222 lines
8.3 KiB
Markdown
222 lines
8.3 KiB
Markdown
# E5 - Debugging and Testing Guide
|
|
|
|
**Last Updated**: December 5, 2025
|
|
**Status**: Active
|
|
|
|
This document provides a comprehensive guide to debugging and testing the `yaze` application. It covers strategies for developers and provides the necessary information for AI agents to interact with, test, and validate the application.
|
|
|
|
---
|
|
|
|
## 1. Standardized Logging for Print Debugging
|
|
|
|
For all print-based debugging, `yaze` uses a structured logging system defined in `util/log.h`. This is the **only** approved method for logging; direct use of `printf` or `std::cout` should be avoided and replaced with the appropriate `LOG_*` macro.
|
|
|
|
### Log Levels and Usage
|
|
|
|
- `LOG_DEBUG(category, "message", ...)`: For verbose, development-only information.
|
|
- `LOG_INFO(category, "message", ...)`: For general, informational messages.
|
|
- `LOG_WARN(category, "message", ...)`: For potential issues that don't break functionality.
|
|
- `LOG_ERROR(category, "message", ...)`: For errors that cause a specific operation to fail.
|
|
|
|
### Log Categories
|
|
|
|
Categories allow you to filter logs to focus on a specific subsystem. Common categories include:
|
|
- `"Main"`
|
|
- `"TestManager"`
|
|
- `"EditorManager"`
|
|
- `"APU"`, `"CPU"`, `"SNES"` (for the emulator)
|
|
|
|
### Enabling and Configuring Logs via CLI
|
|
|
|
You can control logging behavior using command-line flags when launching `yaze` or `yaze_test`.
|
|
|
|
- **Set Log Level & Categories** (allowlist or blocklist by prefixing with `-`; tokens are trimmed and case-sensitive):
|
|
```bash
|
|
./build/bin/yaze --log_level=debug --log_categories="OverworldEditor,-Audio"
|
|
```
|
|
|
|
- **Log to a File (and mirror to console if needed)**:
|
|
```bash
|
|
./build/bin/yaze --log_file=yaze_debug.log --log_to_console
|
|
```
|
|
|
|
- **Enable Verbose Debug Logging** (forces console logging and `debug` level):
|
|
```bash
|
|
./build/bin/yaze --debug --log_file=yaze_debug.log
|
|
```
|
|
|
|
**Best Practice**: When debugging a specific component, add detailed `LOG_DEBUG` statements with a unique category. Then, run `yaze` with the appropriate flags to isolate the output.
|
|
|
|
---
|
|
|
|
## 2. Command-Line Workflows for Testing
|
|
|
|
The `yaze` ecosystem provides several executables and flags to streamline testing and debugging.
|
|
|
|
### Launching the GUI for Specific Tasks
|
|
|
|
- **Load a ROM on Startup**: To immediately test a specific ROM, use the `--rom_file` flag. This bypasses the welcome screen.
|
|
```bash
|
|
./build/bin/yaze --rom_file /path/to/your/zelda3.sfc
|
|
```
|
|
|
|
- **Enable the GUI Test Harness**: To allow the `z3ed` CLI to automate the GUI, you must start `yaze` with the gRPC server enabled.
|
|
```bash
|
|
./build/bin/yaze --rom_file zelda3.sfc --enable_test_harness
|
|
```
|
|
|
|
- **Open a Specific Editor and Panels**: Use `--editor` and `--open_panels` (panel IDs or display names, comma-separated, case-insensitive) to land exactly where you need. Combine with startup visibility flags to hide chrome for automation:
|
|
```bash
|
|
# Open the Dungeon editor with a couple panels pre-visible
|
|
./build/bin/yaze --rom_file zelda3.sfc --editor=Dungeon --open_panels="dungeon.room_list,Room 105"
|
|
|
|
# You can also hide startup chrome for automation runs
|
|
./build/bin/yaze --rom_file zelda3.sfc --editor=Overworld \
|
|
--open_panels="overworld.map_canvas" --startup_welcome=hide --startup_dashboard=hide
|
|
```
|
|
|
|
**Quick Examples**:
|
|
```bash
|
|
# Fast dungeon room testing
|
|
./build/bin/yaze --rom_file=zelda3.sfc --editor=Dungeon --open_panels="Room 0"
|
|
|
|
# Compare multiple rooms side-by-side
|
|
./build/bin/yaze --rom_file=zelda3.sfc --editor=Dungeon --open_panels="Room 0,Room 1,Room 105"
|
|
|
|
# Full dungeon workspace with all tools
|
|
./build/bin/yaze --rom_file=zelda3.sfc --editor=Dungeon \
|
|
--open_panels="Rooms List,Room Matrix,Object Editor,Palette Editor"
|
|
|
|
# Jump straight to overworld editing
|
|
./build/bin/yaze --rom_file=zelda3.sfc --editor=Overworld
|
|
```
|
|
|
|
For a complete reference, see [Startup Debugging Flags](debug-flags.md).
|
|
|
|
### Running Automated C++ Tests
|
|
|
|
The `yaze_test` executable is used to run the project's suite of unit, integration, and E2E tests.
|
|
|
|
- **Run All Tests**:
|
|
```bash
|
|
./build/bin/yaze_test
|
|
```
|
|
|
|
- **Run Specific Categories**:
|
|
```bash
|
|
# Run only fast, dependency-free unit tests
|
|
./build/bin/yaze_test --unit
|
|
|
|
# Run tests that require a ROM file
|
|
./build/bin/yaze_test --rom-dependent --rom-vanilla /path/to/alttp_vanilla.sfc
|
|
```
|
|
|
|
- **Run GUI-based E2E Tests**:
|
|
```bash
|
|
# Run E2E tests and watch the GUI interactions
|
|
./build/bin/yaze_test --e2e --show-gui
|
|
```
|
|
|
|
### Inspecting ROMs with `z3ed`
|
|
|
|
The `z3ed` CLI is a powerful tool for inspecting ROM data without launching the full GUI. This is ideal for quick checks and scripting.
|
|
|
|
- **Get ROM Information**:
|
|
```bash
|
|
z3ed rom info --rom zelda3.sfc
|
|
```
|
|
|
|
- **Inspect Dungeon Sprites**:
|
|
```bash
|
|
z3ed dungeon list-sprites --rom zelda3.sfc --dungeon 2
|
|
```
|
|
|
|
---
|
|
|
|
## 3. GUI Automation for AI Agents
|
|
|
|
The primary way for an AI agent to test its changes and interact with `yaze` is through the GUI automation framework. This system consists of the `yaze` gRPC server (Test Harness) and the `z3ed` CLI client.
|
|
|
|
### Architecture Overview
|
|
|
|
1. **`yaze` (Server)**: When launched with `--enable_test_harness`, it starts a gRPC server that exposes the UI for automation.
|
|
2. **`z3ed` (Client)**: The `z3ed agent test` commands connect to the gRPC server to send commands and receive information.
|
|
3. **AI Agent**: The agent generates `z3ed` commands to drive the UI and verify its actions.
|
|
|
|
### Step-by-Step Workflow for AI
|
|
|
|
#### Step 1: Launch `yaze` with the Test Harness
|
|
|
|
The AI must first ensure the `yaze` GUI is running and ready for automation.
|
|
|
|
```bash
|
|
./build/bin/yaze --rom_file zelda3.sfc --enable_test_harness --test_harness_port 50051
|
|
```
|
|
|
|
#### Step 2: Discover UI Elements
|
|
|
|
Before interacting with the UI, the agent needs to know the stable IDs of the widgets.
|
|
|
|
```bash
|
|
# Discover all widgets in the Dungeon editor window
|
|
z3ed agent test discover --window "Dungeon" --grpc localhost:50051
|
|
```
|
|
This will return a list of widget IDs (e.g., `Dungeon/Canvas/Map`) that can be used in scripts.
|
|
|
|
**Tip**: You can also launch `yaze` with the `--editor` flag to automatically open a specific editor:
|
|
```bash
|
|
./build/bin/yaze --rom_file zelda3.sfc --enable_test_harness --editor=Dungeon --open_panels="Room 0"
|
|
```
|
|
|
|
#### Step 3: Record or Write a Test Script
|
|
|
|
An agent can either generate a test script from scratch or use a pre-recorded one.
|
|
|
|
- **Recording a human interaction**:
|
|
```bash
|
|
z3ed agent test record --suite my_test.jsonl
|
|
```
|
|
- **A generated script might look like this**:
|
|
```json
|
|
// my_test.jsonl
|
|
{"action": "click", "target": "Dungeon/Toolbar/Open Room"}
|
|
{"action": "wait", "duration_ms": 500}
|
|
{"action": "type", "target": "Room Selector/Filter", "text": "Room 105"}
|
|
{"action": "click", "target": "Room Selector/List/Room 105"}
|
|
{"action": "assert_visible", "target": "Room Card 105"}
|
|
```
|
|
|
|
- **Or use startup flags to prepare the environment**:
|
|
```bash
|
|
# Start yaze with the room already open
|
|
./build/bin/yaze --rom_file zelda3.sfc --enable_test_harness \
|
|
--editor=Dungeon --open_panels="Room 105"
|
|
|
|
# Then your test script just needs to validate the state
|
|
{"action": "assert_visible", "target": "Room Card 105"}
|
|
{"action": "assert_visible", "target": "Dungeon/Canvas"}
|
|
```
|
|
|
|
#### Step 4: Replay the Test and Verify
|
|
|
|
The agent executes the script to perform the actions and validate the outcome.
|
|
|
|
```bash
|
|
z3ed agent test replay my_test.jsonl --watch
|
|
```
|
|
The `--watch` flag streams results back to the CLI in real-time. The agent can parse this output to confirm its actions were successful.
|
|
|
|
---
|
|
|
|
## 4. Advanced Debugging Tools
|
|
|
|
For more complex issues, especially within the emulator, `yaze` provides several advanced debugging windows. These are covered in detail in the [Emulator Development Guide](emulator-development-guide.md).
|
|
|
|
- **Disassembly Viewer**: A live, interactive view of the 65816 and SPC700 CPU execution.
|
|
- **Breakpoint Manager**: Set breakpoints on code execution, memory reads, or memory writes.
|
|
- **Memory Viewer**: Inspect WRAM, SRAM, VRAM, and ROM.
|
|
- **APU Inspector**: A dedicated debugger for the audio subsystem.
|
|
- **Event Viewer**: A timeline of all hardware events (NMI, IRQ, DMA).
|
|
|
|
These tools are accessible from the **Debug** menu in the main application.
|