feat(test): test bridge, headless scene tests, functional suite, MazeSession split

[rtkelly13]

Stack 3 of 4 — split out of #6. Based on #9; review that first.

Adds functional (behavioural) testing across the two layers that had no coverage at all: the Godot scene/UI layer and the deployed browser build. Then segregates behaviour from Godot so most of it can be tested without the engine.

Why a bridge was needed

A Godot web export renders everything into a single <canvas>. Playwright's locator model — getByRole, getByText, toBeVisible — sees nothing but one element. Playwright can already drive the app (real key/mouse events reach the engine); what was missing was any way to observe it.

scripts/testing/TestBridge.cs supplies that, opt-in via ?test=1 (or any ?seed=):

window.__mazeTestApi   "1" when live, absent when disabled
window.__mazeState     JSON string of app state, republished on change
window.__mazeCommand   function(jsonString), fire-and-forget

Every design choice is a verified constraint, not a preference:

• Fire-and-forget commands — Godot's docs never state a create_callback return value reaches JS, so results are observed via state rather than depending on unspecified behaviour. Callbacks must also take exactly one Array arg, which a single JSON entry point satisfies.
• No Eval — the docs say it "may be disabled in custom export templates", and this project uses a patched one. GetInterface + property assignment avoids that path.
• Hand-rolled JSON — the web build is trimmed, and reflection-based serializers are exactly what trimming breaks, failing only in the browser.
• Protocol split into TestBridgeProtocol (Godot-free) so the NUnit suite covers the fiddly parsing — 54 tests.

It also implements the URL seeding the visual suite was waiting on.

Scene tests, and why not gdUnit4Net

gdUnit4Net was tried first. On Godot 4.7.1 with gdUnit4.api 5.1.0-rc5: builds and restores cleanly, logic-only tests pass, but every [RequireGodotRuntime] test fails with Starting GodotRuntimeExecutor failed. The operation has timed out. Setting <GodotProjectDir> and pre-importing didn't help.

Isolated the cause: Godot 4.7.1 runs this project headless and executes its C# fine (the GameState autoload's _Ready fires). So the blocker is gdUnit4's own executor — consistent with its stated support stopping at Godot 4.4.1, last release June 2025.

So tests/scene/SceneTestRunner.cs is a ~200-line in-engine runner: checks, a tally, a process exit code. Compiled only under -p:IncludeSceneTests=true so it never ships in a game export. This is the first real coverage of scripts/ui/ (~4300 lines) — the nearest thing before was a test reading menu.tscn as text and asserting it contained "ComparisonButton".

Segregating behaviour from Godot

Measured coupling showed the codebase was already nearly segregated — the test project just didn't include it. AnimationController (254 lines, zero Godot refs) compiles into the Godot-free suite unchanged, and had zero tests.

GameState was 266 lines whose entire Godot surface was : Node, _Ready, _ExitTree, one GD.Print and one Mathf.Clamp. It's now a thin adapter over MazeSession, which has no Godot dependency. Public API unchanged, so nothing in scripts/ui needed editing.

It found a real bug on its first run. GameState.LoadImportedMaze wraps dead ends then builds a graph, and that combination threw Nullable object must have a value — importing any maze crashed the app. A dead-end cell has exactly one direction (the one you arrived from), so GraphBuilder's corridor walk treated it as neither junction nor terminus and dereferenced null. Several existing tests did wrapping; several did graph building; none did both.

Fixed by dropping the edge rather than pointing it at the dead-end cell — the node set is junctions + start/end and consumers use graph.Nodes[edge.Point], so inventing a node target would trade a null-deref for a KeyNotFoundException.

Verification (executed, not reasoned)

Correcting an earlier claim of mine: Godot code is buildable here — GodotSharp targets net8.0.

• 550 tests pass (was 443).
• Godot project builds clean, with and without -p:IncludeSceneTests=true (proving the runner is excluded from normal builds).
• 7/7 scene tests pass in real Godot 4.7.1 headless, exit 0 — and the failure path was checked by deliberately breaking a check: 6/7, exit 1, so CI genuinely gates. Confirmed on real CI too.
• Reverting only the GraphBuilder guard fails 10 tests while the plain-maze control still passes.
• All 18 Playwright specs enumerate; the 4 harness self-tests pass.

⚠️ Not verified: whether the bridge behaves under the patched web export template. Both browser suites are gated on MAZE_TEST_BRIDGE=1 and currently skip rather than risk a false red. #6 makes the smoke test answer this automatically on every deploy.

Docs

docs/TESTING.md (layer map, coupling measurements, gdUnit4Net findings, known gaps) and docs/TEST_BRIDGE.md (contract, per-decision rationale, verification-status table, security notes).

---

Generated by Claude Code