scawful/yaze
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update ROM test paths and envs

Browse Source
This commit is contained in:
scawful
2025-12-22 14:50:57 -05:00
parent 42ae359abc
commit 319e903f24
22 changed files with 102 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/internal/agents/cli-ux-proposals.md
View File

@@ -72,7 +72,7 @@ Board: docs/internal/agents/coordination-board.md (2025-12-01 ai-infra-architect
- Agent-side test commands (`agent test run/list/status/...`) print ad-hoc logs and lack `OutputFormatter`/metadata, making automation fragile; no JSON status, exit codes, or artifacts paths surfaced. - Agent-side test commands (`agent test run/list/status/...`) print ad-hoc logs and lack `OutputFormatter`/metadata, making automation fragile; no JSON status, exit codes, or artifacts paths surfaced.
- Test helper tools (`tools-*/` commands, `tools/test_helpers/*`) mix stdout banners with file emission and manual path requirements; they are not discoverable via TUI or CommandRegistry-driven palettes and do not expose dry-run/plan outputs. - Test helper tools (`tools-*/` commands, `tools/test_helpers/*`) mix stdout banners with file emission and manual path requirements; they are not discoverable via TUI or CommandRegistry-driven palettes and do not expose dry-run/plan outputs.
- TUI/editor have no test surface: no panel to run `stable/gui/rom_dependent/experimental` suites, inspect failing cases, or attach ROM paths/presets; quick actions and history are missing. - TUI/editor have no test surface: no panel to run `stable/gui/rom_dependent/experimental` suites, inspect failing cases, or attach ROM paths/presets; quick actions and history are missing.
- Build/preset coupling is implicit—no guided flow to pick `mac-test/mac-ai/mac-dev`, enable ROM/AI flags, or attach `YAZE_TEST_ROM_PATH`; agents/humans can misconfigure and get empty test sets. - Build/preset coupling is implicit—no guided flow to pick `mac-test/mac-ai/mac-dev`, enable ROM/AI flags, or attach `YAZE_TEST_ROM_VANILLA`; agents/humans can misconfigure and get empty test sets.
### Proposed Improvements ### Proposed Improvements
- **Unified test CLI/TUI API** - **Unified test CLI/TUI API**

2
docs/internal/agents/tests-binary-ux-proposals.md
View File

@@ -22,7 +22,7 @@ Board: docs/internal/agents/coordination-board.md (2025-12-01 ai-infra-architect
## Improvement Proposals ## Improvement Proposals
- **Manifest & discovery**: Generate a JSON manifest (per build) listing tests, labels, requirements (ROM path, AI runtime), and expected artifacts. Expose via `yaze_test --export-manifest <path>` and `ctest -T mem`-style option. Agents can load it instead of scraping. - **Manifest & discovery**: Generate a JSON manifest (per build) listing tests, labels, requirements (ROM path, AI runtime), and expected artifacts. Expose via `yaze_test --export-manifest <path>` and `ctest -T mem`-style option. Agents can load it instead of scraping.
- **Structured output**: Add `--output-format {text,json,junit}` to `yaze_test` to emit summaries (pass/fail, duration, seed, artifacts) in one file; default to text for humans, JSON for automation. Wire ctest to collect the JSON and place it in a predictable directory. - **Structured output**: Add `--output-format {text,json,junit}` to `yaze_test` to emit summaries (pass/fail, duration, seed, artifacts) in one file; default to text for humans, JSON for automation. Wire ctest to collect the JSON and place it in a predictable directory.
- **Requirements gating**: On startup, detect missing ROM/AI/headless support and fail fast with actionable messages and suggested CMake flags/env (e.g., `YAZE_ENABLE_ROM_TESTS`, `YAZE_TEST_ROM_PATH`). Offer a `--mock-rom-ok` mode to downgrade ROM tests when a mock is acceptable. - **Requirements gating**: On startup, detect missing ROM/AI/headless support and fail fast with actionable messages and suggested CMake flags/env (e.g., `YAZE_ENABLE_ROM_TESTS`, `YAZE_TEST_ROM_VANILLA`). Offer a `--mock-rom-ok` mode to downgrade ROM tests when a mock is acceptable.
- **Filters & subsets**: Provide a unified front-end flag set (`--label stable|gui|rom_dependent|experimental`, `--gtest_filter`, `--list`) that internally routes to gtest/labels so humans/agents don’t guess. Add `--shard <N/M>` for parallel runs. - **Filters & subsets**: Provide a unified front-end flag set (`--label stable|gui|rom_dependent|experimental`, `--gtest_filter`, `--list`) that internally routes to gtest/labels so humans/agents don’t guess. Add `--shard <N/M>` for parallel runs.
- **Artifacts & logs**: Standardize artifact output location (`build/artifacts/tests/<run-id>/`) and name failing-test logs/screenshots accordingly. Emit paths in JSON output. Ensure GUI/agent recordings are captured when labels include `gui` or `experimental`. - **Artifacts & logs**: Standardize artifact output location (`build/artifacts/tests/<run-id>/`) and name failing-test logs/screenshots accordingly. Emit paths in JSON output. Ensure GUI/agent recordings are captured when labels include `gui` or `experimental`.
- **Preset hints**: Print which CMake preset was used to build the binary and whether ROM/AI options are compiled in. Add `--recommend-preset` helper to suggest `mac-test/mac-ai/mac-dev` based on requested labels. - **Preset hints**: Print which CMake preset was used to build the binary and whether ROM/AI options are compiled in. Add `--recommend-preset` helper to suggest `mac-test/mac-ai/mac-dev` based on requested labels.

2
docs/internal/architecture/configuration_matrix.md
View File

@@ -44,7 +44,7 @@ This document defines all CMake configuration flags, their interactions, and the
| Flag | Default | Purpose | Notes | | Flag | Default | Purpose | Notes |
|------|---------|---------|-------| |------|---------|---------|-------|
| `YAZE_ENABLE_ROM_TESTS` | OFF | Enable ROM-dependent tests | Requires `zelda3.sfc` file | | `YAZE_ENABLE_ROM_TESTS` | OFF | Enable ROM-dependent tests | Requires vanilla ROM (`alttp_vanilla.sfc`) via `YAZE_TEST_ROM_VANILLA` |
| `YAZE_MINIMAL_BUILD` | OFF | Minimal CI build (skip optional features) | Used in resource-constrained CI | | `YAZE_MINIMAL_BUILD` | OFF | Minimal CI build (skip optional features) | Used in resource-constrained CI |
| `YAZE_SUPPRESS_WARNINGS` | ON | Suppress compiler warnings | Use OFF for verbose builds | | `YAZE_SUPPRESS_WARNINGS` | ON | Suppress compiler warnings | Use OFF for verbose builds |

6
docs/internal/debug/audio-debugging-quick-ref.md
View File

@@ -21,7 +21,7 @@ Before investigating audio issues, verify these values are correct:
# Build with ROM tests enabled # Build with ROM tests enabled
cmake --preset mac-dbg \ cmake --preset mac-dbg \
-DYAZE_ENABLE_ROM_TESTS=ON \ -DYAZE_ENABLE_ROM_TESTS=ON \
-DYAZE_TEST_ROM_PATH=~/zelda3.sfc -DYAZE_TEST_ROM_VANILLA_PATH=~/roms/alttp_vanilla.sfc
cmake --build --preset mac-dbg cmake --build --preset mac-dbg
@@ -29,7 +29,7 @@ cmake --build --preset mac-dbg
ctest --test-dir build -L audio -V ctest --test-dir build -L audio -V
# Run specific test with verbose output # Run specific test with verbose output
YAZE_TEST_ROM_PATH=~/zelda3.sfc ./build/bin/Debug/yaze_test_rom_dependent \ YAZE_TEST_ROM_VANILLA=~/roms/alttp_vanilla.sfc ./build/bin/Debug/yaze_test_rom_dependent \
--gtest_filter="*AudioTiming*" 2>&1 | tee audio_debug.log --gtest_filter="*AudioTiming*" 2>&1 | tee audio_debug.log
# Generate timing report # Generate timing report
@@ -101,7 +101,7 @@ Start yaze with debug flags for audio investigation:
```bash ```bash
./yaze --debug --log_file=audio_debug.log \ ./yaze --debug --log_file=audio_debug.log \
--rom_file=zelda3.sfc --editor=Music --rom_file=roms/alttp_vanilla.sfc --editor=Music
``` ```
## Test Output Files ## Test Output Files

8
docs/internal/testing/README.md
View File

@@ -65,7 +65,7 @@ cmake --build build --target yaze_test
./build/bin/yaze_test --integration ./build/bin/yaze_test --integration
# Run with ROM-dependent tests # Run with ROM-dependent tests
./build/bin/yaze_test --integration --rom-dependent --rom-path zelda3.sfc ./build/bin/yaze_test --integration --rom-dependent --rom-vanilla roms/alttp_vanilla.sfc
``` ```
**Coverage Areas**: **Coverage Areas**:
@@ -159,7 +159,7 @@ scripts/agents/run-tests.sh mac-dbg --output-on-failure
./build/bin/yaze_test ./build/bin/yaze_test
# Run all tests including ROM-dependent # Run all tests including ROM-dependent
./build/bin/yaze_test --rom-dependent --rom-path zelda3.sfc ./build/bin/yaze_test --rom-dependent --rom-vanilla roms/alttp_vanilla.sfc
# Alternative: use ctest with preset # Alternative: use ctest with preset
ctest --preset dev ctest --preset dev
@@ -300,10 +300,10 @@ Common helpers in `test/test_utils.h`:
**Solution**: **Solution**:
```bash ```bash
# Set ROM path environment variable # Set ROM path environment variable
export YAZE_TEST_ROM_PATH=/path/to/zelda3.sfc export YAZE_TEST_ROM_VANILLA=/path/to/alttp_vanilla.sfc
# Or pass directly # Or pass directly
./build/bin/yaze_test --rom-path /path/to/zelda3.sfc ./build/bin/yaze_test --rom-vanilla /path/to/alttp_vanilla.sfc
``` ```
#### 2. GUI Test Failures in CI #### 2. GUI Test Failures in CI

13
docs/internal/testing/configuration.md
View File

@@ -12,7 +12,9 @@ The yaze test suite has been reorganized to improve CI performance and developer
| `YAZE_ENABLE_ROM_TESTS` | **OFF** | Enable tests requiring ROM files | ROM-dependent tests | | `YAZE_ENABLE_ROM_TESTS` | **OFF** | Enable tests requiring ROM files | ROM-dependent tests |
| `YAZE_ENABLE_AI_RUNTIME` | **OFF** | Enable AI runtime integration tests | Experimental AI tests | | `YAZE_ENABLE_AI_RUNTIME` | **OFF** | Enable AI runtime integration tests | Experimental AI tests |
| `YAZE_ENABLE_BENCHMARK_TESTS` | **OFF** | Enable performance benchmarks | Benchmark suite | | `YAZE_ENABLE_BENCHMARK_TESTS` | **OFF** | Enable performance benchmarks | Benchmark suite |
| `YAZE_TEST_ROM_PATH` | `build/bin/zelda3.sfc` | Path to test ROM file | ROM-dependent tests | | `YAZE_TEST_ROM_VANILLA_PATH` | *(empty)* | Path to vanilla test ROM file | ROM-dependent tests |
| `YAZE_TEST_ROM_EXPANDED_PATH` | *(empty)* | Path to expanded test ROM file | Expanded ROM tests |
| `YAZE_TEST_ROM_PATH` | *(legacy)* | Legacy vanilla ROM path | ROM-dependent tests |
## Test Categories and Labels ## Test Categories and Labels
@@ -65,7 +67,7 @@ ctest --test-dir build -L stable
### With ROM-Dependent Tests ### With ROM-Dependent Tests
```bash ```bash
# Configure with ROM tests enabled # Configure with ROM tests enabled
cmake --preset mac-dbg -DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_PATH=~/zelda3.sfc cmake --preset mac-dbg -DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_VANILLA_PATH=~/roms/alttp_vanilla.sfc
cmake --build build cmake --build build
ctest --test-dir build -L rom_dependent ctest --test-dir build -L rom_dependent
``` ```
@@ -97,7 +99,8 @@ cmake --preset mac-dbg \
-DYAZE_ENABLE_ROM_TESTS=ON \ -DYAZE_ENABLE_ROM_TESTS=ON \
-DYAZE_ENABLE_AI_RUNTIME=ON \ -DYAZE_ENABLE_AI_RUNTIME=ON \
-DYAZE_ENABLE_BENCHMARK_TESTS=ON \ -DYAZE_ENABLE_BENCHMARK_TESTS=ON \
-DYAZE_TEST_ROM_PATH=~/zelda3.sfc -DYAZE_TEST_ROM_VANILLA_PATH=~/roms/alttp_vanilla.sfc \
-DYAZE_TEST_ROM_EXPANDED_PATH=~/roms/oos168.sfc
cmake --build build cmake --build build
ctest --test-dir build ctest --test-dir build
``` ```
@@ -194,6 +197,6 @@ Ensure:
### ROM Tests Failing ### ROM Tests Failing
Verify: Verify:
- ROM file exists at `YAZE_TEST_ROM_PATH` - ROM file exists at `YAZE_TEST_ROM_VANILLA` (or `YAZE_TEST_ROM_EXPANDED` for v3 tests)
- ROM is valid Zelda3 US version - ROM is valid Zelda3 US version
- Path is absolute, not relative - Path is absolute, not relative

2
docs/internal/testing/dungeon-gui-test-design.md
View File

@@ -82,7 +82,7 @@ void E2ETest_DungeonEditor_PlaceSingleObject(ImGuiTestContext* ctx) {
ctx->LogInfo("=== Test: Place Single Object on Canvas ==="); ctx->LogInfo("=== Test: Place Single Object on Canvas ===");
// Setup // Setup
gui::LoadRomInTest(ctx, "zelda3.sfc"); gui::LoadRomInTest(ctx, yaze::test::TestRomManager::GetTestRomPath());
gui::OpenEditorInTest(ctx, "Dungeon"); gui::OpenEditorInTest(ctx, "Dungeon");
ctx->Yield(20); ctx->Yield(20);

19
docs/internal/testing/overview.md
View File

@@ -69,7 +69,7 @@ These tests are disabled in PR/Push CI but run in nightly builds for comprehensi
**Requirements to Run Locally:** **Requirements to Run Locally:**
- CMake flag: `-DYAZE_ENABLE_ROM_TESTS=ON` - CMake flag: `-DYAZE_ENABLE_ROM_TESTS=ON`
- ROM path: `-DYAZE_TEST_ROM_PATH=/path/to/zelda3.sfc` - ROM path: `-DYAZE_TEST_ROM_VANILLA_PATH=/path/to/alttp_vanilla.sfc`
- Use `mac-dev`, `lin-dev`, `win-dev` presets or configure manually - Use `mac-dev`, `lin-dev`, `win-dev` presets or configure manually
**Contents:** **Contents:**
@@ -79,7 +79,7 @@ These tests are disabled in PR/Push CI but run in nightly builds for comprehensi
**Run with:** **Run with:**
```bash ```bash
cmake --preset mac-dev -DYAZE_TEST_ROM_PATH=~/zelda3.sfc cmake --preset mac-dev -DYAZE_TEST_ROM_VANILLA_PATH=~/roms/alttp_vanilla.sfc
ctest --test-dir build -L rom_dependent ctest --test-dir build -L rom_dependent
``` ```
@@ -246,7 +246,7 @@ ctest --test-dir build -L "stable|gui" -j4
# Configure with ROM # Configure with ROM
cmake --preset mac-dbg \ cmake --preset mac-dbg \
-DYAZE_ENABLE_ROM_TESTS=ON \ -DYAZE_ENABLE_ROM_TESTS=ON \
-DYAZE_TEST_ROM_PATH=~/zelda3.sfc -DYAZE_TEST_ROM_VANILLA_PATH=~/roms/alttp_vanilla.sfc
# Build ROM test suite # Build ROM test suite
cmake --build --preset mac-dbg --target yaze_test_rom_dependent cmake --build --preset mac-dbg --target yaze_test_rom_dependent
@@ -332,7 +332,7 @@ TEST(NewFeatureTest, BasicFunctionality) {
1. Create file: `test/integration/new_feature_test.cc` 1. Create file: `test/integration/new_feature_test.cc`
2. Same pattern as unit tests 2. Same pattern as unit tests
3. May access ROM files via `YAZE_TEST_ROM_PATH` 3. May access ROM files via `YAZE_TEST_ROM_VANILLA` or `TestRomManager`
4. Automatically labeled as `stable` (unless in special subdirectory) 4. Automatically labeled as `stable` (unless in special subdirectory)
### Adding ROM-Dependent Test ### Adding ROM-Dependent Test
@@ -345,7 +345,8 @@ TEST(NewFeatureTest, BasicFunctionality) {
```cpp ```cpp
#ifdef YAZE_ENABLE_ROM_TESTS #ifdef YAZE_ENABLE_ROM_TESTS
TEST(MyRomTest, EditAndSave) { TEST(MyRomTest, EditAndSave) {
const char* rom_path = YAZE_TEST_ROM_PATH; const std::string rom_path =
yaze::test::TestRomManager::GetRomPath(yaze::test::RomRole::kVanilla);
// ... ROM testing code // ... ROM testing code
} }
#endif #endif
@@ -370,7 +371,9 @@ TEST(MyRomTest, EditAndSave) {
#include "imgui_te_engine.h" #include "imgui_te_engine.h"
void E2ETest_MyGuiWorkflow(ImGuiTestContext* ctx) { void E2ETest_MyGuiWorkflow(ImGuiTestContext* ctx) {
yaze::test::gui::LoadRomInTest(ctx, "zelda3.sfc"); const std::string rom_path =
yaze::test::TestRomManager::GetRomPath(yaze::test::RomRole::kVanilla);
yaze::test::gui::LoadRomInTest(ctx, rom_path);
// ... GUI test code // ... GUI test code
} }
@@ -430,8 +433,8 @@ If ROM tests fail:
```bash ```bash
# Verify ROM path is correct # Verify ROM path is correct
echo $YAZE_TEST_ROM_PATH echo $YAZE_TEST_ROM_VANILLA
file ~/zelda3.sfc file ~/roms/alttp_vanilla.sfc
# Check ROM-dependent tests are enabled # Check ROM-dependent tests are enabled
cmake . | grep YAZE_ENABLE_ROM_TESTS cmake . | grep YAZE_ENABLE_ROM_TESTS

8
docs/public/cli/test-commands.md
View File

@@ -152,6 +152,8 @@ z3ed test-status --format json
### Sample Output (JSON) ### Sample Output (JSON)
```json ```json
{ {
"rom_vanilla": "not set",
"rom_expanded": "not set",
"rom_path": "not set", "rom_path": "not set",
"skip_rom_tests": false, "skip_rom_tests": false,
"ui_tests_enabled": false, "ui_tests_enabled": false,
@@ -167,7 +169,9 @@ The test commands respect these environment variables:
| Variable | Description | | Variable | Description |
|----------|-------------| |----------|-------------|
| `YAZE_TEST_ROM_PATH` | Path to Zelda3 ROM for ROM-dependent tests | | `YAZE_TEST_ROM_VANILLA` | Path to vanilla Zelda3 ROM for ROM-dependent tests |
| `YAZE_TEST_ROM_EXPANDED` | Path to expanded Zelda3 ROM (ZSCustom/OOS) |
| `YAZE_TEST_ROM_PATH` | Legacy ROM path (vanilla fallback) |
| `YAZE_SKIP_ROM_TESTS` | Set to `1` to skip ROM tests | | `YAZE_SKIP_ROM_TESTS` | Set to `1` to skip ROM tests |
| `YAZE_ENABLE_UI_TESTS` | Set to `1` to enable UI tests | | `YAZE_ENABLE_UI_TESTS` | Set to `1` to enable UI tests |
@@ -200,7 +204,7 @@ if [ $? -eq 0 ]; then echo "All tests passed"; fi
### With ROM Tests ### With ROM Tests
```bash ```bash
# Set ROM path # Set ROM path
export YAZE_TEST_ROM_PATH=/path/to/zelda3.sfc export YAZE_TEST_ROM_VANILLA=/path/to/alttp_vanilla.sfc
# Configure with ROM tests enabled # Configure with ROM tests enabled
cmake --preset mac-dev -DYAZE_ENABLE_ROM_TESTS=ON cmake --preset mac-dev -DYAZE_ENABLE_ROM_TESTS=ON

2
docs/public/developer/debugging-guide.md
View File

@@ -108,7 +108,7 @@ The `yaze_test` executable is used to run the project's suite of unit, integrati
./build/bin/yaze_test --unit ./build/bin/yaze_test --unit
# Run tests that require a ROM file # Run tests that require a ROM file
./build/bin/yaze_test --rom-dependent --rom-path /path/to/zelda3.sfc ./build/bin/yaze_test --rom-dependent --rom-vanilla /path/to/alttp_vanilla.sfc
``` ```
- **Run GUI-based E2E Tests**: - **Run GUI-based E2E Tests**:

4
docs/public/developer/testing-guide.md
View File

@@ -78,7 +78,7 @@ cmake --build build --target yaze_test
./build/bin/yaze_test --e2e --show-gui ./build/bin/yaze_test --e2e --show-gui
# Run ROM-dependent tests # Run ROM-dependent tests
./build/bin/yaze_test --rom-dependent --rom-path /path/to/zelda3.sfc ./build/bin/yaze_test --rom-dependent --rom-vanilla /path/to/alttp_vanilla.sfc
# Run by pattern # Run by pattern
./build/bin/yaze_test "*Asar*" ./build/bin/yaze_test "*Asar*"
@@ -91,7 +91,7 @@ cmake --build build --target yaze_test
```bash ```bash
# Configure with ROM tests # Configure with ROM tests
cmake --preset mac-dev -DYAZE_TEST_ROM_PATH=/path/to/zelda3.sfc cmake --preset mac-dev -DYAZE_TEST_ROM_VANILLA_PATH=/path/to/alttp_vanilla.sfc
# Build # Build
cmake --build --preset mac-dev --target yaze_test cmake --build --preset mac-dev --target yaze_test

13
docs/public/developer/testing-quick-start.md
View File

@@ -66,8 +66,8 @@ Run the **complete test suite** before pushing if:
# Run all tests (may take 5+ minutes) # Run all tests (may take 5+ minutes)
./build/bin/yaze_test ./build/bin/yaze_test
# Include ROM-dependent tests (requires zelda3.sfc) # Include ROM-dependent tests (requires alttp_vanilla.sfc)
./build/bin/yaze_test --rom-dependent --rom-path /path/to/zelda3.sfc ./build/bin/yaze_test --rom-dependent --rom-vanilla /path/to/alttp_vanilla.sfc
# Run E2E GUI tests (headless) # Run E2E GUI tests (headless)
./build/bin/yaze_test --e2e ./build/bin/yaze_test --e2e
@@ -107,10 +107,10 @@ cmake --build build --target yaze_test
**Fix**: **Fix**:
```bash ```bash
# Set environment variable # Set environment variable
export YAZE_TEST_ROM_PATH=/path/to/zelda3.sfc export YAZE_TEST_ROM_VANILLA=/path/to/alttp_vanilla.sfc
# Or pass directly to test runner # Or pass directly to test runner
./build/bin/yaze_test --rom-path /path/to/zelda3.sfc ./build/bin/yaze_test --rom-vanilla /path/to/alttp_vanilla.sfc
``` ```
### 4. E2E/GUI Test Failures ### 4. E2E/GUI Test Failures
@@ -177,7 +177,7 @@ git push
```bash ```bash
# Run everything including ROM tests and E2E # Run everything including ROM tests and E2E
./build/bin/yaze_test --rom-dependent --rom-path zelda3.sfc ./build/bin/yaze_test --rom-dependent --rom-vanilla roms/alttp_vanilla.sfc
./build/bin/yaze_test --e2e ./build/bin/yaze_test --e2e
# Check code formatting # Check code formatting
@@ -238,7 +238,8 @@ Customize test behavior with these environment variables:
```bash ```bash
# Path to test ROM file # Path to test ROM file
export YAZE_TEST_ROM_PATH=/path/to/zelda3.sfc export YAZE_TEST_ROM_VANILLA=/path/to/alttp_vanilla.sfc
export YAZE_TEST_ROM_EXPANDED=/path/to/oos168.sfc
# Skip ROM-dependent tests entirely # Skip ROM-dependent tests entirely
export YAZE_SKIP_ROM_TESTS=1 export YAZE_SKIP_ROM_TESTS=1

4
docs/public/reference/changelog.md
View File

@@ -20,8 +20,8 @@
**ROM Auto-Discovery**: **ROM Auto-Discovery**:
- Tests now automatically discover ROMs in common locations (roms/, ../roms/, etc.) - Tests now automatically discover ROMs in common locations (roms/, ../roms/, etc.)
- Searches for common filenames: zelda3.sfc, alttp_vanilla.sfc, vanilla.sfc - Searches for common vanilla filenames: alttp_vanilla.sfc, Legend of Zelda, The - A Link to the Past (USA).sfc
- Environment variable `YAZE_TEST_ROM_PATH` still takes precedence if set - Legacy environment variable `YAZE_TEST_ROM_PATH` is still supported as a fallback
**Overworld Regression Tests**: **Overworld Regression Tests**:
- Added 9 new regression tests for save function version checks - Added 9 new regression tests for save function version checks

2
scripts/README.md
View File

@@ -122,7 +122,7 @@ The script intelligently preserves conditional blocks (if/endif) and excludes co
- Check for `clang-cl`, Ninja, NASM, Visual Studio workloads, and VS Code (optional). - Check for `clang-cl`, Ninja, NASM, Visual Studio workloads, and VS Code (optional).
- Validate vcpkg bootstrap status plus `vcpkg/installed` cache contents. - Validate vcpkg bootstrap status plus `vcpkg/installed` cache contents.
- Warn about missing ROM assets (`zelda3.sfc`, `assets/zelda3.sfc`, etc.). - Warn about missing ROM assets (`roms/alttp_vanilla.sfc`, etc.).
- Offer `-FixIssues` and `-CleanCache` switches to repair Git config, resync submodules, and wipe stale build directories. - Offer `-FixIssues` and `-CleanCache` switches to repair Git config, resync submodules, and wipe stale build directories.
Run the script once per machine (and rerun after major toolchain updates) to ensure presets such as `win-dbg`, `win-ai`, `mac-ai`, and `ci-windows-ai` have everything they need. Run the script once per machine (and rerun after major toolchain updates) to ensure presets such as `win-dbg`, `win-ai`, `mac-ai`, and `ci-windows-ai` have everything they need.

9
scripts/run_overworld_tests.sh
View File

@@ -89,9 +89,9 @@ Options:
--cleanup Clean up test files after completion --cleanup Clean up test files after completion
Examples: Examples:
$0 zelda3.sfc $0 roms/alttp_vanilla.sfc
$0 zelda3.sfc --generate-report --cleanup $0 roms/alttp_vanilla.sfc --generate-report --cleanup
$0 /path/to/rom.sfc --skip-unit-tests $0 /path/to/alttp_vanilla.sfc --skip-unit-tests
EOF EOF
} }
@@ -233,6 +233,7 @@ run_unit_tests() {
cd "$PROJECT_ROOT" cd "$PROJECT_ROOT"
# Set environment variable for ROM path # Set environment variable for ROM path
export YAZE_TEST_ROM_VANILLA="$ROM_PATH"
export YAZE_TEST_ROM_PATH="$ROM_PATH" export YAZE_TEST_ROM_PATH="$ROM_PATH"
# Run unit tests # Run unit tests
@@ -258,6 +259,7 @@ run_integration_tests() {
cd "$PROJECT_ROOT" cd "$PROJECT_ROOT"
# Set environment variable for ROM path # Set environment variable for ROM path
export YAZE_TEST_ROM_VANILLA="$ROM_PATH"
export YAZE_TEST_ROM_PATH="$ROM_PATH" export YAZE_TEST_ROM_PATH="$ROM_PATH"
# Run integration tests # Run integration tests
@@ -283,6 +285,7 @@ run_e2e_tests() {
cd "$PROJECT_ROOT" cd "$PROJECT_ROOT"
# Set environment variable for ROM path # Set environment variable for ROM path
export YAZE_TEST_ROM_VANILLA="$ROM_PATH"
export YAZE_TEST_ROM_PATH="$ROM_PATH" export YAZE_TEST_ROM_PATH="$ROM_PATH"
# Run E2E tests # Run E2E tests

6
scripts/test_ai_features.ps1
View File

@@ -4,11 +4,15 @@
param( param(
[string]$YazeBin = "build-windows\bin\Debug\yaze.exe", [string]$YazeBin = "build-windows\bin\Debug\yaze.exe",
[string]$Z3edBin = "build-windows\bin\Debug\z3ed.exe", [string]$Z3edBin = "build-windows\bin\Debug\z3ed.exe",
[string]$TestRom = "zelda3.sfc" [string]$TestRom = $env:YAZE_TEST_ROM_VANILLA
) )
$ErrorActionPreference = "Continue" $ErrorActionPreference = "Continue"
if (-not $TestRom) {
$TestRom = "roms\alttp_vanilla.sfc"
}
function Write-Header { function Write-Header {
Write-Host "`n╔════════════════════════════════════════════════════════════════╗" -ForegroundColor Cyan Write-Host "`n╔════════════════════════════════════════════════════════════════╗" -ForegroundColor Cyan
Write-Host "║ YAZE AI Features Test Suite (Windows) ║" -ForegroundColor Cyan Write-Host "║ YAZE AI Features Test Suite (Windows) ║" -ForegroundColor Cyan

2
scripts/test_ai_features.sh
View File

@@ -15,7 +15,7 @@ NC='\033[0m'
# Configuration # Configuration
YAZE_BIN="${YAZE_BIN:-./build/bin/yaze}" YAZE_BIN="${YAZE_BIN:-./build/bin/yaze}"
Z3ED_BIN="${Z3ED_BIN:-./build/bin/z3ed}" Z3ED_BIN="${Z3ED_BIN:-./build/bin/z3ed}"
TEST_ROM="${TEST_ROM:-./zelda3.sfc}" TEST_ROM="${TEST_ROM:-${YAZE_TEST_ROM_VANILLA:-./roms/alttp_vanilla.sfc}}"
GEMINI_API_KEY="${GEMINI_API_KEY:-}" GEMINI_API_KEY="${GEMINI_API_KEY:-}"
SCREENSHOTS_DIR="./test_screenshots" SCREENSHOTS_DIR="./test_screenshots"

5
scripts/test_dungeon_loading.sh
View File

@@ -5,7 +5,7 @@
set -e set -e
# Configuration # Configuration
ROM_FILE="${1:-zelda3.sfc}" ROM_FILE="${1:-roms/alttp_vanilla.sfc}"
BUILD_DIR="build/bin" BUILD_DIR="build/bin"
LOG_FILE="dungeon_loading_test.log" LOG_FILE="dungeon_loading_test.log"
@@ -23,7 +23,7 @@ echo ""
# Check if ROM file exists # Check if ROM file exists
if [ ! -f "$ROM_FILE" ]; then if [ ! -f "$ROM_FILE" ]; then
echo -e "${RED}ERROR: ROM file not found: $ROM_FILE${NC}" echo -e "${RED}ERROR: ROM file not found: $ROM_FILE${NC}"
echo "Usage: $0 [path/to/zelda3.sfc]" echo "Usage: $0 [path/to/alttp_vanilla.sfc]"
exit 1 exit 1
fi fi
@@ -169,4 +169,3 @@ kill $YAZE_PID 2>/dev/null || true
echo "yaze stopped." echo "yaze stopped."
exit 0 exit 0

7
scripts/test_gui_tools.sh
View File

@@ -91,11 +91,10 @@ echo ""
echo "=== Ready to Test! ===" echo "=== Ready to Test! ==="
echo "" echo ""
echo "To start testing:" echo "To start testing:"
echo "1. Terminal 1: ./build/bin/yaze assets/zelda3.sfc --enable-test-harness" echo "1. Terminal 1: ./build/bin/yaze roms/alttp_vanilla.sfc --enable-test-harness"
echo "2. Terminal 2: export AI_PROVIDER=ollama && ./build/bin/z3ed agent chat --rom assets/zelda3.sfc" echo "2. Terminal 2: export AI_PROVIDER=ollama && ./build/bin/z3ed agent chat --rom roms/alttp_vanilla.sfc"
echo "3. Try: 'What buttons are available in the Overworld editor?'" echo "3. Try: 'What buttons are available in the Overworld editor?'"
echo "" echo ""
echo "Or use Gemini:" echo "Or use Gemini:"
echo "2. Terminal 2: export AI_PROVIDER=gemini && export GEMINI_API_KEY='...' && ./build/bin/z3ed agent chat --rom assets/zelda3.sfc" echo "2. Terminal 2: export AI_PROVIDER=gemini && export GEMINI_API_KEY='...' && ./build/bin/z3ed agent chat --rom roms/alttp_vanilla.sfc"
echo "" echo ""

8
scripts/verify-build-environment.ps1
View File

@@ -426,10 +426,10 @@ function Test-VSCode {
function Test-RomAssets { function Test-RomAssets {
Write-Status "Checking for local Zelda 3 ROM assets..." "Step" Write-Status "Checking for local Zelda 3 ROM assets..." "Step"
$romPaths = @( $romPaths = @(
"zelda3.sfc", "roms/alttp_vanilla.sfc",
"assets/zelda3.sfc", "roms/Legend of Zelda, The - A Link to the Past (USA).sfc",
"assets/zelda3.yaze", "assets/zelda3.yaze",
"Roms/zelda3.sfc" "Roms/alttp_vanilla.sfc"
) )
foreach ($relativePath in $romPaths) { foreach ($relativePath in $romPaths) {
@@ -441,7 +441,7 @@ function Test-RomAssets {
} }
} }
Write-Status "No ROM asset detected. Place a clean 'zelda3.sfc' in the repo root or assets/ directory." "Warning" Write-Status "No ROM asset detected. Place a clean 'alttp_vanilla.sfc' in roms/ or set YAZE_TEST_ROM_VANILLA." "Warning"
$script:warnings += "ROM assets missing - GUI workflows that load ROMs will fail until one is provided." $script:warnings += "ROM assets missing - GUI workflows that load ROMs will fail until one is provided."
} }

44
test/README.md
View File

@@ -34,8 +34,10 @@ ctest --test-dir build -L stable
# Run all available tests (respects your preset configuration) # Run all available tests (respects your preset configuration)
ctest --test-dir build --output-on-failure ctest --test-dir build --output-on-failure
# Run with ROM path for full coverage # Run with ROM paths for full coverage
cmake --preset mac-dbg -DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_PATH=~/zelda3.sfc cmake --preset mac-dbg -DYAZE_ENABLE_ROM_TESTS=ON \
-DYAZE_TEST_ROM_VANILLA_PATH=~/roms/alttp_vanilla.sfc \
-DYAZE_TEST_ROM_EXPANDED_PATH=~/roms/oos168.sfc
ctest --test-dir build ctest --test-dir build
``` ```
@@ -113,7 +115,8 @@ Tests that require an actual Zelda3 ROM file. Disabled by default to avoid distr
**Enable with**: **Enable with**:
```bash ```bash
cmake --preset mac-dbg -DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_PATH=/path/to/zelda3.sfc cmake --preset mac-dbg -DYAZE_ENABLE_ROM_TESTS=ON \
-DYAZE_TEST_ROM_VANILLA_PATH=/path/to/alttp_vanilla.sfc
cmake --build --preset mac-dbg --target yaze_test_rom_dependent cmake --build --preset mac-dbg --target yaze_test_rom_dependent
``` ```
@@ -221,7 +224,7 @@ ctest --test-dir build -L headless_gui
# Must configure with ROM path first # Must configure with ROM path first
cmake --preset mac-dbg \ cmake --preset mac-dbg \
-DYAZE_ENABLE_ROM_TESTS=ON \ -DYAZE_ENABLE_ROM_TESTS=ON \
-DYAZE_TEST_ROM_PATH=~/zelda3.sfc -DYAZE_TEST_ROM_VANILLA_PATH=~/roms/alttp_vanilla.sfc
# Build ROM-dependent test suite # Build ROM-dependent test suite
cmake --build --preset mac-dbg --target yaze_test_rom_dependent cmake --build --preset mac-dbg --target yaze_test_rom_dependent
@@ -258,8 +261,12 @@ ctest --test-dir build
These variables control test behavior: These variables control test behavior:
```bash ```bash
# Specify ROM for tests (if YAZE_ENABLE_ROM_TESTS=ON) # Specify ROMs for tests (if YAZE_ENABLE_ROM_TESTS=ON)
export YAZE_TEST_ROM_PATH=/path/to/zelda3.sfc export YAZE_TEST_ROM_VANILLA=/path/to/alttp_vanilla.sfc
export YAZE_TEST_ROM_EXPANDED=/path/to/oos168.sfc
export YAZE_TEST_ROM_US=/path/to/Legend\\ of\\ Zelda,\\ The\\ -\\ A\\ Link\\ to\\ the\\ Past\\ \\(USA\\).sfc
# Legacy fallback (kept for older scripts)
export YAZE_TEST_ROM_PATH=/path/to/alttp_vanilla.sfc
# Skip ROM tests (useful for CI without ROM) # Skip ROM tests (useful for CI without ROM)
export YAZE_SKIP_ROM_TESTS=1 export YAZE_SKIP_ROM_TESTS=1
@@ -274,12 +281,17 @@ The test framework automatically discovers ROMs without requiring environment va
**Search Paths:** `.`, `roms/`, `../roms/`, `../../roms/` **Search Paths:** `.`, `roms/`, `../roms/`, `../../roms/`
**ROM Filenames:** `zelda3.sfc`, `alttp_vanilla.sfc`, `vanilla.sfc`, `Legend of Zelda, The - A Link to the Past (USA).sfc` **ROM Filenames (vanilla only):** `alttp_vanilla.sfc`, `Legend of Zelda, The - A Link to the Past (USA).sfc`
This means you can simply place your ROM in the `roms/` directory and run tests without setting `YAZE_TEST_ROM_PATH`: Auto-discovery is intentionally limited to clean vanilla ROM names. It does not
consider `zelda3.sfc` or `vanilla.sfc` to avoid picking up modified files. For
expanded ROM tests, set `YAZE_TEST_ROM_EXPANDED` explicitly.
This means you can simply place your vanilla ROM in the `roms/` directory and
run tests without setting `YAZE_TEST_ROM_VANILLA`:
```bash ```bash
# Just works if you have roms/zelda3.sfc # Just works if you have roms/alttp_vanilla.sfc
./build/bin/Debug/yaze_test_stable ./build/bin/Debug/yaze_test_stable
``` ```
@@ -337,7 +349,7 @@ The test suite is optimized for AI agent automation:
4. **Provide ROM path explicitly when needed** 4. **Provide ROM path explicitly when needed**
```bash ```bash
cmake . -DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_PATH=/path/to/rom cmake . -DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_VANILLA_PATH=/path/to/alttp_vanilla.sfc
``` ```
5. **Use headless mode for CI-safe GUI tests** 5. **Use headless mode for CI-safe GUI tests**
@@ -385,7 +397,7 @@ These tests have no external dependencies and run fast. They're enabled by defau
Disabled by default because they require a Zelda3 ROM file. Enable only when needed: Disabled by default because they require a Zelda3 ROM file. Enable only when needed:
```bash ```bash
cmake ... -DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_PATH=/path/to/rom cmake ... -DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_VANILLA_PATH=/path/to/alttp_vanilla.sfc
``` ```
**Experimental AI Suite** **Experimental AI Suite**
@@ -412,14 +424,16 @@ ctest --test-dir build -L "stable|gui" -j4
ctest --test-dir build -L stable --output-on-failure ctest --test-dir build -L stable --output-on-failure
# Add ROM tests if modifying ROM/editor code # Add ROM tests if modifying ROM/editor code
cmake . -DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_PATH=~/zelda3.sfc cmake . -DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_VANILLA_PATH=~/roms/alttp_vanilla.sfc
ctest --test-dir build -L rom_dependent --output-on-failure ctest --test-dir build -L rom_dependent --output-on-failure
``` ```
### Full Test Coverage (With All Features) ### Full Test Coverage (With All Features)
```bash ```bash
# AI features + ROM tests # AI features + ROM tests
cmake --preset mac-dev -DYAZE_TEST_ROM_PATH=~/zelda3.sfc cmake --preset mac-dev \
-DYAZE_TEST_ROM_VANILLA_PATH=~/roms/alttp_vanilla.sfc \
-DYAZE_TEST_ROM_EXPANDED_PATH=~/roms/oos168.sfc
cmake --build --preset mac-dev --target yaze_test_rom_dependent yaze_test_experimental cmake --build --preset mac-dev --target yaze_test_rom_dependent yaze_test_experimental
ctest --test-dir build --output-on-failure ctest --test-dir build --output-on-failure
``` ```
@@ -438,13 +452,13 @@ See `.github/workflows/ci.yml` for details.
### ROM Tests Not Found ### ROM Tests Not Found
```bash ```bash
# Ensure ROM tests are enabled # Ensure ROM tests are enabled
cmake . -DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_PATH=/path/to/rom cmake . -DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_VANILLA_PATH=/path/to/alttp_vanilla.sfc
cmake --build . --target yaze_test_rom_dependent cmake --build . --target yaze_test_rom_dependent
``` ```
### GUI Tests Crash ### GUI Tests Crash
- Ensure SDL display available: `export DISPLAY=:0` on Linux - Ensure SDL display available: `export DISPLAY=:0` on Linux
- Check `assets/zelda3.sfc` exists if no ROM path specified - Check `roms/alttp_vanilla.sfc` exists if no ROM path specified
- Run headlessly: `ctest -L headless_gui` - Run headlessly: `ctest -L headless_gui`
### Tests Not Discovered ### Tests Not Discovered

7
test/e2e/README.md
View File

@@ -57,7 +57,7 @@ Follow the pattern in `dungeon_editor_smoke_test.cc`:
void E2ETest_MyNewTest(ImGuiTestContext* ctx) { void E2ETest_MyNewTest(ImGuiTestContext* ctx) {
// Load ROM // Load ROM
yaze::test::gui::LoadRomInTest(ctx, "zelda3.sfc"); yaze::test::gui::LoadRomInTest(ctx, yaze::test::TestRomManager::GetTestRomPath());
// Open editor // Open editor
yaze::test::gui::OpenEditorInTest(ctx, "My Editor"); yaze::test::gui::OpenEditorInTest(ctx, "My Editor");
@@ -130,7 +130,7 @@ test/e2e/
### Helper Functions ### Helper Functions
Available in `test_utils.h`: Available in `test_utils.h`:
- `yaze::test::gui::LoadRomInTest(ctx, "zelda3.sfc")` - Load ROM for testing - `yaze::test::gui::LoadRomInTest(ctx, yaze::test::TestRomManager::GetTestRomPath())` - Load ROM for testing
- `yaze::test::gui::OpenEditorInTest(ctx, "Editor Name")` - Open an editor window - `yaze::test::gui::OpenEditorInTest(ctx, "Editor Name")` - Open an editor window
## Future Test Ideas ## Future Test Ideas
@@ -147,7 +147,7 @@ Potential tests to add:
## Troubleshooting ## Troubleshooting
### Test Crashes in GUI Mode ### Test Crashes in GUI Mode
- Ensure ROM exists at `assets/zelda3.sfc` - Ensure ROM exists at `roms/alttp_vanilla.sfc` (or set `YAZE_TEST_ROM_VANILLA`)
- Check logs for specific error messages - Check logs for specific error messages
- Try running without `--show-gui` first - Try running without `--show-gui` first
@@ -173,4 +173,3 @@ Potential tests to add:
**Current State**: E2E testing infrastructure is working with 6+ active tests. **Current State**: E2E testing infrastructure is working with 6+ active tests.
**Test Coverage**: Basic workflows covered; opportunity for expansion. **Test Coverage**: Basic workflows covered; opportunity for expansion.
**Stability**: Tests run reliably in both GUI and CI modes. **Stability**: Tests run reliably in both GUI and CI modes.