Test Suite Structure

Test Suite Structure

Relevant source files

The following files were used as context for generating this wiki page:

• scripts/bench_texconv.py
• tests/test_cli_surface.py
• tests/test_engine_tiling.py
• tests/test_ffxiv_package.py
• tests/test_manifest_classify.py
• tests/test_mdlstrings.py
• tests/test_penumbra_pack.py
• tests/test_run_pipeline.py
• tests/test_texdecode.py
• tests/test_texio.py
• tests/test_texio_batch.py

Purpose and Scope

The test suite located under tests/ provides regression protection, format correctness validation, and architectural verification for XIVUpscaler (clarity). The testing strategy emphasizes platform-independence, running successfully on both Windows (with native texconv.exe binaries and GPU acceleration) and non-Windows environments (via pure-numpy fallback encoders and decoders). It utilizes differential testing against compiled reference libraries, mock game archives (StubGame), and stubbed subprocess hooks (FakeTexconv) to test error containment, batching boundaries, and neural inference tiling invariants without requiring an active game installation or hardware dependencies.

Sources: tests/test_texio.py:1-21], tests/test_run_pipeline.py:1-10], tests/test_texio_batch.py:1-10]()

---

Test Suite Layout and Component Mapping

The test suite mirrors the modular architecture of the core codebase (clarity/), grouping tests by subsystem. Each module has dedicated test files verifying format policies, database transactions, parsing logic, and execution loops.

graph TD
    subgraph "Test Suite Files"
    TI["tests/test_texio.py"]
    TB["tests/test_texio_batch.py"]
    TR["tests/test_run_pipeline.py"]
    TE["tests/test_engine_tiling.py"]
    TD["tests/test_texdecode.py"]
    TM["tests/test_manifest_classify.py"]
    TC["tests/test_cli_surface.py"]
    TP["tests/test_penumbra_pack.py"]
    TMD["tests/test_mdlstrings.py"]
    end

    subgraph "Code Entities"
    TEX["clarity.texio"]
    RUN["clarity.cli (run loop)"]
    ENG["clarity.processing.engine.Engine"]
    DEC["clarity.ffxiv.texdecode"]
    MAN["clarity.manifest"]
    PKI["clarity.packaging.penumbra"]
    MDL["clarity.ffxiv.mdlpatch"]
    end

    TI --> TEX
    TB --> TEX
    TR --> RUN
    TR --> TEX
    TE --> ENG
    TD --> DEC
    TM --> MAN
    TC --> MAN
    TP --> PKI
    TMD --> MDL

Loading

Figure 1: Mapping between test suite files and core codebase entities.

Sources: tests/test_texio.py:1-19], tests/test_run_pipeline.py:1-20], tests/test_engine_tiling.py:1-17], tests/test_cli_surface.py:1-17]()

---

Invariant Single-Source Tests and Differential Decoders

To ensure that byte-level serialization, mips generation, and texture decoding remain strictly aligned with the Final Fantasy XIV SQPack standards, the test suite executes invariant assertions and differential checks against external reference implementations.

Block Decoder Differential Verification

tests/test_texdecode.py tests block and uncompressed decoders (texdecode.py) by comparing the pure-numpy fallback decoder output against the compiled reference library texture2ddecoder (t2d) tests/test_texdecode.py:1-24. Random block bytes are generated with fixed seeds and evaluated:

• BC1 Decoding: Validates that 3-colour mode transparency maps correctly to transparent black, verifying expected alpha against block bits tests/test_texdecode.py:73-96.
• BC2/BC3 Decoding: Compares numpy-derived colour and alpha planes against t2d.decode_bc3 within a tolerance of 1 count to account for float32 truncation versus compiled interpolant rounding tests/test_texdecode.py:110-138.

Format Policy and Float Mip Chains

tests/test_texio.py pins output format selection policies (texio.out_format) and float-precision box filtering (texio.float_chain) tests/test_texio.py:1-10.

• Format Policy Invariants: Uncompressed formats preserve BGRA8, BC2/BC3 are restricted to UI and icon roles while all other texture types map to BC7 tests/test_texio.py:83-102.
• Float Mip Generation: texio.float_chain is tested for box-filtering correctness, ensuring that each lower mip level is computed from the unrounded float level above it, rounded once per level, and clamped properly at 1x1 dimensions tests/test_texio.py:104-161.

Sources: tests/test_texdecode.py:1-58], tests/test_texio.py:1-119]()

---

Pipeline, Tiling, and Batching Tests

Complex execution pipelines—such as asynchronous batch encoding, neural network tiling, and memory limit handling—are validated via isolated simulation harnesses.

Run Loop and Error Isolation (test_run_pipeline.py)

tests/test_run_pipeline.py exercises the end-to-end clarity run CLI command using StubGame, a mock game handle that serves small B8G8R8A8 textures without a real game install or model weights tests/test_run_pipeline.py:1-42.

• Batching & Filling: Verifies that textures aggregate into staging batches up to --encode-batch caps before flushing to encoders tests/test_run_pipeline.py:103-115.
• Failure Isolation: Monkeypatching texio.encode_tiers_many to sabotage a specific item proves that a single encoding failure is recorded independently on its respective database row without aborting the surrounding batch tests/test_run_pipeline.py:132-148.
• Budget Draining: Validates that interruption via --budget successfully encodes and records completed models up to the stop time, leaving remaining items marked as planned for rerun pick-up tests/test_run_pipeline.py:161-182.

graph TD
    SG[StubGame] -->|Reads tex bytes| CL[cli.main run]
    CL -->|Upscales via Lanczos| STG[Staging Batch]
    STG -->|Batched Encode| ET[texio.encode_tiers_many]
    ET -->|Success / Failure isolation| DB[(manifest.sqlite)]
    ET -->|Disk Write| PK[Penumbra Mod Output]

Loading

Figure 2: Data flow and isolation boundaries during pipeline test execution.

Neural Engine Tiling and OOM Recovery (test_engine_tiling.py)

tests/test_engine_tiling.py ensures that Engine._tiled partitions and processes large textures without altering a single pixel, using elementwise arithmetic (FakeModel) instead of convolutions to avoid non-deterministic backend optimizations tests/test_engine_tiling.py:1-35.

• Bitwise Stability: Confirms identical output between single-pass processing and batched tile groups across various tile batch configurations (1, 2, 4, 8, 64) tests/test_engine_tiling.py:79-86.
• CUDA OOM Recovery: Utilizes OOMOnce to simulate a CUDA out-of-memory exception during inference, verifying that the engine catches the exception, halves tile_batch dynamically, flushes the cache, and completes the operation successfully tests/test_engine_tiling.py:37-49, 115-127.

Sources: tests/test_run_pipeline.py:1-185], tests/test_engine_tiling.py:1-145]()

---

Fixture and Platform-Independence Strategy

The test suite runs consistently across Windows, Linux, and macOS without relying on native binaries by employing specific virtualization layers and conditional markers:

• Texconv Abstraction & Subprocess Simulation: Because texconv.exe is Windows-only, tests/test_texio_batch.py implements FakeTexconv, a mock callable substituting subprocess.run tests/test_texio_batch.py:31-68. It mimics multi-file batch CLI invocations, processes valid inputs, skips zero-pixel files, returns non-zero exit codes when expected, and validates single-item fallback retries tests/test_texio_batch.py:31-101.
• Conditional Skippage: Platform-specific tests use @pytest.mark.skipif(os.name == "nt", ...) or check for the presence of optional compiled modules (torch, texture2ddecoder), gracefully falling back or bypassing hardware-accelerated paths tests/test_texio.py:40-51, `tests/test_engine_tiling.py:18]().
• Database Fixtures: SQLite manifest tests instantiate temporary databases via tmp_path pytest fixtures, verifying database schemas, classification updates, and rollback/commit behaviors cleanly without polluting working directories tests/test_manifest_classify.py:1-18, tests/test_cli_surface.py:91-122]().

Sources: tests/test_texio.py:40-51], tests/test_texio_batch.py:31-70], tests/test_cli_surface.py:91-122]()