# Test Structure Overview

## Two-Level Test Organization

### Level 1: Per-Crate Tests
Located in each crate's `tests/` directory. Tests that crate in isolation.

```
mlf-lang/tests/          # Parsing, validation, workspace
mlf-codegen/tests/       # Core codegen logic (if any)
mlf-cli/tests/           # CLI-specific units
mlf-diagnostics/tests/   # Diagnostics formatting
```

**Characteristics:**
- ✅ Fast (single crate dependency)
- ✅ Focused (one crate's API)
- ✅ Independent (no cross-crate setup)
- ❌ Limited scope (can't test full workflows)

### Level 2: Workspace Tests
Located at workspace root `tests/`. Tests multiple crates working together.

```
tests/
├── lang/              # Language features (uses mlf-lang)
├── codegen/           # Code generation (uses mlf-lang + mlf-codegen)
├── cli/               # CLI workflows (uses mlf-cli + dependencies)
├── diagnostics/       # Error messages (uses mlf-diagnostics + mlf-lang)
├── workspace/         # Multi-file resolution
└── real_world/        # Full lexicon suites
```

**Characteristics:**
- ✅ Comprehensive (full workflows)
- ✅ Realistic (actual user scenarios)
- ✅ Integration (catch cross-crate issues)
- ❌ Slower (multiple crate compilation)

## Current State

```
✅ mlf-lang/tests/lang/        17 tests (parsing, validation, imports)
📝 tests/codegen/              (4 test cases ready, runner implemented)
📝 tests/cli/                  (structure created, tests pending)
📝 tests/diagnostics/          (structure created, tests pending)
📝 tests/workspace/            (structure created, tests pending)
📝 tests/real_world/           (structure created, tests pending)
```

## Decision Tree: Where Does My Test Go?

```
┌─────────────────────────────────────┐
│ Does this test require multiple    │
│ crates? (CLI, codegen, diagnostics) │
└─────────────┬───────────────────────┘
              │
    ┌─────────┴─────────┐
    │ YES               │ NO
    │                   │
    ▼                   ▼
┌───────────────┐   ┌──────────────────┐
│ Workspace     │   │ Does it test     │
│ tests/        │   │ mlf-lang         │
│               │   │ internals?       │
└───────────────┘   └────────┬─────────┘
                             │
                   ┌─────────┴─────────┐
                   │ YES               │ NO
                   │                   │
                   ▼                   ▼
            ┌──────────────┐   ┌──────────────┐
            │ mlf-lang/    │   │ Other crate/ │
            │ tests/       │   │ tests/       │
            └──────────────┘   └──────────────┘
```

## Examples

### ✅ mlf-lang/tests/
```rust
// Tests parsing and validation only
#[test]
fn test_namespace_alias() {
    let mut ws = Workspace::with_std().unwrap();
    // ... add modules, resolve, check results
}
```

### ✅ tests/codegen/
```rust
// Tests parsing + codegen together
#[test]
fn test_lexicon_generation() {
    // Parse (mlf-lang)
    let lexicon = parse_lexicon(&mlf).unwrap();

    // Generate (mlf-codegen)
    let json = LexiconGenerator::generate(lexicon).unwrap();

    assert_eq!(json, expected);
}
```

### ✅ tests/cli/
```bash
#!/bin/bash
# Tests full CLI workflow
echo 'record foo { bar!: string; }' > test.mlf
mlf generate lexicon test.mlf -o output.json
diff output.json expected.json
```

## Test Execution

### Run everything
```bash
cargo test --workspace
```

### Run workspace tests only
```bash
cargo test --tests  # From workspace root
```

### Run specific crate tests
```bash
cargo test -p mlf-lang
cargo test -p mlf-codegen
```

### Run specific category
```bash
cargo test --test codegen_integration
cd tests/cli && ./run_all.sh
```

## Benefits of This Structure

1. **Fast feedback loop** - Crate tests run quickly during development
2. **Comprehensive validation** - Workspace tests catch integration issues
3. **Clear boundaries** - Easy to know where tests belong
4. **Flexible CI/CD** - Can run crate tests first, workspace tests later
5. **Documentation** - Tests show both isolated and integrated usage

## Adding New Tests

### For Single-Crate Features
```bash
# Example: Add constraint test to mlf-lang
cd mlf-lang/tests/lang/constraints
mkdir new_constraint_test
echo '...' > new_constraint_test/test.mlf
echo '{"status": "success"}' > new_constraint_test/expected.json
cargo test -p mlf-lang --test integration_test
```

### For Multi-Crate Features
```bash
# Example: Add TypeScript codegen test
cd tests/codegen/typescript
mkdir basic_union
echo '...' > basic_union/input.mlf
echo '...' > basic_union/expected.ts
# Update tests/codegen_integration.rs
cargo test --test codegen_integration
```

## Migration Status

- [x] Create workspace test structure
- [x] Document test organization
- [x] Copy lang tests to workspace (for future expansion)
- [ ] Create codegen test runner
- [ ] Create CLI test runner
- [ ] Add first codegen test
- [ ] Add first CLI test
- [ ] Add real-world lexicon tests