Add CI workflow and reusable test-harness foundation

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-09-05 00:06:18 +03:00
parent 994ce3be73
commit a6f938a0da
4 changed files with 189 additions and 0 deletions
@@ -0,0 +1,63 @@
+# Tests
+
+Headless, deterministic tests that run in CI (`.github/workflows/ci.yml`) and locally via
+`bash run_tests.sh`. Nothing here needs a GPU — even the UI checks assert computed geometry
+instead of comparing pixels, so the whole suite runs in plain headless Godot.
+
+## Run
+
+```bash
+bash run_tests.sh                 # lint + every headless test (+ gameplay assertions)
+bash run_tests.sh --no-gameplay   # skip the slower full-scene gameplay pass (what CI runs)
+
+# a single test:
+godot --headless --script tests/<name>.gd
+```
+
+Set `GODOT` to point at a specific binary: `GODOT=/path/to/godot bash run_tests.sh`.
+
+## The six layers
+
+Order is cheapest first. The middle layers are where "don't break interactions/UI by accident"
+is actually won — none of them need a screenshot.
+
+| Layer | What it drives | Example here |
+|---|---|---|
+| **Scene smoke** | Instantiate a scene headless, assert no errors | `level_switch_test.gd` (level modules load, no geometry leaks) |
+| **Unit / logic** | Pure functions, no scene tree | `logic_test.gd`; `harness_selftest.gd` (proves `test_helpers.gd`) |
+| **Signal contract** | Emit a signal, assert args/count | *to add:* `died` / `health_changed` / `all_defeated` fire correctly |
+| **Interaction** | Feed synthetic input, step frames, assert state | `touch_controls_test.gd`, `matador_charge_test.gd` |
+| **Scenario / replay** | Scripted inputs + fixed seed over a whole fight | `difficulty_sim.gd` (a report), `bear_boss_test.gd` |
+| **UI layout** | Resize the viewport, query `Control` rects | `ui_layout_test.gd` (on-screen, text fits, tap size, scroll) |
+
+## Shared harness
+
+`test_helpers.gd` (`class_name TestHelpers`) holds the primitives every test used to re-implement:
+
+- `TestHelpers.make_rng(seed)` — a **seeded** `RandomNumberGenerator`. Determinism is the
+  precondition for the interaction/scenario layers; seed the RNG here instead of the global
+  `randf()`/`randi()` so a test replays identically. (Reworking gameplay code to accept an injected
+  RNG is tracked in the refactor plan's Workstream 2.)
+- `TestHelpers.approx(a, b, eps)` / `vec_approx(a, b, eps)` — float/vector comparisons with
+  tolerance, because computed positions never compare exactly equal.
+- A pass/fail tally: `t.ok(cond, msg)` and `t.report()`, which prints `Results: X passed, Y failed`
+  and returns the process exit code.
+
+New tests follow the existing idiom: `extends SceneTree`, `_init()` → `_run.call_deferred()`,
+print `  PASS:` / `  FAIL:`, and `quit(t.report())`.
+
+## Next step: GdUnit4
+
+The hand-rolled harness is enough for CI today. The plan's Workstream 5 adopts
+[GdUnit4](https://github.com/MikeSchulze/gdUnit4) for a fluent assertion API, its **scene runner**
+(synthetic input + frame stepping — purpose-built for the interaction layer), and HTML/JUnit
+reports. Adoption is incremental, so the current tests keep running throughout:
+
+1. Add it under `addons/gdUnit4` (AssetLib in-editor, or a git submodule) and enable the plugin in
+   Project Settings → Plugins.
+2. Point CI at GdUnit4's own GitHub Action (it publishes the JUnit report to the PR) alongside the
+   existing `run_tests.sh` step.
+3. Port suites one at a time — `test_helpers.gd`'s primitives map directly onto GdUnit4 assertions,
+   so a ported test is smaller, not larger.
+
+Do **not** vendor GdUnit4 into this repo by hand; install it through AssetLib or a submodule.