yaze Test Suite

This directory contains the comprehensive test suite for YAZE, organized for optimal AI agent testing and development workflow.

Directory Structure

test/
├── unit/                    # Unit tests for individual components
│   ├── core/               # Core functionality tests
│   ├── rom/                # ROM handling tests
│   ├── gfx/                # Graphics system tests
│   └── zelda3/             # Zelda 3 specific tests
├── integration/            # Integration tests
│   ├── editor/             # Editor integration tests
│   ├── asar_integration_test.cc
│   ├── asar_rom_test.cc
│   └── dungeon_editor_test.cc
├── e2e/                    # End-to-end tests
│   ├── rom_dependent/      # ROM-dependent E2E tests
│   └── zscustomoverworld/  # ZSCustomOverworld upgrade tests
├── deprecated/             # Outdated tests (for cleanup)
│   └── emu/                # Deprecated emulator tests
├── mocks/                  # Mock objects for testing
├── assets/                 # Test assets and patches
└── yaze_test.cc           # Enhanced test runner

Test Categories

Unit Tests (<tt>unit/</tt>)

• Core: ASAR wrapper, hex utilities, core functionality
• ROM: ROM loading, saving, validation
• Graphics: SNES tiles, palettes, compression
• Zelda3: Message system, overworld, objects, sprites

Integration Tests (<tt>integration/</tt>)

• Editor: Tile editor, dungeon editor integration
• ASAR: ASAR integration and ROM patching
• Dungeon: Dungeon editor system integration

End-to-End Tests (<tt>e2e/</tt>)

• ROM Dependent: Complete ROM editing workflow validation
• ZSCustomOverworld: Version upgrade testing (vanilla → v2 → v3)

Enhanced Test Runner

The yaze_test executable now supports comprehensive argument handling for AI agents:

Usage Examples

# Run all tests
./yaze_test
 
# Run specific test categories
./yaze_test --unit --verbose
./yaze_test --integration
./yaze_test --e2e --rom-path my_rom.sfc
./yaze_test --zscustomoverworld --verbose
 
# Run specific test patterns
./yaze_test RomTest.*
./yaze_test *ZSCustomOverworld*
 
# Skip ROM-dependent tests
./yaze_test --skip-rom-tests
 
# Enable UI tests
./yaze_test --enable-ui-tests

Test Modes

• --unit: Unit tests only
• --integration: Integration tests only
• --e2e: End-to-end tests only
• --rom-dependent: ROM-dependent tests only
• --zscustomoverworld: ZSCustomOverworld tests only
• --core: Core functionality tests
• --graphics: Graphics tests
• --editor: Editor tests
• --deprecated: Deprecated tests (for cleanup)

Options

• --rom-path PATH: Specify ROM path for testing
• --skip-rom-tests: Skip tests requiring ROM files
• --enable-ui-tests: Enable UI tests (requires display)
• --verbose: Enable verbose output
• --help: Show help message

E2E ROM Testing

The E2E ROM test suite (e2e/rom_dependent/e2e_rom_test.cc) provides comprehensive validation of the complete ROM editing workflow:

1. Load vanilla ROM
2. Apply various edits (overworld, dungeon, graphics, etc.)
3. Save changes
4. Reload ROM and verify edits persist
5. Verify no data corruption occurred

Test Cases

• BasicROMLoadSave: Basic ROM loading and saving
• OverworldEditWorkflow: Complete overworld editing workflow
• DungeonEditWorkflow: Complete dungeon editing workflow
• TransactionSystem: Multi-edit transaction validation
• CorruptionDetection: ROM corruption detection
• LargeScaleEditing: Large-scale editing without corruption

ZSCustomOverworld Upgrade Testing

The ZSCustomOverworld test suite (e2e/zscustomoverworld/zscustomoverworld_upgrade_test.cc) validates version upgrades:

Supported Upgrades

• Vanilla → v2: Basic upgrade with main palettes
• v2 → v3: Advanced upgrade with expanded features
• Vanilla → v3: Direct upgrade to latest version

Test Cases

• VanillaBaseline: Validate vanilla ROM baseline
• VanillaToV2Upgrade: Test vanilla to v2 upgrade
• V2ToV3Upgrade: Test v2 to v3 upgrade
• VanillaToV3Upgrade: Test direct vanilla to v3 upgrade
• AddressValidation: Validate version-specific addresses
• SaveCompatibility: Test save compatibility between versions
• FeatureToggle: Test feature enablement/disablement
• DataIntegrity: Test data integrity during upgrades

Version-Specific Features

Vanilla

• Basic overworld functionality
• Standard message IDs, area graphics, palettes

v2

• Main palettes support
• Expanded message ID table

v3

• Area-specific background colors
• Subscreen overlays
• Animated GFX
• Custom tile GFX groups
• Mosaic effects

Environment Variables

• YAZE_TEST_ROM_PATH: Path to test ROM file
• YAZE_SKIP_ROM_TESTS: Skip ROM-dependent tests
• YAZE_ENABLE_UI_TESTS: Enable UI tests
• YAZE_VERBOSE_TESTS: Enable verbose test output

CI/CD Integration

Tests are automatically labeled for CI/CD:

• unit: Fast unit tests
• integration: Medium-speed integration tests
• e2e: Slow end-to-end tests
• rom: ROM-dependent tests
• zscustomoverworld: ZSCustomOverworld specific tests
• core: Core functionality tests
• graphics: Graphics tests
• editor: Editor tests
• deprecated: Deprecated tests

Deprecated Tests

The deprecated/ directory contains outdated tests that no longer pass after the large refactor:

• EMU tests: CPU, PPU, SPC700, APU tests that are no longer compatible
• These tests are kept for reference but should not be run in CI/CD

Best Practices

1. Use appropriate test categories for new tests
2. Add comprehensive E2E tests for new features
3. Test upgrade paths for ZSCustomOverworld features
4. Validate data integrity in all ROM operations
5. Use descriptive test names for AI agent clarity
6. Include verbose output for debugging

AI Agent Testing

The enhanced test runner is specifically designed for AI agent testing:

• Clear argument structure for easy automation
• Comprehensive help system for understanding capabilities
• Verbose output for debugging and validation
• Flexible test filtering for targeted testing
• Environment variable support for configuration