troytt
/
diablo2-web
1
0
Fork 0
Code Issues 96 Pull Requests Packages Projects Releases Wiki Activity
diablo2-web/TEST_INFRA.md

8.2 KiB
Raw Blame History

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
  • 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

# 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.