# Test Infrastructure — Diablo II 1.13c Isometric Automap & Minimap E2E Suite

## 1. Architecture Overview

The requirement-driven opaque-box E2E test suite in `tests/e2e-automap-113c/` validates all 13 canonical features (`F1`–`F13`) defined in `PROJECT.md § Feature Inventory` against the authoritative Diablo II 1.13c binary specifications (`D2Common.dll` and `D2Client.dll`) and MPQ data tables (`AutoMap.txt`, `LvlTypes.txt`, `Levels.txt`, `Objects.txt`, `MonStats.txt`, `MonStats2.txt`, `SuperUniques.txt`, and 8 automap DC6 sprite sheets).

The test suite is organized into 4 progressive tiers (`160` tests total across 4 test files):

| Tier | File | Scope | Test Count |
|---|---|---|---|
| **Tier 1** | `tests/e2e-automap-113c/tier1-feature-coverage.test.ts` | Happy-path & primary behavior coverage (`5` tests per feature across `F1`–`F13`) | `65` |
| **Tier 2** | `tests/e2e-automap-113c/tier2-boundary-corner.test.ts` | Boundary values, off-by-one edges, negative/invalid inputs, & adversarial stress (`5` tests per feature across `F1`–`F13`) | `65` |
| **Tier 3** | `tests/e2e-automap-113c/tier3-cross-feature-combinations.test.ts` | Pairwise and multi-feature interaction chains (`F1`–`F13` end-to-end combinations) | `18` |
| **Tier 4** | `tests/e2e-automap-113c/tier4-real-world-scenarios.test.ts` | Realistic gameplay scenarios across Acts 1–5 towns/dungeons and full-spectrum 136-level (`1..136`, 365 baked scenes) audits | `12` |
| **Total** | `tests/e2e-automap-113c/*.test.ts` | All 13 features (`F1`–`F13`) | **`160`** |

---

## 2. Authoritative Oracles & Data Sources

1. **Live MPQ Archives (`samples/d2/d2exp.mpq`, `samples/d2/d2data.mpq`)**:
   - Loaded in memory via `MpqArchive.open(memorySource(new Uint8Array(fs.readFileSync(...))))`.
   - Provides the unmodified 3,348-row `data\global\excel\AutoMap.txt` table (`parseAutomapTable`), `.ds1` map files (`decodeDs1`), and `.dc6` sprite sheets.
2. **Baked 8-Sheet Automap UI Manifest (`src/ui/baked-ui-meta.ts` + `public/assets/ui/automap/*.png`)**:
   - `MaxiMap` / `MaxiMapS` (`1499` frames each)
   - `Act2Map` / `Act2MapS` (`40` frames each)
   - `Act4Map` / `Act4MapS` (`4` frames each)
   - `ExTnMap` / `ExTnMapS` (`8` frames each)
3. **Baked 136-Level Scene Pack (`samples/d2-packs/index.json`)**:
   - Contains `365` baked scene variants covering all `136` canonical Level IDs (`1..136`), each pre-populated with `scene.automap` (`floors`, `walls`, `objects`, `extras`).

---

## 3. Recording `SpriteRenderer` & `D2FontRenderer` Harness

To deterministically inspect every GPU draw call, scissor clip rectangle, alpha tint, and text overlay without requiring a live browser GPU context in unit/E2E Vitest workers, the test suite uses a lightweight recording harness:

- **Sprite Draw Recording (`renderer.draw(frame, x, y, options)`)**:
  Captures `{ kind: 'sprite', frame, x, y, atlas, width, height, tint }` in exact emission order, enabling verification of:
  - 6-stage rendering order (`Floors -> Walls -> Objects -> Extras -> Crosshairs -> Text`).
  - Sheet routing (`MaxiMap(S)`, `Act2Map(S)`, `Act4Map(S)`, `ExTnMap(S)`).
  - Screen-space projection (`projectAutomapCellScreenRect`) with `1/10` (`bMinimap = false`) and `1/20` (`bMinimap = true`) divisors and `yOffset` (`+3` vs `+1`).
  - Fade mode alpha tints (`1.0`, `0.75`, `0.45`, `0.25`).
- **Crosshair Quad Recording (`renderer.drawSolidQuad(...)`)**:
  Captures `{ kind: 'quad', x0, y0, x1, y1, x2, y2, x3, y3, color }` for each of the 12 radial line segments per crosshair (`AUTOMAP_CROSSHAIR_COLORS.player`, `ally`, `monster`, `boss`).
- **WebGL Scissor Recording (`renderer.gl.enable/scissor/disable`)**:
  Captures `gl.scissor(x, glY, width, height)` where `glY = screenHeight - (rect.y + rect.height)`.
- **Bitmap Font Recording (`font.drawText(renderer, text, x, y, options)`)**:
  Captures `{ kind: 'text', text, x, y, colorCode }` for exit/dungeon target labels and top-right HUD level/difficulty/timer strings.

---

## 4. Execution Instructions

Run the complete 4-tier E2E Automap 1.13c test suite:

```bash
npx vitest run tests/e2e-automap-113c/
```

Run an individual tier:

```bash
npx vitest run tests/e2e-automap-113c/tier1-feature-coverage.test.ts
npx vitest run tests/e2e-automap-113c/tier2-boundary-corner.test.ts
npx vitest run tests/e2e-automap-113c/tier3-cross-feature-combinations.test.ts
npx vitest run tests/e2e-automap-113c/tier4-real-world-scenarios.test.ts
```

Run TypeScript strict typecheck across the repository:

```bash
npm run typecheck
```

Run the full-spectrum 136-level offline + headless Chrome CDP verification script:

```bash
npx tsx scripts/verify-automap.ts
```