From 3200459c21f239f9bea178dcd757f133e12e3750 Mon Sep 17 00:00:00 2001 From: scawful Date: Sun, 5 Oct 2025 21:01:36 -0400 Subject: [PATCH] docs: Enhance GUI Testing Framework and Introduce z3ed Agent Documentation - Expanded the testing guide with detailed sections on widget registration, state introspection, and integration with AI agents for automated testing. - Added a new comprehensive readme for the z3ed agent, outlining its architecture, capabilities, and quick start instructions for AI-driven ROM hacking. - Updated the changelog to reflect recent enhancements in GUI and UX, including a theme system and modular architecture for the Overworld Editor. - Removed outdated networking documentation to streamline resources and improve clarity. --- docs/A1-testing-guide.md | 74 +++++++++++++++++-- .../README.md => A2-z3ed-agent-readme.md} | 0 docs/C1-changelog.md | 18 +++++ docs/index.md | 2 + docs/{z3ed/NETWORKING.md => networking.md} | 2 +- 5 files changed, 89 insertions(+), 7 deletions(-) rename docs/{z3ed/README.md => A2-z3ed-agent-readme.md} (100%) rename docs/{z3ed/NETWORKING.md => networking.md} (99%) diff --git a/docs/A1-testing-guide.md b/docs/A1-testing-guide.md index 6b184fe8..f0457eca 100644 --- a/docs/A1-testing-guide.md +++ b/docs/A1-testing-guide.md @@ -176,6 +176,26 @@ An agent-friendly, end-to-end testing framework built on `ImGuiTestEngine` to au - `test/e2e/canvas_selection_test.cc` - Canvas interaction tests - `test/test_utils.h` - High-level action wrappers (LoadRomInTest, OpenEditorInTest, etc.) +### Widget Registration for Automation + +All modern UI components are fully integrated with the ImGui Test Engine for seamless automation. + +**Toolbar Components:** +All toolbar buttons are automatically registered with descriptive paths: +- `ModeButton:Pan (1)` +- `ModeButton:Draw (2)` +- `ToolbarAction:Toggle Tile16 Selector` +- `ToolbarAction:Open Tile16 Editor` + +**Editor Cards:** +All EditorCard windows are registered as discoverable windows: +- `EditorCard:Tile16 Selector` +- `EditorCard:Area Graphics` + +**State Introspection:** +Card visibility states are tracked for test automation: +- `OverworldToolbar/state:tile16_selector_visible` + ### Writing E2E Tests ```cpp @@ -202,15 +222,57 @@ void RegisterCanvasSelectionTest() { } ``` -### Running GUI Tests +### Running GUI Tests with `z3ed` + +The `z3ed` CLI provides a powerful interface for running GUI tests. ```bash # Run all E2E tests -z3ed test-gui --rom zelda3.sfc --test all +z3ed gui replay --ci-mode -# Run specific test suite -z3ed test-gui --rom zelda3.sfc --test canvas_selection +# Run a specific test suite from a YAML file +z3ed gui replay test_overworld_workflow.yaml --ci-mode -# Run in headless mode (CI) -z3ed test-gui --rom zelda3.sfc --test all --headless +# Click a specific button +z3ed gui click "ModeButton:Draw (2)" + +# Wait for a window to become visible +z3ed gui wait "window_visible:Tile16 Selector" + +# Assert that a card is visible +z3ed gui assert "visible:EditorCard:Tile16 Selector" ``` + +### Widget Discovery + +You can discover all registered UI elements for scripting and testing. + +```bash +# List all widgets in the Overworld window +z3ed gui discover --window="Overworld" --format=yaml > overworld_widgets.yaml + +# Find all toolbar actions +z3ed gui discover --path-prefix="ToolbarAction:" + +# Find all editor cards +z3ed gui discover --path-prefix="EditorCard:" +``` + +### Integration with AI Agent + +The agent can leverage the GUI testing framework to perform actions. + +1. **Discover UI Elements**: `Agent> describe gui` +2. **Interact with UI**: `Agent> click toolbar button "Toggle Tile16 Selector"` +3. **Monitor State**: `Agent> check if "Tile16 Selector" is visible` + +### Visual Testing + +For vision-based testing, overworld entities are rendered with high-visibility colors: +- **Entrances**: Bright yellow-gold +- **Exits**: Cyan-white +- **Items**: Bright red +- **Sprites**: Bright magenta + +### Performance +Widget registration has zero runtime overhead, using efficient hash map lookups and automatic cleanup of stale widgets. \ No newline at end of file diff --git a/docs/z3ed/README.md b/docs/A2-z3ed-agent-readme.md similarity index 100% rename from docs/z3ed/README.md rename to docs/A2-z3ed-agent-readme.md diff --git a/docs/C1-changelog.md b/docs/C1-changelog.md index 188474f5..73183936 100644 --- a/docs/C1-changelog.md +++ b/docs/C1-changelog.md @@ -1,5 +1,23 @@ # Changelog +## 0.3.3 (October 2025) + +### GUI & UX Modernization +- **Theme System**: Implemented a comprehensive theme system (`AgentUITheme`) that centralizes all UI colors. All Agent UI components are now theme-aware, deriving colors from the main application theme. +- **UI Helper Library**: Created a library of 30+ reusable UI helper functions (`AgentUI::*` and `gui::*`) to standardize panel styles, section headers, status indicators, and buttons, reducing boilerplate code by over 50%. +- **Visual Polish**: Enhanced numerous UI panels (Agent Chat, Test Harness, Collaboration) with theme-aware colors, status badges (PASS/FAIL/RUN), connection indicators, and provider badges (Ollama/Gemini). + +### Overworld Editor Refactoring +- **Modular Architecture**: Refactored the 3,400-line `OverworldEditor` into smaller, focused modules, including `OverworldEntityRenderer`. +- **Progressive Loading**: Implemented a priority-based progressive loading system in the central `gfx::Arena` to prevent UI freezes during asset loading. This benefits all editors. +- **Critical Graphics Fixes**: Resolved major bugs related to graphics not refreshing immediately, multi-quadrant map updates, and incorrect feature visibility on vanilla ROMs. +- **Multi-Area Map Configuration**: Implemented a robust `ConfigureMultiAreaMap()` method to correctly handle parent/child relationships for all area sizes (Small, Large, Wide, Tall). + +### Build System & Stability +- **Build Fixes**: Resolved 7 critical build errors, including linker issues, missing virtual methods, and filesystem crashes. +- **C API Separation**: Decoupled the C API library from the main application to improve build modularity. + + ## 0.3.2 (December 2025) - In Development ### Tile16 Editor Improvements (In Progress) diff --git a/docs/index.md b/docs/index.md index 8b4588b6..bec02572 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,6 +10,8 @@ Welcome to the official documentation for yaze, a comprehensive ROM editor for T ## Development & API +- [Development Guide](development_guide.md) - Core architectural patterns, UI systems, and best practices. +- [GUI Testing Guide](gui_testing.md) - The end-to-end GUI testing framework. - [API Reference](04-api-reference.md) - C/C++ API documentation for extensions. - [Testing Guide](A1-testing-guide.md) - The testing framework and best practices. - [Assembly Style Guide](E1-asm-style-guide.md) - 65816 assembly coding standards. diff --git a/docs/z3ed/NETWORKING.md b/docs/networking.md similarity index 99% rename from docs/z3ed/NETWORKING.md rename to docs/networking.md index 875e5206..9158e94a 100644 --- a/docs/z3ed/NETWORKING.md +++ b/docs/networking.md @@ -207,4 +207,4 @@ z3ed net proposal status --id prop_123 - **Automatic reconnection with exponential backoff** - **Connection pooling for multiple sessions** - **NAT traversal for home networks** -- **End-to-end encryption for proposals** \ No newline at end of file +- **End-to-end encryption for proposals**