# Granado Espada IPF Tools - Testing Framework

Modular JavaScript validation framework for Granado Espada IPF tool implementations.

## Related Documentation

- [Project Testing Strategy](../documentation/TESTING.md) - Testing philosophy, types, and coverage
- [Testing Framework Architecture](./architecture.md) - Technical architecture and implementation

## Overview

This testing framework validates our open-source IPF tools against the original Windows tools (iz.exe, ez.exe, etc.) using hash-based comparison. The framework ensures 100% compatibility without distributing proprietary IPF files.

## Quick Start

### Install Dependencies

```bash
cd testing
npm install
```

### Run Full Test Suite

```bash
npm test
```

This will:
1. Extract all test IPF files (ai.ipf, item_texture.ipf, ui.ipf)
2. Optimize ui.ipf and compare with reference
3. Create IPF from extracted files and compare with reference
4. Generate hashes from our output
5. Compare with reference hashes from original tools
6. Report validation results

### Run Individual Commands

```bash
# Run extraction tests only
npm run test:extraction

# Run optimization tests only
npm run test:optimization

# Run all tests (extraction + optimization)
npm test

# Generate reference hashes (requires original Windows tools)
npm run generate

# Generate reference hashes from original tool extractions
# Note: This saves hashes to test_hashes/tools/extraction/original_hashes.json
```

## Directory Structure

The testing framework uses a three-directory structure:

### test_hashes/tools/
- **extraction/original_hashes.json**: Reference hashes from original Windows tools (iz.exe + ez.exe)
  - Generated by: `npm run generate`
  - Source: `reference_original/` directory
  - Purpose: Ground truth for validation

- **extraction/our_hashes.json**: Hashes from our Go IPF extractor
  - Generated by: `npm test`
  - Source: `reference_our/` directory (temporary)
  - Purpose: Record our tool's output for regression testing
  - Note: Hashes always preserved, extracted files cleaned unless `--keep` flag used

**Future Scalability:**
As additional tools are implemented (conversion, addition), the structure will expand:
```
test_hashes/tools/
├── extraction/
│   ├── original_hashes.json
│   └── our_hashes.json
├── optimization/
│   ├── original_hashes.json
│   └── our_hashes.json
├── creation/
│   ├── original_hashes.json
│   └── our_hashes.json
└── conversion/
    ├── original_hashes.json
    └── our_hashes.json
```

### reference_original/
Contains extractions from original Windows tools:
- `small_original/` - ai.ipf extracted by iz.exe + ez.exe
- `medium_original/` - item_texture.ipf extracted by iz.exe + ez.exe
- `large_original/` - ui.ipf extracted by iz.exe + ez.exe

**Purpose**: Source of truth for validation. Regenerated only when re-running original tools.

### reference_our/
Contains extractions from our Go IPF extractor:
- `small_our/` - ai.ipf extracted by our tool
- `medium_our/` - item_texture.ipf extracted by our tool
- `large_our/` - ui.ipf extracted by our tool

**Purpose**: Temporary storage for validation. Files are cleaned up after test runs unless `--keep` flag is used. Hashes are always preserved in `test_hashes/tools/extraction/our_hashes.json`.

## Test Files

The framework validates against three test files:

| Name      | Size   | Files | Strategy |
|-----------|--------|-------|----------|
| ai.ipf    | 4.3K   | 4     | Full hash |
| item_texture.ipf | 191MB | 3,063 | Sampling |
| ui.ipf    | 877MB  | 11,567 | Sampling |

For detailed hash strategy explanation, see [Project Testing Strategy](../documentation/TESTING.md#hash-validation-features).

## Commands

### generate

Generate reference hash databases (requires original Windows tools).

```bash
npm run generate [options]

Options:
  --ipf-path, -i <path>     Path to IPF files directory
  --output-dir, -o <path>    Output directory for hash databases
  --verbose, -v              Enable detailed output
  --help, -h                 Show help
```

### test

Run all tests (extraction + optimization).

```bash
npm test
# or
npm run test

Options:
  --verbose, -v      Enable detailed output
  --keep              Keep extracted/optimized files for debugging (otherwise cleaned up)
  --help, -h         Show help message
```

**Process:**
1. Extract all test IPF files using our Go tool
2. Optimize ui.ipf and compare with reference
3. Save hashes to `test_hashes/tools/extraction/our_hashes.json` and `test_hashes/tools/optimization/our_hashes.json`
4. Compare against reference hashes from original tools
5. Clean up extracted files from `reference_our/` (unless `--keep` flag used)

### test-extraction

Run extraction validation test only.

```bash
npm run test:extraction [options]

Options:
  --verbose, -v      Enable detailed output
  --keep              Keep extracted files for debugging (otherwise cleaned up)
  --help, -h         Show help message
```

### test-optimization

Run optimization validation test only.

```bash
npm run test:optimization [options]

Options:
  --verbose, -v      Enable detailed output
  --quiet, -q        Suppress console output
  --help, -h         Show help message
```

### test-creation

Run creation validation test only.

```bash
npm run test:creation [options]

Options:
  --verbose, -v      Enable detailed output
  --keep             Keep temp files for debugging
  --help, -h         Show help message
```


## CI/CD Integration

The framework is designed for CI/CD integration:

```bash
# Run all tests (non-zero exit code on failure)
npm test

# Run extraction tests only
npm run test:extraction

# Run optimization tests only
npm run test:optimization

# Run creation tests only
npm run test:creation
```

## For Maintainers

### Regenerating Reference Hashes

To regenerate reference hashes:

1. Ensure original Windows tools are available (iz.exe, ez.exe, oz.exe)
2. Run the generate command:

```bash
npm run generate --verbose
```

This will:
- Run original tools on all test files
- Generate reference hash databases
- Save to `test_hashes/tools/extraction/original_hashes.json` and `test_hashes/tools/optimization/original_hashes.json`

### Adding New Test Files

1. Add IPF file to `test_files/` directory
2. Update `TEST_FILES` configuration in `src/config.js`
3. Generate reference hashes: `npm run generate`
4. Validate: `npm test`

## Troubleshooting

### Binary Not Found

```
Error: IPF file not found
```

**Solution**: Ensure the Go binary is built:

```bash
cd src/golang
go build -o build/ipf-extractor ./cmd/ipf-extractor
```

### Permission Denied

```
Error: EACCES: permission denied
```

**Solution**: Make binary executable:

```bash
chmod +x src/golang/build/ipf-extractor
```

### Timeout Errors

```
Error: Command timed out
```

**Solution**: Increase timeout in `src/config.js`:

```javascript
EXECUTION_TIMEOUT: 1200000,  // 20 minutes
```

### Hash Mismatches

```
✗ large: Hash mismatch
```

**Solution**: Verify:
1. Go binary is latest version
2. Reference hashes are up to date
3. No file corruption in test files

## License

MIT License - See LICENSE file for details.