Skip to content

Latest commit

 

History

History
291 lines (206 loc) · 7.06 KB

README.md

File metadata and controls

291 lines (206 loc) · 7.06 KB

Granado Espada IPF Tools - Testing Framework

Modular JavaScript validation framework for Granado Espada IPF tool implementations.

Related Documentation

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

cd testing
npm install

Run Full Test Suite

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

# 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.

Commands

generate

Generate reference hash databases (requires original Windows tools).

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).

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.

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.

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.

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:

# 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:
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:

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

Permission Denied

Error: EACCES: permission denied

Solution: Make binary executable:

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

Timeout Errors

Error: Command timed out

Solution: Increase timeout in src/config.js:

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.