# FREEEXILE TEST INFRASTRUCTURE SPECIFICATION
# Asset Campaign & Graphics Optimization Pipeline 2026 (Tiers 1–4)

> **Document Type**: Architecture & Test Infrastructure Specification (`TEST_INFRA.md`)  
> **Target Scope**: Graphics R&D Tools (LOD, WebP Compressor, Viewport Culling), DRQ Management, Asset Production & Technical Quality Gate  
> **Test Harness**: `tests/e2e/test_asset_campaign_and_pipeline_e2e.py`  
> **Compliance**: Strict Hygiene Gate (`check_code_and_doc_hygiene.py --strict`)  
> **Test Framework**: Standard Python `pytest` & `unittest`

---

## 1. 4-Tier Testing Architecture

FreeExile enforces an autonomous 4-Tier Test Architecture designed to guarantee that graphics optimization utilities, design request ingestion, asset compression, viewport culling, and full-campaign asset quality operate deterministically and robustly without regressions.

```mermaid
flowchart TD
    subgraph T1 [Tier 1: Feature Coverage >=5 tests/feature]
        F1["DRQ Schema & Ingestion Parsing"]
        F2["Sprite LOD 3-Tier Generation (100%, 50%, 25%)"]
        F3["WebP Texture Compression (<= 50% Size)"]
        F4["Viewport Frustum Culling (AABB & Iso Projection)"]
        F5["Mob & Boss Atlas Manifest Verification"]
        F6["Currencies & UI Assets Specifications"]
    end
    subgraph T2 [Tier 2: Boundary & Corner Cases >=5 tests/feature]
        B1["Empty Directories & Missing Input Handling"]
        B2["Non-PoT (Power of Two) Dimension Rejection"]
        B3["Corrupt & Truncated Texture Handling"]
        B4["Extreme Camera Coords & Zero Viewport"]
        B5["Single-Pixel & Boundary Downsampling"]
        B6["WebP Quality Clamping (1 to 100)"]
    end
    subgraph T3 [Tier 3: Cross-Feature Combinations]
        C1["Pipeline Chain: Source -> LODs -> WebP Batch"]
        C2["Design Pipeline Manager Ingest -> Report Cycle"]
        C3["Culling -> Metal GPU Instancing Draw Call Budget"]
        C4["Server AoI & Delta Compression Simulation"]
    end
    subgraph T4 [Tier 4: Real-World Application Scenarios]
        S1["Full Asset Campaign Audit (Dimensions & Paths)"]
        S2["Tangent-Space Normal Map Blue Channel (Mean > 128)"]
        S3["File Size Budget Enforcement (Atlas, UI, Tiles)"]
        S4["Departmental DRQ Ingestion Audit (6 Depts >= 20 DRQs)"]
        S5["Rendering Optimization Research Report Validation"]
    end

    T1 --> T2
    T2 --> T3
    T3 --> T4
```

---

## 2. Test Tier Specifications

### 2.1. Functional Feature Coverage (Tier 1)
- **Feature 1: DRQ Schema & Ingestion**: Verifies parsing of Design Requests from `docs/design_requests/inbox/`, ensuring mandatory metadata keys (ID, Dept, Title, Priority, Asset Type, Target Path, Dimensions, Budget, Normal Map), canonical naming `DRQ-YYYYMMDD-[FEATURE].md`, and status transitions.
- **Feature 2: Sprite LOD Generator**: Verifies `tools/asset_pipeline/lod_generator.py` API (`generate_sprite_lods`, `evaluate_lod_generation`) and CLI, producing 3 tiers (LOD-0 100%, LOD-1 50%, LOD-2 25%) using Lanczos resampling, with LOD-2 file size $\le 40\%$ of original.
- **Feature 3: WebP Texture Compressor**: Verifies `tools/asset_pipeline/texture_compressor.py` API (`compress_to_webp`, `batch_compress_directory`) and CLI, guaranteeing output WebP file size $\le 50\%$ of original PNG, full RGBA alpha transparency preservation, and compression stats.
- **Feature 4: Viewport Frustum Culling**: Verifies `tools/asset_pipeline/viewport_culling_utils.py` math primitives (`AABB`, `Frustum2D`, `project_iso`, `intersects`, `cull_entities`), confirming correct off-screen culling, on-screen visibility, and sub-millisecond execution over 1,000 entities.
- **Feature 5: Mob & Boss Atlases**: Validates character and monster animation packages in `client/webapp/assets/animations/`, checking manifest JSON schema, frame dimensions, action states, and companion normal maps.
- **Feature 6: Currencies & UI Assets**: Validates icon sets in `client/webapp/assets/currencies/` and `ui/`, checking dimension power-of-two constraints and metadata.

### 2.2. Boundary, Stress & Corner Cases (Tier 2)
- **Vector 1: Missing & Empty Sources**: Validates `FileNotFoundError` when source textures do not exist, and graceful zero-result handling for empty directories.
- **Vector 2: Non-Power-of-Two (Non-PoT) Rejection**: Validates that odd resolutions (e.g. $100 \times 150$, $300 \times 500$) fail PoT validation assertions.
- **Vector 3: Corrupt & Truncated Textures**: Verifies that truncated files or invalid image headers raise clean exceptions without crashing the pipeline process.
- **Vector 4: Extreme Camera & Viewport Zoom**: Tests viewport size $0 \times 0$, extreme $10,000 \times 10,000$ viewport, and extreme negative world coordinates $(-9,999, -9,999)$.
- **Vector 5: Single-Pixel Downsampling**: Tests $1 \times 1$ and $2 \times 2$ sprites downsampled to LOD-2, verifying minimum dimension clamp to 1 without division by zero.
- **Vector 6: WebP Quality Clamping**: Validates quality values at boundary conditions (quality=1, quality=100) and clamping behavior.

### 2.3. Cross-Feature Combinations & Real-World Scenarios (Tiers 3 & 4)
- **Pipeline Chain**: End-to-end integration: input PNG $\to$ 3-tier LOD generation $\to$ batch WebP compression on all LOD levels, verifying complete pipeline throughput and cascading size savings.
- **Design Pipeline Manager Cycle**: Ingestion of all DRQs $\to$ scan $\to$ departmental grouping $\to$ report output format validation.
- **Culling to GPU Instancing**: Simulates 50–200 entities on-screen, filters via viewport culling, groups visible entities into archetype palette buckets, and verifies total draw calls $< 30$ per frame ($200+$ instances batched via Metal instancing).
- **Campaign Normal Map Audit**: Vectorized Pillow inspection across normal maps verifying that Tangent-space Normal Blue channel mean $> 128$.
- **File Size Budget Enforcement**: Character spritesheets $\le 2\text{ MB}$, UI icons $\le 150\text{ KB}$, Map tiles $\le 50\text{ KB}$.
- **Departmental DRQ Ingestion Audit**: Verifies $\ge 20$ DRQs across all 6 departments (Systems, Narrative, Economy, Security, Client, Server) with $\ge 3$ DRQs per department.

---

## 3. Test Execution Metrics

| Metric | Target | Current Status |
| :--- | :---: | :---: |
| **Total Test Items** | $\ge 40$ items | **Planned $\ge 45$ items** |
| **Operational Pass Rate** | $100\%$ | **Target 100% PASS** |
| **Execution Time** | $< 10.0\text{s}$ | **Target $< 5.0\text{s}$** |
| **Hygiene Compliance** | Code $\le 450$ lines, Docs $\le 400$ lines | **Clean PASS** |

---

## 4. Test Runner Commands

```bash
# Execute the comprehensive Asset Campaign & Graphics Optimization E2E Suite
pytest tests/e2e/test_asset_campaign_and_pipeline_e2e.py -v

# Run with concise summary
pytest tests/e2e/test_asset_campaign_and_pipeline_e2e.py -q

# Run specific tier
pytest tests/e2e/test_asset_campaign_and_pipeline_e2e.py -k "TestTier1" -v
pytest tests/e2e/test_asset_campaign_and_pipeline_e2e.py -k "TestTier2" -v
pytest tests/e2e/test_asset_campaign_and_pipeline_e2e.py -k "TestTier3" -v
pytest tests/e2e/test_asset_campaign_and_pipeline_e2e.py -k "TestTier4" -v

# Verify strict code and documentation hygiene gate
python tools/lint/check_code_and_doc_hygiene.py --strict
```