# FREEEXILE TEST INFRASTRUCTURE SPECIFICATION
# Multi-Domain ARPG Systems: UI Microcopy, Typography, Multilingual Lexicon & PoE2 Combat UX/VFX

> **Document Type**: Architecture & Test Infrastructure Specification (`TEST_INFRA.md`)  
> **Target Scope**: UI/I18n Streamlining (Features 1–16) & Modern ARPG UX/UI, Animation & VFX (Features 1–23)  
> **Test Harnesses**: `tests/e2e/test_ui_typography_i18n_wiki_streamlining_e2e.py` & `tests/e2e/test_poe2_ui_animation_vfx_e2e.py`  
> **Compliance**: Strict Hygiene Gate (`check_code_and_doc_hygiene.py --strict`)  
> **Test Framework**: Standard Python `unittest` & `pytest`

---

## 1. 4-Tier Testing Architecture

FreeExile enforces an autonomous 4-Tier Test Architecture designed to guarantee that UI microcopy, sans-serif typography, 9-language lexicon, and PoE2 visceral combat systems (Dual Orbs, radial cooldown sweep, kinetic animations, and 120 FPS VFX) operate deterministically without regressions.

```mermaid
flowchart TD
    subgraph T1 [Tier 1: Feature Coverage]
        F1["Button Microcopy (<=2 words)"]
        F2["Elimination of Bilingual A (B) Strings"]
        F3["Typography Sans-Serif Modernization"]
        F4["9-Language Lexicon Parity (143 Keys)"]
        F5["14 Multilingual Wiki Specifications"]
        F6["Dual Fluid Orbs & Wave Math (180x180)"]
        F7["360deg Radial Cooldown Sweep & 0.25s Ready Flash"]
        F8["W3C PointerEvents Joystick (>0.15 Dead-Zone)"]
    end
    subgraph T2 [Tier 2: Boundary & Corner Cases]
        B1["Empty/Null Key Lookups in I18n Engine"]
        B2["Single-Word Microcopy Edge Cases (1 vs 2 vs 3 words)"]
        B3["Tooltip Length Boundaries (<100 chars, 1 sentence)"]
        B4["File Line Caps (Code <=500, Wiki <=600)"]
        B5["0/Negative HP & Rapid Cooldown Clamp Boundaries"]
    end
    subgraph T3 [Tier 3: Cross-Feature Combinations]
        C1["Language Switching Preserves Microcopy across Locales"]
        C2["Typography Classes on Bilingual Controls Remain Sans-Serif"]
        C3["100% HTML & Template Keys Mapped across all 9 Locales"]
        C4["Dodge Cancels Wind-up & Hit-Stop During Screen Shake"]
    end
    subgraph T4 [Tier 4: Real-World Application Scenarios]
        S1["Simulated HUD Navigation Flow (Zero Raw Key Leaks)"]
        S2["9-Language Full Cycle Telemetry & No Overflow"]
        S3["iPhone 15 Pro Mobile Viewport Ergonomics (393px width)"]
        S4["Target Dummy DPS Telemetry & 120 FPS Budget (<=8.33ms)"]
    end

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

---

## 2. Test Tier Specifications

### 2.1. UI Microcopy, Typography & Lexicon Parity (Features 1–16)
- **Objective**: Validate explicit contracts for Features 1–16 from `PROJECT.md`.
- **Criteria**:
  - `Feature 1 (UI Microcopy)`: All interactive buttons in `index.html` and modular template catalogs (`template_catalog_*.js`) have $\le 2$ words.
  - `Feature 2 (Bilingual Removal)`: Zero dual-language parenthetical labels like `Động Thiên (Hideout)` or `Bản Đồ (World Map)`.
  - `Feature 3 (Typography)`: Zero serif font families (`Noto Serif`, `Cinzel`, `Georgia`, `serif`) in `index.html`, `css/main.css`, `css/hud_skills.css`, `css/modals.css`, and Canvas/SVG renderers.
  - `Feature 4 (Multilingual Lexicon)`: Parity across all 9 languages (`vi`, `en`, `zh`, `ja`, `ko`, `th`, `de`, `ru`, `es`) with exactly 143 keys.
  - `Feature 5 (Wiki Streamlining)`: All 14 canonical articles exist synchronously across `wiki/vi/`, `wiki/en/`, and `wiki/zh/`.

### 2.2. PoE2 Modern ARPG UX/UI, Animation & VFX Specifications (Features 1–23)
- **Objective**: Validate HUD Orbs, docked action bar, cooldown mechanics, input ergonomics, and 120 FPS performance.
- **Criteria**:
  - `Feature 1 (Dual Health & Mana Fluid Orbs)`: Retinal $180 \times 180$ Canvas 2D/Metal fluid dynamics with sinusoidal wave equations `sin(x * 0.05 + time * 3.0)` and $< 25\%$ low HP heartbeat pulse vignette.
  - `Feature 2 (Radial Cooldown Sweep & Overlay)`: Docked action bar featuring a 360° clockwise `conic-gradient` radial cooldown `sweep` (`--cooldown-sweep`), numeric countdown badge, and tactile blocked-shake feedback.
  - `Feature 3 (Luminous Ready Flash)`: 0.25s (`0.25s`) golden ready flash pulse (`@keyframes skill-ready-pulse`) with amber bloom on cooldown completion, accompanied by haptic impulse.
  - `Feature 4 (Dual-Scheme Input Ergonomics)`: PC hotkeys (Q, W, E, R, Space, LMB, 4) and mobile virtual joystick with W3C PointerEvents, pointer capture, and $> 0.15$ dead-zone clamping.
  - `Feature 5 (5-Phase Kinetic State Machine & Hit-Stop)`: Character animation phases (Idle, Run, Wind-up, Hit-stop, Recovery), 2-4 frame hit-stop micro-pause, and invincible roll (i-frame).
  - `Feature 6 (Hybrid Elemental VFX & Object Pooling)`: Zero-allocation static object pooling (`vfx_pool.js`) guaranteeing 120 FPS ProMotion frame budget ($\le 8.33\text{ ms/frame}$).

### 2.3. Boundary, Clamp & Corner Case Stress (Tier 2)
- **Objective**: Verify robustness against edge conditions, malformed input, and formatting limits.
- **Key Vectors**:
  - *I18n Fallbacks*: `t("", ...)`, `t(None, ...)`, whitespace strings, unknown keys, and `None` interpolation parameters.
  - *Microcopy Edge Boundaries*: 1-word terms ("Kho", "Thoát"), 2-word terms ("Động Thiên"), 3-word rejections ("Toàn Màn Hình"), emoji stripping ("⚔️ Võ Học"), and CJK 2–4 glyph boundaries.
  - *Tooltip Boundaries*: Length $\le 100$ characters, exactly 1 complete sentence, zero `\n` or `\r` newlines, and catalog descriptions $\le 120$ characters.
  - *Hygiene Line Caps*: `i18n.js` $\le 350/500$ lines, `i18n_catalog.js` $\le 700/1000$ lines, `index.html` $\le 200/400$ lines, template catalogs $\le 700$ lines, wiki docs $\le 400/600$ lines.
  - *Combat Boundaries*: Dual Orbs fill ratio clamping between 0.0 and 1.0; non-positive cooldown duration clamping to 0.0s.

### 2.4. Cross-Feature State Interleaving & Real-World Scenarios (Tiers 3 & 4)
- **Objective**: Ensure that dynamic runtime interactions between subsystems maintain constraints.
- **Scenarios & Combinations**:
  - Dynamic locale switching preserves microcopy and typography stacks across all 9 languages.
  - Dodge roll cancels skill wind-up; hit-stop micro-pause executes concurrently with screen shake.
  - Mobile touch cluster ergonomically isolates joystick movement from action button spam.
  - Target dummy DPS telemetry tracks rotation cycles within the $8.33\text{ ms}$ (120 FPS) frame budget.

---

## 3. Test Execution & Coverage Thresholds

| Metric | Target | Current Status |
| :--- | :---: | :---: |
| **Total Test Cases (I18n / Typography)** | $\ge 50$ items | **60 items (52 passed, 8 skipped)** |
| **Total Test Cases (UI / Animation / VFX)** | $\ge 40$ items | **42 items (33 passed, 9 xfailed)** |
| **Operational Baseline Pass Rate** | $100\%$ | **100% Operational Pass** |
| **Unexpected Failures / Regressions** | $0$ | **0** |
| **Execution Time** | $< 1.0\text{s}$ per suite | **~0.10s / ~0.70s** |
| **Hygiene Compliance** | Code $\le 500$, Docs $\le 600$ | **PASS** |

---

## 4. Verification Commands

```bash
# Execute UI Typography, Microcopy & Wiki Streamlining E2E Suite
pytest tests/e2e/test_ui_typography_i18n_wiki_streamlining_e2e.py -v

# Execute PoE2 UI, Animation, VFX & 120 FPS E2E Suite
pytest tests/e2e/test_poe2_ui_animation_vfx_e2e.py -v

# Execute Unit Tests for HUD Orbs and Skill Bar Controller
pytest tests/unit/test_hud_orbs_and_skill_bar.py -v

# Verify Strict Code and Documentation Hygiene Gate
python tools/lint/check_code_and_doc_hygiene.py --strict
```