engine_rust_src/TEST_ORGANIZATION.md

# Engine Test Suite - Complete Organization Guide

**Last Updated**: March 13, 2026  
**Total Tests**: 568 (all passing except Q166 isolation issue)  
**Execution Time**: 17-18 seconds (parallelized), ~70 seconds (single-threaded)

---

## Table of Contents

1. [Quick Reference](#quick-reference)
2. [Test Categories](#test-categories)
3. [Directory Structure](#directory-structure)
4. [Running Tests](#running-tests)
5. [Adding New Tests](#adding-new-tests)
6. [Organization Migration Plan](#organization-migration-plan)
7. [Performance Optimization](#performance-optimization)

---

## Quick Reference

### Run All Tests
```bash

cd engine_rust_src

cargo test --lib          # ~18s, parallelized (default)

cargo test --lib -- --test-threads=1  # ~70s, single-threaded

```

### Run Test Categories
```bash

cargo test --lib qa                    # QA rule tests (163 tests, ~5s)

cargo test --lib opcode               # Opcode tests (150 tests, ~3s)

cargo test --lib mechanics            # Mechanics tests (180 tests, ~3s)

cargo test --lib edge_case            # Edge case/stress tests (75 tests, ~2s)

cargo test --lib regression           # Regression tests only

```

### Run Specific Test
```bash

cargo test --lib test_q166            # Single test by name

cargo test --lib test_opcode_draw     # Tests matching pattern

cargo test --lib qa::batch_4          # Tests in batch_4 module

```

---

## Test Categories

### 1. QA Verification Tests (163 tests)

**Purpose**: Automated validation of official Q&A rulings

**Location**: `src/qa/` module
- `batch_1.rs` - Q1-Q50
- `batch_2.rs` - Q51-Q100
- `batch_3.rs` - Q101-Q150
- `batch_4_unmapped_qa.rs` - Q151+

**Key Features**:
- Real database cards
- Official ruling references in comments
- High-impact rule coverage
- ~50% of total Q&A entries

**Example Tests**:
- `test_q166_reveal_until_refresh_excludes_currently_revealed_cards`
- `test_q211_sunny_day_song` (live ability targeting)
- `test_q191_daydream_mermaid` (mode selection)

**Run**: `cargo test --lib qa`

### 2. Opcode Tests (~150 tests)

**Purpose**: Bytecode instruction validation

**Location**: Multiple files in `src/`
- `opcode_tests.rs` - Core opcode tests
- `opcode_coverage_gap_2.rs` - Coverage gaps
- `opcode_missing_tests.rs` - Missing implementations
- `opcode_rigor_tests.rs` - Rigorous validation

**Key Opcodes Tested**:
- O_DRAW, O_REVEAL_UNTIL, O_DRAW_UNTIL

- O_LOOK_AND_CHOOSE, O_LOOK_DECK
- O_ADD_BLADES, O_ADD_HEARTS
- O_TAP_UNTAP state management
- Filter expressions and conditions

**Run**: `cargo test --lib opcode`

### 3. Mechanics Tests (~180 tests)

**Purpose**: Game flow and rule engine integration

**Location**: Multiple mechanics test files
- `mechanics_tests.rs` - Core mechanics
- `game_flow_tests.rs` - Phase transitions
- `card_interaction_tests.rs` - Card interactions
- `response_flow_tests.rs` - Response phase

**Key Mechanics Tested**:
- Card drawing and deck refresh
- Stat calculations
- Card placement and movement
- Trigger queuing
- Multi-ability chains

**Run**: `cargo test --lib mechanics`

### 4. Edge Cases & Stress Tests (~75 tests)

**Purpose**: Rare scenarios, stress, and regression

**Location**: Multiple files
- `regression_tests.rs` - Bug regressions
- `coverage_gap_tests.rs` - Coverage analysis
- `stabilized_tests.rs` - Stable behavior validation
- `../tests/edge_cases/` - Planned stress tests

**Key Tests**:
- Rare opcode combinations
- Deeply nested conditions
- Boundary conditions
- Performance stress
- State consistency under load

**Run**: `cargo test --lib edge_case` or `cargo test --lib stress`

---

## Directory Structure

### Current Organization (Active)

```

engine_rust_src/

├── src/

│   ├── lib.rs                          # Main library + test module declarations

│   ├── core/                           # Core engine code

│   ├── qa/                             # QA test module (163 tests)

│   │   ├── mod.rs

│   │   ├── batch_1.rs

│   │   ├── batch_2.rs

│   │   ├── batch_3.rs

│   │   ├── batch_4_unmapped_qa.rs

│   │   └── [other QA tests]

│   ├── qa_verification_tests.rs        # Additional QA tests

│   ├── opcode_tests.rs                 # Core opcode tests

│   ├── opcode_coverage_gap_2.rs        # Coverage gaps

│   ├── opcode_missing_tests.rs         # Missing opcodes

│   ├── opcode_rigor_tests.rs           # Rigorous tests

│   ├── mechanics_tests.rs              # Mechanics tests

│   ├── game_flow_tests.rs              # Game flow

│   ├── card_interaction_tests.rs       # Interactions

│   ├── regression_tests.rs             # Regressions

│   ├── response_flow_tests.rs          # Response phase

│   ├── coverage_gap_tests.rs           # Coverage analysis

│   ├── stabilized_tests.rs             # Stable validation

│   ├── test_helpers.rs                 # Test utilities

│   └── [other test modules]

└── tests/                              # Reference structure (new)

    ├── README.md                       # Test organization docs

    ├── mod.rs                          # Module organization guide

    ├── qa/mod.rs                       # QA test reference

    ├── opcodes/mod.rs                  # Opcode test reference

    ├── mechanics/mod.rs                # Mechanics test reference

    └── edge_cases/                     # Stress tests (active)

        ├── mod.rs

        └── stress_rare_bytecode_sequences.rs

```

### Planned Organization (Future)

See `tests/README.md` for full reorganization blueprint:
- `tests/qa/` - QA tests (copy from src/qa/)
- `tests/opcodes/` - Opcode tests (migrate from src/)
- `tests/mechanics/` - Mechanics tests (migrate from src/)
- `tests/edge_cases/` - Stress and regression (NEW)

---

## Running Tests

### Full Test Suite
```bash

# Parallelized (default, ~18 seconds)

cargo test --lib



# With parallelization control

cargo test --lib -- --test-threads=4  # 4 threads

cargo test --lib -- --test-threads=8  # 8 threads



# Single-threaded for debugging (~70 seconds)

cargo test --lib -- --test-threads=1



# With output

cargo test --lib -- --nocapture

```

### By Category
```bash

# QA tests only (~5 seconds)

cargo test --lib qa



# Opcode tests only (~3 seconds)

cargo test --lib opcode



# Mechanics tests only (~3 seconds)

cargo test --lib mechanics



# Regression tests only

cargo test --lib regression



# Stress tests only

cargo test --lib stress

```

### Specific Tests
```bash

# Single test

cargo test --lib test_q166_reveal_until_refresh



# Pattern matching

cargo test --lib test_opcode_draw



# Module-specific

cargo test --lib qa::batch_4::tests::test_q166



# With debugging output

cargo test --lib test_q166 -- --nocapture

```

### CI/CD Usage
```bash

# Quick validation (~30 seconds)

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



# Full validation (~18 seconds)

cargo test --lib



# With coverage

cargo tarpaulin --lib

```

---

## Adding New Tests

### Adding a New Q&A Test

1. **Identify the Q# and topic** from official documentation
2. **Open** `src/qa/batch_4_unmapped_qa.rs` (or create batch_5.rs)

3. **Write the test**:



```rust

/// Q###: [Official Japanese ruling text]

/// A###: [Official answer/clarification]

#[test]

fn test_q###_brief_topic_description() {

    let db = load_real_db();

    let mut state = create_test_state();



    // Setup game state according to Q###

    state.players[0].deck = vec![/* card IDs */].into();

    state.players[0].stage[0] = 123;  // specific card



    // Perform action described in Q###

    // ...



    // Verify expected ruling outcome

    assert_eq!(expected_result, actual_result,
        "Q###: [brief description of expected behavior]");

}

```


4. **Run the test**:
```bash

cargo test --lib test_q###_brief_topic

```

5. **Commit and document**:
```

Add test for Q###: [official topic]



Tests the ruling: [brief description of what is validated]

References: Official Q&A documentation Q###

```

### Adding an Opcode Test

1. **Identify** which opcode (O_DRAW, O_REVEAL_UNTIL, etc.)

2. **Choose appropriate file**:

   - `opcode_tests.rs` - Core opcode behavior
   - `opcode_coverage_gap_2.rs` - Coverage gaps
   - `opcode_rigor_tests.rs` - Edge cases
3. **Write the test**:

```rust

/// Tests O_OPCODE_NAME with [scenario description]

/// Complexity: Basic/Medium/Advanced

#[test]

fn test_opcode_name_scenario() {

    let db = create_test_db();

    let mut state = create_test_state();



    // Minimal setup

    state.players[0].deck = vec![/* ... */].into();



    // Execute bytecode

    let bc = vec![O_OPCODE_NAME, /* args */, O_RETURN];

    state.resolve_bytecode_cref(&db, &bc, &ctx);



    // Verify

    assert_eq!(expected, actual);

}

```

4. **Test it**:
```bash

cargo test --lib test_opcode_name_scenario

```

### Adding a Stress Test

1. **Create or edit** `tests/edge_cases/stress_rare_bytecode_sequences.rs`
2. **Add to the appropriate section** (rare opcodes, deep nesting, etc.)
3. **Document complexity metrics**:

```rust

/// Stress test: [scenario]

/// 

/// **Complexity**: High | **Bytecode Length**: 200+ | **Nesting**: 8+ levels

#[test]

fn test_stress_scenario_name() {

    // Test implementation

}

```

---

## Organization Migration Plan

### Phase 1: Reference Structure (DONE)
- ✅ Created `tests/` directory with reference blueprints
- ✅ Added comprehensive documentation comments
- ✅ Created stress test framework in `tests/edge_cases/`
- ✅ Documented migration path

### Phase 2: New Test Additions (ONGOING)
- Add new stress tests to `tests/edge_cases/stress_*.rs`
- Add complex bytecode analysis to stress framework
- Extend coverage with rare opcode tests

### Phase 3: Planned Migration (FUTURE)
When test suite grows or organizational needs change:
1. Copy `src/qa/*` → `tests/qa/*`
2. Copy `src/opcode_*.rs` tests → `tests/opcodes/*.rs`
3. Copy mechanics tests → `tests/mechanics/*.rs`
4. Update module declarations
5. Verify all paths still resolve

## Performance Optimization

### Current Performance (Good)
- **Full Suite**: 17-18 seconds (parallelized)
- **Parallelization**: 4-8 threads (auto-scaled)
- **Memory**: ~200MB peak
- **Speedup**: 4x vs single-threaded (17s vs 70s)

### Optimization Techniques

**For faster local feedback**:
```bash

# Just QA tests (5s)

cargo test --lib qa



# Just opcode tests (3s)

cargo test --lib opcode



# Single test (0.5s)

cargo test --lib test_q166

```

**For CI/CD**:
```bash

# Parallelized with more threads

cargo test --lib -- --test-threads=8   # 16-17s on 8-core machine



# Category-based parallelization

cargo test --lib qa & cargo test --lib opcode & wait  # Can run in parallel

```

**For debugging**:
```bash

# Single-threaded for deterministic ordering

cargo test --lib -- --test-threads=1   # ~70s



# With logging

RUST_LOG=debug cargo test --lib -- --nocapture

```

---

## Troubleshooting

### Q166 Test Isolation Issue
- **Symptom**: Q166 fails in `cargo test --lib` but passes in `cargo test --lib test_q166`
- **Status**: Known test contamination issue (one test pollutes Q166's state)
- **Workaround**: Run Q166 separately or in batch
- **Investigation**: Needed to identify which test runs before Q166

### Tests Running Slowly
- **Check parallelization**: `cargo test --lib -- --test-threads=4`
- **Profile single test**: `time cargo test --lib test_q166`
- **Check for I/O bottleneck**: DB loading is one-time (~0.5s)

### Test Compilation Taking Long
- **Incremental builds**: Usually ~30s for clean test run
- **Use incremental compilation**: Enabled by default in latest Rust

---

## Contributing Tests

When adding tests:
1. **Follow naming conventions**: `test_category_brief_description`
2. **Add documentation comments**: Explain what is tested and why
3. **Use minimal setup**: Only initialize state needed for test
4. **Include assertions**: Validate both positive and negative cases
5. **Document complexity**: Note if test is stress/slow
6. **Reference source**: Link to official rules, issue numbers, or card names

---

## Additional Resources

- `tests/README.md` - Test directory organization reference
- `src/lib.rs` - Full architecture documentation
- `src/qa/mod.rs` - QA test module documentation
- `src/opcode_tests.rs` - Opcode test documentation
- `src/mechanics_tests.rs` - Mechanics test documentation

---

**Last Updated**: March 13, 2026  
**Next Review**: After reaching 600+ tests or adding new test category