[R2-9][P3] Add game-ui test coverage (108 pub fns, 0 tests — grade F)

[MichaelFisher1997]

Part of #839 — [Audit][Round 2] A++ umbrella.
Phase: P3 · Finding: R2-9 · Priority: HIGH (grade F module)

Problem

game-ui has 108 pub fns, 0 tests. All UI screens, menus, and widgets are untested. This is one of two grade-F modules in the codebase (the other is engine-rhi, addressed in R2-4). UI bugs (broken navigation, dead buttons, layout regressions on resize) ship silently.

Evidence

• find modules/game-ui -name '*.zig' | xargs grep -l '^test ' → zero results
• modules/game-ui/src/screens/world.zig is 969 LOC; screens/home.zig, screens/world_list.zig, screens/graphics.zig, screens/settings.zig are all untested
• 108 pub fns across the module (screen lifecycle, input handling, widget state machines, settings binding)
• Co-located tests are an explicit AGENTS.md rule: "Add tests alongside modules"

For contrast:

• engine-math ratio 4.00 (A)
• world-core ratio 2.33 (A)
• world-meshing ratio 2.09 (A)
• game-ui ratio 0.00 (F)

Fix

Three layers, in order of return-on-investment:

Layer 1 — Pure state machines (highest ROI, no GPU)

Extract and test the pure-logic cores of each screen:

• WorldListScreen state: filter/sort logic, world-metadata parsing, selection state → world_list_state.zig. Test sorting, filtering, pagination.
• SettingsScreen state: keybind rebinding, graphics-preset application, value clamping → settings_state.zig. Test value clamping, keybind conflict detection.
• GraphicsMenu state: preset matrix, slider-to-setting mapping → graphics_menu_state.zig. Test preset application, slider clamping.

Target: 60+ tests across these state modules. Lifts game-ui ratio from 0.00 to ~0.5.

Layer 2 — Mock UI host

Build on engine-ui's existing test harness (if any). Create modules/game-ui/src/test_host.zig:

• MockInputHost — implements IInputHost (fake keyboard/mouse events)
• MockDrawHost — implements IDrawHost (records draw calls instead of executing them)
• MockNavigationHost — implements INavigationHost (records push/pop transitions)

Then screens/*_tests.zig can exercise lifecycle: init → input("Enter") → update() → assert navigated to next screen.

Layer 3 — Visual regression hooks

Where headless graphics rendering is feasible (R2-4 mock RHI), wire 2-3 happy-path screen tests through the existing headless-screenshot skill to catch layout regressions.

Verification

• nix develop --command zig build test -- --test-filter "WorldListState" and similar
• nix develop --command zig build test overall still green
• Coverage target: game-ui ratio ≥ 0.4 (43+ tests for 108 pub fns). Stretch: ≥ 0.7 (grade B+).
• Co-locate tests under modules/game-ui/src/screens/*_tests.zig per AGENTS.md.
• Wire into the test aggregator at src/tests.zig.

Constraints

• Tests must run without a GPU (Layer 1 + 2) or with mock RHI (Layer 3).
• No production code changes unless extraction is required to make it testable (Layer 1). Extracted state modules are a legitimate refactor.
• One PR per layer is acceptable.
• Conventional commits: test(game-ui): add WorldListScreen state tests, test(game-ui): add mock UI host for screen lifecycle, etc.

Notes

• Coordinate with R2-8 (silent-error surfacing) — the toast-mock harness developed here benefits both.
• Layer 1 extraction (state-machine pull-out) is also good SRP discipline — fat screens like world_list.zig and world.zig (969 LOC) benefit from having their pure cores separated from rendering.
• Future: a game-ui-test-coverage CI gate (codecov threshold) would prevent regression. Out of scope here; tracked in Production-Readiness Audit: missing CI / lint / benchmark / regression guardrails #834.

Tracking: #839

[github-actions]

Validation Report

I verified the audit findings against the current tree on dev (HEAD 9c6e53d):

Numbers confirmed

• 108 pub fns in game-ui ✅ (28 in screen lifecycle + widget code plus 80 more inside the impl blocks; the audit counts all pub fn matches in find modules/game-ui -name '*.zig')
• Zero ^test blocks in the entire module ✅ — no co-located test files exist
• Largest offenders: screens/world.zig (969 LOC), screens/settings.zig (533 LOC), screens/world_list.zig (501 LOC), screens/graphics.zig (354 LOC)
• src/tests.zig currently registers no game-ui test imports — first PR in this finding should wire the aggregator too

Related PRs

• 32 new tests for game-core and game-ui modules #608 ("32 new tests for game-core and game-ui modules") was CLOSED, not merged — this is an important signal. A previous attempt to land game-ui tests stalled. Any new PR should look at why 32 new tests for game-core and game-ui modules #608 didn't merge (likely test flakiness, GPU dependencies, or scope creep) and address those blockers early.
• refactor: resolve SOLID architecture seams #838 / refactor: decouple world and RHI interface seams #835 / refactor: extract RHI and world runtime responsibilities #827 (recent SOLID extractions) just landed and may have changed the surface area since this audit was captured. screens/world.zig and screens/world_list.zig are prime candidates for further extraction before tests can be written.

Implementation notes worth surfacing before code lands

1. Layer 2 interface names are inaccurate. The issue names IInputHost, IDrawHost, INavigationHost as existing interfaces to mock, but none of those names exist in the codebase (grep across all modules/ returned zero hits). The actual abstraction surface is:

   • IScreen (vtable) — modules/game-ui/src/screen.zig:183
   • ScreenManager — modules/game-ui/src/screen.zig:241 with pushScreen, setScreen, etc.
   • EngineContext — modules/game-ui/src/screen.zig:19 (the host struct screens actually consume)

   The mock harness should target EngineContext + ScreenManager operations, not invented interfaces. This is a meaningful correction before Layer 2 lands.

2. engine-ui has no general test harness — only modules/engine-ui/src/font.zig has co-located tests. The "build on engine-ui's existing test harness (if any)" caveat in the issue is real: there is none to build on. Layer 2 is greenfield.

3. Layer 1 extraction is required and non-trivial. Pure state cores don't exist yet — they have to be carved out of:

   • WorldListScreen (501 LOC, mixed with I/O + render + level.dat parsing)
   • SettingsScreen (533 LOC)
   • GraphicsMenu (354 LOC)

   Worth proposing the extracted modules' public surface in the PR description so reviewers can sign off before the test code lands.

Scope

The three-layer split is sound and the author is right that one PR per layer is acceptable. This is a multi-PR, multi-week effort — I recommend creating three tracking sub-issues under #845 (or under the #839 umbrella):

• R2-9a: Layer 1 — extract + test pure state cores (no GPU, biggest coverage win)
• R2-9b: Layer 2 — mock EngineContext + ScreenManager harness + lifecycle tests
• R2-9c: Layer 3 — visual regression via headless-screenshot skill

Each sub-issue should reference #845 and close it when all three merge.

Suggested first PR (Layer 1a — highest ROI)

Carve WorldEntry/LevelDat parsing + filter/sort logic out of screens/world_list.zig into a new world_list_state.zig. The readLevelDat/writeLevelDat functions at screen.zig:39-99 are already nearly pure (only side effect is filesystem) — ideal first targets. Target: 20+ tests covering malformed JSON, missing fields, generator-id reconciliation, sort stability. Should land without touching any rendering code.

Will not push code per the issue-only directive.

[github-actions]

Comment posted to issue #845. Key points I contributed:

Validation — confirmed 108 pub fns / 0 tests, plus the LOC numbers (world.zig 969, settings.zig 533, world_list.zig 501, graphics.zig 354). Verified src/tests.zig registers no game-ui tests today.

Critical correction — the issue's Layer 2 references IInputHost/IDrawHost/INavigationHost which don't exist anywhere in the codebase. The real surface is IScreen (screen.zig:183), ScreenManager (screen.zig:241), and EngineContext (screen.zig:19). Mocks should target those.

Related work flagged — PR #608 ("32 new tests for game-core and game-ui") was closed, not merged. A prior attempt to land game-ui tests stalled. Any new PR should investigate why first.

Scope — recommended three tracking sub-issues (R2-9a/b/c) under #845/#839 for the three layers.

Suggested first PR — Layer 1a: extract readLevelDat/writeLevelDat (+ filter/sort logic) from screens/world_list.zig into a new pure state module. The JSON parsing functions at screen.zig:39-99 are already nearly pure and the easiest first target.

opencode session  |  github run