yaze/docs/internal/plans/comprehensive-test-and-cli-plan.md

Comprehensive Plan: E2E Testing & z3ed CLI Improvements

This document outlines the design for ROM-dependent End-to-End (E2E) tests for yaze editors and improvements to the z3ed CLI tool.

1. E2E Testing Design

The goal is to ensure stability and correctness of major editors by simulating user actions and verifying the state of the ROM and application.

1.1. Test Infrastructure

We will extend the existing RomDependentTestSuite in src/app/test/rom_dependent_test_suite.h or create a new EditorE2ETestSuite.

Key Components:

• Test Fixture: A setup that loads a clean ROM (or a specific test ROM) before each test.
• Action Simulator: Helper functions to simulate editor actions (e.g., SelectTile, PlaceObject, Save).
• State Verifier: Helper functions to verify the ROM state matches expectations after actions.

1.2. Overworld Editor Tests

Scope:

• Draw Tile 16: Select a tile from the blockset and place it on the map. Verify the map data reflects the change.
• Edit Tile 16: Modify a Tile16 definition (e.g., change sub-tiles, flip, priority). Verify the Tile16 data is updated.
• Multi-select & Draw: Select a range of tiles and draw them. Verify all tiles are placed correctly.
• Manipulate Entities: Add, move, and delete sprites/exits/items. Verify their coordinates and properties.
• Change Properties: Modify map properties (e.g., palette, music, message ID).
• Expanded Features: Test features specific to ZSCustomOverworld (if applicable).

Implementation Strategy:

• Use OverworldEditor class directly or via a wrapper to invoke methods like SetTile, UpdateEntity.
• Verify by inspecting OverworldMap data and GameData.

1.3. Dungeon Editor Tests

Scope:

• Object Manipulation: Add, delete, move, and resize objects.
• Door Manipulation: Change door types, toggle open/closed states.
• Items & Sprites: Add/remove items (chests, pots) and sprites. Verify properties.
• Room Properties: Change header settings (music, palette, floor).

Implementation Strategy:

• Use DungeonEditor and Room classes.
• Simulate mouse/keyboard inputs if possible, or call logical methods directly.
• Verify by reloading the room and checking object lists.

1.4. Graphics & Palette Editor Tests

Scope:

• Graphics: Edit pixel data in a sprite sheet. Save and reload. Verify pixels are preserved and no corruption occurs.
• Palette: Change color values. Save and reload. Verify colors are preserved.

Implementation Strategy:

• Modify Bitmap data directly or via editor methods.
• Trigger SaveGraphics / SavePalettes.
• Reload and compare byte-for-byte.

1.5. Message Editor Tests

Scope:

• Text Editing: Modify dialogue text.
• Command Insertion: Insert control codes (e.g., wait, speed change).
• Save/Reload: Verify text and commands are preserved.

Implementation Strategy:

• Use MessageEditor backend.
• Verify encoded text data in ROM.

2. z3ed CLI Improvements

The z3ed CLI is a vital tool for ROM hacking workflows. We will improve its "doctor" and "comparison" capabilities and general UX.

2.1. Doctor Command Improvements (z3ed doctor)

Goal: Provide deeper insights into ROM health and potential issues.

New Features:

• Deep Scan: Analyze all rooms, not just a sample (already exists via --all, but make it default or more prominent).
• Corruption Heuristics: Check for common corruption patterns (e.g., invalid pointers, overlapping data).
• Expanded Feature Validation: Verify integrity of expanded tables (Tile16, Tile32, Monologue).
• Fix Suggestions: Where possible, offer specific commands or actions to fix issues (e.g., "Run z3ed fix-checksum").
• JSON Output: Ensure comprehensive JSON output for CI/CD integration.

2.2. Comparison Command Improvements (z3ed compare)

Goal: Make it easier to track changes and spot unintended regressions.

New Features:

• Smart Diff: Ignore insignificant changes (e.g., checksum, timestamp) if requested.
• Visual Diff (Text): Improved hex dump visualization of differences (side-by-side).
• Region Filtering: Allow comparing only specific regions (e.g., "Overworld", "Dungeon", "Code").
• Summary Mode: Show high-level summary of changed areas (e.g., "3 Rooms modified, 1 Overworld map modified").

2.3. UX Improvements

• Progress Bars: Add progress indicators for long-running operations (like full ROM scan).
• Interactive Mode: For doctor, allow interactive fixing of simple issues.
• Better Help: Improve help messages and examples.
• Colorized Output: Enhance readability with color-coded status (Green=OK, Yellow=Warning, Red=Error).

3. Implementation Roadmap

1. Phase 1: Foundation & CLI

   • Refactor z3ed commands for better extensibility.
   • Implement improved doctor and compare logic.
   • Add UX enhancements (colors, progress).

2. Phase 2: Editor Test Framework

   • Create EditorTestBase class.
   • Implement helpers for ROM loading/resetting.

3. Phase 3: Specific Editor Tests

   • Implement Overworld tests.
   • Implement Dungeon tests.
   • Implement Graphics/Palette/Message tests.

4. Phase 4: Documentation & Integration

   • Update docs with usage guides.
   • Integrate into CI pipeline.

4. Verification Plan

• Unit Tests: Verify individual command logic.
• Integration Tests: Run z3ed against known good and bad ROMs.
• Manual Verification: Use the improved CLI tools on real projects to verify utility.