[R2-10][P3] Add world-runtime test coverage (ratio 0.08) + co-locate input/ecs tests

[MichaelFisher1997]

Part of #839 — [Audit][Round 2] A++ umbrella.
Phase: P3 · Finding: R2-10 · Priority: HIGH (grade D critical glue)

Problem

world-runtime — the world facade that ties streaming, rendering, mutation, lighting, save, LOD, and GPU buffers together — has 165 pub fns and 14 tests (ratio 0.08). This is the system's critical glue; defects here cascade into every gameplay system.

Also: engine-input and engine-ecs violate the AGENTS.md "tests alongside modules" rule by relying on test files in src/ (src/input_tests.zig, src/ecs_tests.zig).

Evidence

Coverage table (Round 2 audit):

• world-runtime: 165 pub fns, 14 tests, ratio 0.08 (grade D)
• engine-input: 44 pub fns, 0 internal tests, 6 in src/input_tests.zig (grade C, violates co-location)
• engine-ecs: 28 pub fns, 0 internal tests, 7 in src/ecs_tests.zig (grade C, violates co-location)

For contrast: world-core ratio 2.33, world-meshing ratio 2.09.

The 14 existing world-runtime tests are scattered (world.zig, world_streamer.zig, world_renderer.zig, gpu_mesher.zig, lighting_engine.zig, lpv_grid_builder.zig, chunk_queue_coordinator.zig, world_mutation.zig). Coverage is shallow: most pub fns on the World facade (world.zig, 1112 LOC, 46 pub methods, 33-method vtable) have no test.

Fix

Tier 1 — world-runtime facade tests

Focus on the 33-method IWorld vtable (world.zig). For each method, add at least one happy-path test and one failure-path test using a mock-able world setup:

• init / deinit lifecycle — assert resource cleanup ordering
• setBlock / getBlock — round-trip; out-of-bounds error; chunk-not-loaded error
• streamChunk / unloadChunk — assert streamer queue state before/after
• render — assert it delegates to WorldRenderer without mutating state
• save / load — round-trip; corrupt-save error; missing-save error
• getStats / telemetry — assert counters increment on stream/load/save
• Simulation/Render/Telemetry role-interface views — assert they expose only their slice

Build a MockWorldSubsystems harness (modules/world-runtime/src/test_harness.zig): fake streamer, fake renderer, fake mutation coordinator. The facade orchestrates them; tests assert on the orchestration, not the subsystem internals.

Target: 60+ tests. Lifts ratio from 0.08 to ~0.4 (grade B).

Tier 2 — Co-locate engine-input tests

Move src/input_tests.zig → modules/engine-input/src/input_tests.zig. Update src/tests.zig aggregator to import from the new location. Re-run to confirm green.

Tier 3 — Co-locate engine-ecs tests

Move src/ecs_tests.zig → modules/engine-ecs/src/ecs_tests.zig. Same aggregator update.

Tier 4 — Subsystem tests

For each sibling file in world-runtime/src/ (world_streamer.zig, world_renderer.zig, gpu_mesher.zig, lighting_engine.zig, lpv_grid_builder.zig, chunk_queue_coordinator.zig, world_mutation.zig), add 5–10 tests focused on edge cases (empty input, max-size input, error propagation, threading invariants).

Verification

• nix develop --command zig build test -- --test-filter "World" runs the new suite
• nix develop --command zig build test overall green
• Coverage targets:
  • world-runtime: ratio ≥ 0.4 (currently 0.08). Stretch: ≥ 0.7 (grade A−)
  • engine-input: ratio ≥ 0.3, tests co-located
  • engine-ecs: ratio ≥ 0.3, tests co-located
• AGENTS.md co-location: find modules -name '*_tests.zig' | xargs grep -l '^test ' includes the new files

Constraints

• Tests must run without a GPU (mock RHI from R2-4) for facade/subsystem orchestration tests.
• Coordinate with R2-1 (LODManager decomposition) — tests written against the new extracted interfaces are more durable than tests against the current fat orchestrator.
• Conventional commits: test(world-runtime): add IWorld facade lifecycle tests, refactor(engine-input): co-locate tests per AGENTS.md, etc.

Notes

• The MockWorldSubsystems harness built here is reusable for game-core/game-ui tests (R2-9).
• R2-1's LODManager extraction will make World facade testing tractable — the LOD subsystem will be mockable.
• Out of scope but worth noting: world-core (ratio 2.33, grade A) is the gold standard — new tests should follow its style.

Tracking: #839

[github-actions]

R2-10 analysis & suggested breakdown

Verified the audit numbers against dev HEAD:

• world-runtime has 14 tests scattered across lighting_engine.zig (2), chunk_queue_coordinator.zig (2), world_renderer.zig (3, mostly pure helpers — not facade), world_mutation.zig (7). Confirmed world.zig (1112 LOC) ships zero internal tests.
• src/input_tests.zig (93 LOC, 6 tests) and src/ecs_tests.zig (165 LOC, 7 tests) live at the repo root; src/tests.zig:26 and src/tests.zig:108 aggregate them. AGENTS.md §Code Style — Adding Unit Tests clearly mandates co-location, so Tiers 2 & 3 are unarguable rule violations.
• Umbrella [Audit][Round 2][Umbrella] A++ Architecture & Maintainability Roadmap #839 already places R2-10 in Wave 4 behind R2-1 (LODManager decomposition) and R2-2 (LODMesh/LODChunk encapsulation) explicitly because the current fat orchestrator is hard to test. The Issue body reiterates this coordination need.

Why this should be split into ≥ 3 sub-issues

The 4 Tiers are independent in review surface, risk profile, and reviewer pool. Bundling them in one PR would (a) hit the recommended reviewable size limit, (b) confuse reviewers about which tier failed CI, and (c) block the trivially-mechanical co-location moves behind the test-harness work.

Suggested slicing:

Sub-issue A — Test co-location (Tier 2 + Tier 3)

Mechanical, ~30 LOC diff, behavior-preserving, ~15 min review.

• git mv src/input_tests.zig modules/engine-input/src/input_tests.zig
• git mv src/ecs_tests.zig modules/engine-ecs/src/ecs_tests.zig
• Rewrite the two @import paths in src/tests.zig (lines 26 and 108) to relative paths.
• Adjust module-relative imports inside the moved files (@import("engine-input"), etc.).
• Re-run nix develop --command zig build test to confirm green.

Why first: zero design surface, zero new code, immediately closes two rule violations, and can land today without waiting on R2-1. Conventional commit: refactor(tests): co-locate engine-input/engine-ecs tests per AGENTS.md.

Sub-issue B — MockWorldSubsystems harness (Tier 1, foundation)

Adds modules/world-runtime/src/test_harness.zig, no new assertions. ~150 LOC.

• Fake IWorldStreamer / IWorldRenderer / mutation coordinator reachable through the facade via the existing role interfaces (IWorldRenderView, IWorldSimulation, etc.).
• Stub RHI from R2-4's mock contract.
• No behavior change; this is pure infrastructure for Sub-issues C/D.

Conventional commit: test(world-runtime): add MockWorldSubsystems harness.

Sub-issue C — IWorld vtable happy/failure-path tests (Tier 1, 60+ tests)

Depends on B and (per umbrella) ideally on R2-1 / R2-2. Tests every one of the 33 vtable fns with both paths as the Issue body specs:

• init/deinit resource ordering
• setBlock/getBlock round-trip + out-of-bounds + chunk-not-loaded
• streamChunk/unloadChunk queue assertions
• render non-mutation delegation
• save/load round-trip + corrupt/missing-save
• Stats/telemetry counter deltas
• Role-interface exposure narrowing (simulation() / renderView() / telemetry())

Should explicitly gate on R2-1 / R2-2 landing per umbrella's Wave ordering. Until then, testing the current orchestrator pins tests to the soon-to-change interface and creates churn.

Conventional commit: test(world-runtime): add IWorld facade lifecycle tests.

Sub-issue D — Subsystem edge-case tests (Tier 4)

Lower-risk, 5–10 tests per file across world_streamer.zig, world_renderer.zig, gpu_mesher.zig, lighting_engine.zig, lpv_grid_builder.zig, chunk_queue_coordinator.zig, world_mutation.zig. Can land in parallel with C after R2-1.

Proposed verification per Sub-issue

• A: nix develop --command zig build test + find modules -name '*_tests.zig' | xargs grep -l '^test ' shows the moved files.
• B: nix develop --command zig build test -- --test-filter "MockWorld" green; no regression in zig build test.
• C: nix develop --command zig build test -- --test-filter "World" runs the new suite; zig fmt src/ clean; zig build -Doptimize=ReleaseFast clean.
• D: per-subsystem --test-filter.

Sequencing recommendation

1. Land Sub-issue A immediately (no R2-1 dependency).
2. Land Sub-issue B alongside (or after) R2-1 (per umbrella Wave 4 ordering).
3. Land Sub-issue C after R2-1 + B, ideally after R2-2.
4. Land Sub-issue D in parallel with C.

Coverage targets confirmed

• world-runtime: 0.08 → ≥ 0.4 (stretch 0.7) ✔ as stated.
• engine-input: 0 → ≥ 0.3 (also fixes AGENTS.md violation).
• engine-eos: 0 → ≥ 0.3 (also fixes AGENTS.md violation).

Out-of-scope but worth flagging in the umbrella: R2-9 (game-ui) shares the same harness dependency and should be tracked as a follow-up sibling issue.

Happy to draft any of these sub-issues on request.

[github-actions]

Comment posted on issue #847: #847 (comment)

Summary:

• Classification: Feature Request (test coverage) — automated-audit finding from umbrella [Audit][Round 2][Umbrella] A++ Architecture & Maintainability Roadmap #839
• Validation: Confirmed 14 tests across listed subsystem files, verified src/tests.zig aggregator imports, confirmed world.zig has 0 internal tests
• Duplicates/PRs: None exist yet
• Scope: Recommended splitting into 4 sub-issues (A: co-location, B: harness, C: vtable tests, D: subsystem tests) sequenced after R2-1/R2-2 per umbrella's Wave 4 ordering, with Sub-issue A being independent and immediately actionable

opencode session  |  github run