cursebreaker-parser-rust/TESTING.md

# Testing Guide

This document describes how to test the Cursebreaker Unity Parser against real Unity projects.

## Integration Tests

The integration test suite can automatically clone Unity projects from GitHub and parse all their files, providing detailed statistics and error reporting.

### Requirements

- **Git**: Required for cloning test projects
- **Internet connection**: For cloning repositories (only needed on first run)
- **Disk space**: ~100-500 MB per project

### Running Tests

#### Basic Test (VR Horror Project)

This test clones and parses the VR Horror Unity project:

```bash
cargo test test_vr_horror_project -- --nocapture
```

Expected output:
```
============================================================
Testing: VR_Horror_YouCantRun
============================================================
Cloning VR_Horror_YouCantRun from https://github.com/Unity3D-Projects/VR_Horror_YouCantRun.git...
Finding Unity files in test_data/VR_Horror_YouCantRun...
Found 150 Unity files
Parsing files...
  [1/150] Parsing: SampleScene.unity
  [10/150] Parsing: Player.prefab
  ...

============================================================
Parsing Statistics
============================================================
  Total files found:    150
  Scenes parsed:        15
  Prefabs parsed:       120
  Assets parsed:        15
  Total entities:       450
  Total documents:      1200
  Parse time:           250 ms

  Success rate:         95.00%
============================================================
```

#### Detailed Parsing Test

This test shows detailed information about parsed files:

```bash
cargo test test_vr_horror_detailed -- --nocapture
```

This will:
- Parse a sample scene file and show entity information
- Parse a sample prefab file and test the instantiation system
- Test the override system
- Display component type distributions

#### All Projects (Including Ignored Tests)

```bash
cargo test --test integration_tests -- --nocapture --ignored
```

This runs tests for additional projects like PiratePanic (ignored by default because they're large).

#### Performance Benchmark

```bash
cargo test benchmark_parsing -- --nocapture --ignored
```

This measures parsing performance and provides metrics like:
- Files per second
- KB per second
- Average time per file

### Available Test Projects

| Project | Description | Files | Size |
|---------|-------------|-------|------|
| **VR_Horror_YouCantRun** | VR horror game with complex scenes | ~150 | ~50MB |
| **PiratePanic** | Unity Technologies sample project | ~300 | ~200MB |

### Test Data Location

Cloned projects are stored in `test_data/` (gitignored):
```
test_data/
├── VR_Horror_YouCantRun/
│   └── Assets/
│       ├── Scenes/
│       ├── Prefabs/
│       └── ...
└── PiratePanic/
    └── Assets/
        └── ...
```

Projects are cloned only once and reused for subsequent test runs. Delete `test_data/` to force a fresh clone.

### Understanding Test Output

#### Success Rate
- **>95%**: Excellent - parser handles almost all files
- **80-95%**: Good - some edge cases not handled
- **<80%**: Needs investigation - may indicate parser issues

#### Common Error Types
- **Missing Header**: File doesn't have Unity YAML header
- **Invalid Type Tag**: Unknown Unity type ID
- **YAML Parsing Error**: Malformed YAML structure

#### Statistics
- **Total entities**: Number of GameObjects in scenes
- **Total documents**: Number of YAML documents in prefabs/assets
- **Parse time**: Total time to parse all files (lower is better)

### Adding New Test Projects

To add a new Unity project to test:

1. Edit `tests/integration_tests.rs`
2. Add a new project configuration:
```rust
const MY_PROJECT: TestProject = TestProject {
    name: "MyProject",
    repo_url: "https://github.com/user/MyProject.git",
    branch: None, // or Some("main")
};
```

3. Add a test function:
```rust
#[test]
#[ignore] // Optional: ignore by default for large projects
fn test_my_project() {
    test_project(&TestProject::MY_PROJECT);
}
```

4. Run the test:
```bash
cargo test test_my_project -- --nocapture --ignored
```

### Continuous Integration

For CI/CD pipelines:

```bash
# Quick smoke test (doesn't require git)
cargo test --lib

# Full integration tests (requires git)
cargo test --test integration_tests -- --nocapture
```

To skip integration tests in CI environments without git:
```bash
cargo test --lib --bins
```

### Troubleshooting

#### "Git clone failed"
- Ensure git is installed: `git --version`
- Check internet connection
- Verify repository URL is accessible

#### "Skipping test: file not found"
- The test project hasn't been cloned yet
- Run the test again with `--nocapture` to see clone progress
- Check `test_data/` directory was created

#### High error rate
- Check error details in test output
- Some Unity files may use unsupported features
- Error rate <20% is generally acceptable for parsing stress tests

#### Out of disk space
- Delete `test_data/` to free up space
- Run tests for individual projects instead of all at once

### Development Workflow

When adding new parser features:

1. Run integration tests to establish baseline:
```bash
cargo test test_vr_horror_project -- --nocapture > baseline.txt
```

2. Make your changes

3. Re-run tests and compare:
```bash
cargo test test_vr_horror_project -- --nocapture > after_changes.txt
diff baseline.txt after_changes.txt
```

4. Verify:
   - Success rate didn't decrease
   - No new error types introduced
   - Parse time didn't significantly increase

### Performance Targets

- **Parse time**: <2ms per file average
- **Memory usage**: <100MB for 1000 files
- **Success rate**: >90% for well-formed Unity projects

### Example: Testing Prefab Instancing

The detailed test demonstrates the prefab instancing system:

```bash
cargo test test_vr_horror_detailed -- --nocapture
```

Look for output like:
```
Testing prefab instantiation:
  ✓ Created instance with 45 remapped FileIDs
  ✓ Override system working
  - Component types:
    - GameObject: 1
    - Transform: 1
    - RectTransform: 3
    - Canvas: 1
```

This confirms that:
1. Prefabs can be instantiated
2. FileIDs are properly remapped
3. The override system works
4. All component types are recognized