104 lines
8.2 KiB
Markdown
104 lines
8.2 KiB
Markdown
# Diablo II v1.13c Parity Test Infrastructure (`TEST_INFRA.md`)
|
||
|
||
This document defines the comprehensive test infrastructure, architectural contracts, test runner configuration, and execution guidelines for the Diablo II v1.13c parity test initiative (Issues #562–#712).
|
||
|
||
---
|
||
|
||
## 1. Test Architecture & Runner Setup
|
||
|
||
### Test Framework
|
||
- **Test Runner**: [Vitest v2.1.9](https://vitest.dev/)
|
||
- **Runtime Environment**: Node.js v20+ with native TypeScript compilation and ESM modules.
|
||
- **Assertion Library**: Vitest BDD assertions (`describe`, `it`, `expect`) with strict value and deep object matching.
|
||
- **Execution Mode**: Hermetic, isolated, parallelized test runner with sub-millisecond execution times for model and state-tree tests, and isolated headless Chromium browser automation for frontend flows.
|
||
|
||
### Standard Test Commands
|
||
|
||
```bash
|
||
# Run all tests in the repository
|
||
npx vitest run
|
||
|
||
# Run only the 4-tier Diablo II v1.13c parity test suite
|
||
npx vitest run tests/e2e-parity/
|
||
|
||
# Run individual tiers
|
||
npx vitest run tests/e2e-parity/tier1-feature-coverage.test.ts
|
||
npx vitest run tests/e2e-parity/tier2-boundary-corner.test.ts
|
||
npx vitest run tests/e2e-parity/tier3-cross-feature.test.ts
|
||
npx vitest run tests/e2e-parity/tier4-real-world-scenarios.test.ts
|
||
|
||
# Run migrated legacy test suites (zero regressions)
|
||
npx vitest run tests/frontend-flow.test.ts tests/netproto-bncs-packets.test.ts tests/netproto-online-flow.test.ts tests/e2e-bnet-create-account.test.ts
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Four-Tier Parity Test Suite Structure
|
||
|
||
The parity test suite is organized into four complementary verification tiers inside `tests/e2e-parity/`:
|
||
|
||
```
|
||
tests/e2e-parity/
|
||
├── helpers.ts # Shared test fixtures, mock collision oracles, item builders, and math helpers
|
||
├── tier1-feature-coverage.test.ts # Tier 1: 48 Feature Coverage Tests (6 per batch across 8 batches)
|
||
├── tier2-boundary-corner.test.ts # Tier 2: 48 Boundary & Edge Case Tests (6 per batch across 8 batches)
|
||
├── tier3-cross-feature.test.ts # Tier 3: 8 Pairwise Cross-Feature Integration Tests
|
||
└── tier4-real-world-scenarios.test.ts # Tier 4: 5 Full-Lifecycle Gameplay Scenarios
|
||
```
|
||
|
||
### Tier 1: Feature Coverage (48 Tests)
|
||
Guarantees primary positive-path behavior across all 8 subsystem batches:
|
||
- **Batch 1 (Issues #562–#579)**: 25Hz simulation tick accumulator (40ms ticks), isometric 2:1 projection math, sub-tile conversions, and diminishing return curves.
|
||
- **Batch 2 (Issues #580–#597)**: Universal DT1 tile loading (`Blank.dt1`, `InvisWal.dt1`, `Warp.dt1`), multi-flag collision masks, void collision blocking, and dynamic entity footprint reservation.
|
||
- **Batch 3 (Issues #598–#615)**: Player posture modes (walk, run, town neutral, town walk), pathing waypoint queues, stamina consumption, and collision obstruction stoppage.
|
||
- **Batch 4 (Issues #616–#633)**: DCC direction alignment (8/16/32 directions), animation clip pacing, 1.13c FCR/IAS speed formulas, and cast overlay alignment.
|
||
- **Batch 5 (Issues #634–#651)**: DT1 block layout decoding (sub-blocks 0..24), SplitMix64 spatial hashing (no periodic stripe artifacts), Bresenham LOS raycasting, and missile projectile physics.
|
||
- **Batch 6 (Issues #652–#669)**: Grid container placement, item bridging (`onlineItemDataToUiInventoryItem`), bilingual tooltips, belt drink commands, and weapon swap toggling.
|
||
- **Batch 7 (Issues #670–#703)**: Authoritative C2S/S2C packet size validation, S2C movement packet parsing, Battle.net character name filtering, and corpse assignment tracking.
|
||
- **Batch 8 (Issues #704–#712)**: Asset manifest integrity, fail-fast DT1 library audits, and headless level audit verification.
|
||
|
||
### Tier 2: Boundary & Corner Cases (48 Tests)
|
||
Stress tests extreme numerical bounds, edge conditions, invalid inputs, and corrupt state:
|
||
- Zero, negative, and fractional delta times in the simulation tick loop.
|
||
- Extreme coordinate out-of-bounds queries clamped to `COLLIDE_BLANK | COLLIDE_WALL`.
|
||
- Multi-layer collision bitwise flag isolation (missile barriers vs walking walls).
|
||
- Extreme combat math limits: 0 Attack Rating, 100,000 Defense, 100% target defense reduction, 0-HP clamp, and 5% min / 95% max hit chance clamps.
|
||
- Diminishing return caps for Faster Cast Rate (+1000% FCR clamped to 75%).
|
||
- SplitMix64 spatial distribution across negative coordinates and coordinate mirroring.
|
||
- Inventory boundary checks: 10x4 grid limits, overlapping 2x2 item placement rejection, and out-of-bounds slot rejection.
|
||
- Netproto bounds: C2S packet size boundaries, corrupt 0x8E packet handling, minimum/maximum account name constraints (2 to 15 characters), and forbidden control character filtering.
|
||
|
||
### Tier 3: Pairwise Cross-Feature Interactions (8 Tests)
|
||
Verifies multi-subsystem contracts across overlapping modules:
|
||
- **X1 (Movement + Weapon Swap + Skill Cast)**: Swapping weapon sets while running updates effective cast rate and interrupts run motion upon skill cast.
|
||
- **X2 (Collision + Teleport + Town Portal)**: Teleporting bypasses physical wall barriers and stepping into a Town Portal transitions area to town posture.
|
||
- **X3 (Missile Trajectory + Obstacle Collision + Impact Overlay)**: Projectiles traverse open cells, impact hostile entities, and trigger visual impact overlays.
|
||
- **X4 (S2C Server Correction + Reassign)**: Local client prediction is authoritatively corrected by S2C UnitReassign packets.
|
||
- **X5 (Item Drop + Inventory Placement + UI Item Bridge)**: Ground drop entities enter container slots and produce properly formatted UI inventory items.
|
||
- **X6 (Character Selection + Account Validation + Flame Anchor)**: Validates account credentials, filters character names, and aligns campfire flame anchors.
|
||
- **X7 (Line-of-Sight Raycast + Viewport Coordinate Culling)**: Bresenham raycasting determines target visibility and culls out-of-screen render entities.
|
||
- **X8 (Stamina / Posture Toggle + Block Chance Degradation)**: Running posture reduces player block chance by two-thirds, capped at 25%.
|
||
|
||
### Tier 4: Real-World Gameplay Scenarios (5 Scenarios)
|
||
Verifies authentic full-lifecycle gameplay journeys under 1.13c ground truth:
|
||
1. **Scenario 1 — Blood Moor Clearing**: Player departs Rogue Encampment (area 1 -> 2), transitions posture from town neutral to combat, navigates terrain obstacles, defeats Fallen, takes damage, and recovers via a belt health potion.
|
||
2. **Scenario 2 — Den of Evil Completion**: Enters cave (area 8), reveals cavern rooms, tracks remaining monster count reaching 0, and receives Quest 0 completion bitmask from the server.
|
||
3. **Scenario 3 — Countess Tower Run**: Descends Forgotten Tower cellars (areas 21 -> 25), battles Superunique Countess with FCR-boosted spells, slays her, and loots a guaranteed Ral Rune (`r08`) into inventory.
|
||
4. **Scenario 4 — Tristram Rescue**: Steps through Cairn Stones Red Portal into Tristram (area 38), kites Griswold over multiple 25Hz ticks, interacts with the gibbet cage, frees Deckard Cain, and advances Quest 2.
|
||
5. **Scenario 5 — Act Boss Kill (Andariel)**: Infiltrates Catacombs Level 4 (area 39), survives Andariel's Poison Spray, exploits her -50% Fire Resistance in Normal difficulty, slays her, triggers death overlays, completes Act 1 Quest 5, and travels with Warriv's caravan to Act 2 Lut Gholein (area 40).
|
||
|
||
---
|
||
|
||
## 3. Ground Truth Invariants & Simulation Contracts
|
||
|
||
1. **Diablo II v1.13c Ground Truth Invariant**:
|
||
All formulas, packet sizes, collision flags, town level IDs, and animation step calculations strictly mirror 1.13c assembly from `D2Common.dll`, `D2Game.dll`, `D2Client.dll`, and `D2Launch.dll`.
|
||
2. **Discrete 25Hz Simulation Tick**:
|
||
Simulation logic runs on fixed 40ms intervals (`D2_TICK_MS = 40`). Sub-millisecond elapsed times accumulate until 40ms threshold is reached.
|
||
3. **Universal DT1 Tiles**:
|
||
Universal DT1s (`Blank.dt1`, `InvisWal.dt1`, `Warp.dt1`) are loaded unconditionally with `COLLIDE_BLANK | COLLIDE_WALL` for void safety.
|
||
4. **SplitMix64 Spatial Hash**:
|
||
Tile variant selection uses 64-bit SplitMix64 spatial hashing to prevent 45-degree mechanical tiling artifacts.
|
||
5. **No Facade Tests**:
|
||
All tests assert on real models (`ClientWorld`, `HudModel`, `CollisionGridOracle`) and verify state mutations, container contents, and packet serialization without mocking away critical domain logic.
|