engine_rust_src/tests/ORGANIZATION.md

Test Suite Organization

This directory contains the engine test suite, organized by purpose and scope.

Directory Structure

/qa

Purpose: Official Q&A rule verification tests from the official Love Live Card Game Q&A documentation.

• Tests are sourced from published Q&A documents (Q1-Q300+)
• Each test validates a specific ruling, edge case, or clarification
• Tests are grouped by complexity and rule category
• Key files: batch_1.rs, batch_2.rs, batch_3.rs, batch_4_unmapped_qa.rs

Run just QA tests:

cargo test --lib qa -- --test-threads=4

/opcodes

Purpose: Comprehensive coverage tests for bytecode opcodes and operation codes.

• Tests verify individual opcode behavior in isolation
• Tests verify opcode combinations and nesting
• Includes:
  • Basic opcode functionality tests
  • Edge cases for each opcode
  • Opcode interaction tests
  • Stress tests for rare/complex opcode combinations

Run just opcode tests:

cargo test --lib opcode -- --test-threads=4

/mechanics

Purpose: Game mechanics and rule engine integration tests.

• Tests verify multi-turn sequences
• Tests verify phase transitions
• Tests verify state consistency during complex gameplay
• Includes:
  • Card interaction chains
  • Stat/effect buff combinations
  • Trigger and response mechanics
  • Game flow and phase management

Run just mechanics tests:

cargo test --lib mechanics -- --test-threads=4

/edge_cases

Purpose: Stress tests, regression tests, and unusual scenarios.

• Tests for rare ability bytecode sequences
• Stress tests for complex nested conditionals
• Tests for boundary conditions and limits
• Regression tests for previously-fixed bugs
• Includes:
  • Longest/most complex compiled abilities
  • Stress tests for deeply nested conditions
  • Memory limits and performance stress
  • Multi-ability interaction stress tests

Run just edge case tests:

cargo test --lib edge_cases -- --test-threads=4

Test Execution Strategies

Quick CI Pass

# ~30 seconds - Tests critical paths only
cargo test --lib qa -- --test-threads=4

Full Coverage

# ~18 seconds - All tests with parallelization
cargo test --lib

Single-Threaded Debugging

# ~70 seconds - For deterministic ordering/bug reproduction
cargo test --lib -- --test-threads=1

Category-Specific Testing

# Run tests from specific categories
cargo test --lib qa::batch_4
cargo test --lib opcode::rare_bytecode_stress
cargo test --lib mechanics::card_interaction
cargo test --lib edge_cases::complex_ability

Total Test Count: 568

• QA Tests: 163 (Official Q&A document verification)
• Opcode Tests: ~150 (Bytecode operation coverage)
• Mechanics Tests: ~180 (Game flow and interaction)
• Edge Cases: ~75 (Stress, regression, rare scenarios)

Performance Notes

• Parallelization: Tests run with 4-8 threads by default
• Speed: 17-18 seconds for full suite (parallelized)
• Single-threaded: ~70 seconds (use for deterministic debugging)
• Memory: ~200MB during test execution

Adding New Tests

1. New Q&A test? → Add to src/qa/batch_*.rs (existing organization)
2. New opcode test? → Add to /opcodes/opcode_*.rs
3. New mechanics test? → Add to /mechanics/game_flow.rs or similar
4. Stress/edge case? → Add to /edge_cases/stress_*.rs

Tests automatically discovered via Cargo's #[test] attribute macro.