yaze/docs/internal/plans/CLAUDE_TEST_HANDOFF.md

Claude Test Handoff Document

Date: 2024-11-22 Prepared by: Claude (Sonnet 4.5) Previous agents: Gemini 3, Claude 4.5 (build fixes) Status: Build passing, ready for testing

TL;DR

All 6 feature branches from Gemini3's work have been merged to master and build issues are resolved. The codebase needs comprehensive testing across multiple areas: Overworld fixes, Dungeon E2E tests, Agent UI improvements, CI infrastructure, and debugger/disassembler features.

Current State

Commit: ed980625d7 fix: resolve build errors from Gemini3 handoff
Branch: master (13 commits ahead of origin)
Build: PASSING (mac-dbg preset)

Merged Branches (in order)

1. infra/ci-test-overhaul - CI/CD and test infrastructure
2. test/e2e-dungeon-coverage - Dungeon editor E2E tests
3. feature/agent-ui-improvements - Agent UI and dev tools
4. fix/overworld-logic - Overworld test fixes
5. chore/misc-cleanup - Documentation and cleanup
6. feature/debugger-disassembler - Debugger and disassembler support

Build Fixes Applied

• Added memory_inspector_tool.cc to agent.cmake (was missing, caused vtable linker errors)
• Fixed API mismatches in memory_inspector_tool.cc:
  • GetArg() → GetString().value_or()
  • OutputMap()/OutputTable() → BeginObject()/AddField()/EndObject() pattern

---

Testing Areas

1. Overworld Fixes (fix/overworld-logic)

Files Changed:

• test/integration/zelda3/overworld_integration_test.cc
• test/unit/zelda3/overworld_test.cc

Test Commands:

# Run overworld tests
ctest --test-dir build -R "overworld" --output-on-failure

# Specific test binaries
./build/bin/Debug/yaze_test_stable --gtest_filter="*Overworld*"

What to Verify:

• Overworld unit tests pass
• Overworld integration tests pass
• No regressions in overworld map loading
• Multi-area map configuration works correctly

Manual Testing:

./build/bin/Debug/yaze.app/Contents/MacOS/yaze --rom_file=<path_to_rom> --editor=Overworld

• Load a ROM and verify overworld renders correctly
• Test map switching between Light World, Dark World, Special areas
• Verify entity visibility (entrances, exits, items, sprites)

---

2. Dungeon E2E Tests (test/e2e-dungeon-coverage)

New Test Files:

File	Purpose
dungeon_canvas_interaction_test.cc/.h	Canvas click/drag tests
dungeon_e2e_tests.cc/.h	Full workflow E2E tests
dungeon_layer_rendering_test.cc/.h	Layer visibility tests
dungeon_object_drawing_test.cc/.h	Object rendering tests
dungeon_visual_verification_test.cc/.h	Visual regression tests

Test Commands:

# Run all dungeon tests
ctest --test-dir build -R "dungeon" -L stable --output-on-failure

# Run dungeon E2E specifically
ctest --test-dir build -R "dungeon_e2e" --output-on-failure

# GUI tests (requires display)
./build/bin/Debug/yaze_test_gui --gtest_filter="*Dungeon*"

What to Verify:

• All new dungeon test files compile
• Canvas interaction tests pass
• Layer rendering tests pass
• Object drawing tests pass
• Visual verification tests pass (may need baseline images)
• Integration tests with ROM pass (if ROM available)

Manual Testing:

./build/bin/Debug/yaze.app/Contents/MacOS/yaze --rom_file=<path_to_rom> --editor=Dungeon

• Load dungeon rooms and verify rendering
• Test object selection and manipulation
• Verify layer toggling works
• Check room switching

---

3. Agent UI Improvements (feature/agent-ui-improvements)

Key Files:

File	Purpose
src/cli/service/agent/dev_assist_agent.cc/.h	Dev assistance agent
src/cli/service/agent/tools/build_tool.cc/.h	Build system integration
src/cli/service/agent/tools/filesystem_tool.cc/.h	File operations
src/cli/service/agent/tools/memory_inspector_tool.cc/.h	Memory debugging
src/app/editor/agent/agent_editor.cc	Agent editor UI

Test Commands:

# Run agent-related tests
ctest --test-dir build -R "tool_dispatcher" --output-on-failure
ctest --test-dir build -R "agent" --output-on-failure

# Test z3ed CLI
./build/bin/Debug/z3ed --help
./build/bin/Debug/z3ed memory regions
./build/bin/Debug/z3ed memory analyze 0x7E0000

What to Verify:

• Tool dispatcher tests pass
• Memory inspector tools work:
  • memory regions - lists known ALTTP memory regions
  • memory analyze <addr> - analyzes memory at address
  • memory search <pattern> - searches for patterns
  • memory compare <addr> - compares memory values
  • memory check [region] - checks for anomalies
• Build tool integration works
• Filesystem tool operations work
• Agent editor UI renders correctly

Manual Testing:

./build/bin/Debug/yaze.app/Contents/MacOS/yaze --rom_file=<path_to_rom> --editor=Agent

• Open Agent editor and verify chat UI
• Test proposal drawer functionality
• Verify theme colors are consistent (no hardcoded colors)

---

4. CI Infrastructure (infra/ci-test-overhaul)

Key Files:

• .github/workflows/ci.yml - Main CI workflow
• .github/workflows/release.yml - Release workflow
• .github/workflows/nightly.yml - Nightly builds (NEW)
• test/test.cmake - Test configuration
• test/README.md - Test documentation

What to Verify:

• CI workflow YAML is valid:

  python3 -c "import yaml; yaml.safe_load(open('.github/workflows/ci.yml'))"
  python3 -c "import yaml; yaml.safe_load(open('.github/workflows/nightly.yml'))"
  

• Test labels work correctly:

  ctest --test-dir build -L stable -N  # List stable tests
  ctest --test-dir build -L unit -N    # List unit tests
  

• Documentation is accurate in test/README.md

---

5. Debugger/Disassembler (feature/debugger-disassembler)

Key Files:

• src/cli/service/agent/disassembler_65816.cc
• src/cli/service/agent/rom_debug_agent.cc
• src/app/emu/debug/ - Emulator debug components

Test Commands:

# Test disassembler
ctest --test-dir build -R "disassembler" --output-on-failure

# Manual disassembly test (requires ROM)
./build/bin/Debug/z3ed disasm <rom_file> 0x008000 20

What to Verify:

• 65816 disassembler produces correct output
• ROM debug agent works
• Emulator stepping (if integrated)

---

Quick Test Matrix

Area	Unit Tests	Integration	E2E/GUI	Manual
Overworld	overworld_test	overworld_integration_test	-	Open editor
Dungeon	object_rendering_test	dungeon_room_test	dungeon_e2e_tests	Open editor
Agent Tools	tool_dispatcher_test	-	-	z3ed CLI
Memory Inspector	-	-	-	z3ed memory *
Disassembler	disassembler_test	-	-	z3ed disasm

---

Full Test Suite

# Quick smoke test (stable only, ~2 min)
ctest --test-dir build -L stable -j4 --output-on-failure

# All tests (may take longer)
ctest --test-dir build --output-on-failure

# ROM-dependent tests (if ROM available)
cmake --preset mac-dbg -DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_PATH=~/zelda3.sfc
ctest --test-dir build -L rom_dependent --output-on-failure

---

Known Issues / Watch For

1. Linker warnings: You may see warnings about duplicate libraries during linking - these are benign warnings, not errors.

2. third_party/ directory: There's an untracked third_party/ directory that needs a decision:

   • Should it be added to .gitignore?
   • Should it be a git submodule?
   • For now, leave it untracked.

3. Visual tests: Some dungeon visual verification tests may fail if baseline images don't exist yet. These tests should generate baselines on first run.

4. GUI tests: Tests with -L gui require a display. On headless CI, these may need to be skipped or run with Xvfb.

5. gRPC tests: Some agent features require gRPC. Ensure YAZE_ENABLE_REMOTE_AUTOMATION is ON if testing those.

---

Recommended Test Order

1. First: Run stable unit tests to catch obvious issues

   ctest --test-dir build -L stable -L unit -j4
   

2. Second: Run integration tests

   ctest --test-dir build -L stable -L integration -j4
   

3. Third: Manual testing of key editors (Overworld, Dungeon, Agent)

4. Fourth: E2E/GUI tests if display available

   ./build/bin/Debug/yaze_test_gui
   

5. Fifth: Full test suite

   ctest --test-dir build --output-on-failure
   

---

Build Commands Reference

# Configure (if needed)
cmake --preset mac-dbg

# Build main executable
cmake --build build --target yaze -j4

# Build all (including tests)
cmake --build build -j4

# Build specific test binary
cmake --build build --target yaze_test_stable -j4
cmake --build build --target yaze_test_gui -j4

---

Files Modified in Final Fix Commit

For reference, these files were modified in ed980625d7:

File	Change
assets/asm/usdasm	Submodule pointer update
src/app/editor/agent/agent_editor.cc	Gemini3's UI changes
src/app/gui/style/theme.h	Theme additions
src/cli/agent.cmake	Added memory_inspector_tool.cc
src/cli/service/agent/emulator_service_impl.h	Gemini3's changes
src/cli/service/agent/rom_debug_agent.cc	Gemini3's changes
src/cli/service/agent/tools/memory_inspector_tool.cc	API fixes
src/protos/emulator_service.proto	Gemini3's proto changes

---

Success Criteria

Testing is complete when:

• All stable tests pass (ctest -L stable)
• No regressions in Overworld editor
• No regressions in Dungeon editor
• Agent tools respond correctly to CLI commands
• Build succeeds on all platforms (via CI)

---

Contact / Escalation

If you encounter issues:

1. Check docs/BUILD-TROUBLESHOOTING.md for common fixes
2. Review GEMINI3_HANDOFF.md for context on the original work
3. Check git log for related commits: git log --oneline -20

Good luck with testing!