124 lines
5.5 KiB
Markdown
124 lines
5.5 KiB
Markdown
# 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.
|