NetDeck: headless test runner — unit + integration suites, E2E as separate build

- emulator/tests/: harness.h (TEST/EXPECT framework, input + serial +
  framebuffer helpers), shim_globals.cpp (shim externs for test binaries,
  replacing main.cpp ownership)
- unit_tests.h (14): map/door/LOS/BFS/cover/link state machine/trace/
  spike/reinforcement/win/loss/reset — deterministic fixed-seed, sim
  stepped tick by tick
- integration_tests.h (7): keyboard->pollKeyboard->handleKey pipeline,
  beacon clicks -> squad movement, full network journey via clicks,
  hover-sever (incl. safe sever during trace), daemon gating
- e2e_tests.cpp (separate NetDeck-e2e build): real setup()/loop() journeys
  with device-pipeline input injection (boot grace, 0x55 keyboard, GT911
  tap, trackball ISRs), transcript + pixel assertions (HUD, freeze tint)
- shim SerialSim: opt-in transcript ring for test assertions (off by
  default, interactive emulator unchanged)
- make netdeck-test / -unit / -e2e (root) and make test / test-unit /
  test-e2e (emulator/); tests/README.md documents the structure
- STATUS.md: test-structure note

Verified: make netdeck-test -> 14 unit + 7 integration + 3 E2E, 0 failures
This commit is contained in:
Dejvino
2026-11-14 13:02:41 +01:00
parent 383bffc85a
commit a1d0730124
13 changed files with 894 additions and 9 deletions
+62
View File
@@ -0,0 +1,62 @@
# NetDeck headless tests
Three layers, all running on the host (no device needed). The sketch is
compiled into each test binary as a **single translation unit** (the same
`#include APP_INO` trick `emulator/src/main.cpp` uses), which gives tests
direct access to the sketch's internal statics — no refactor required to
make the game testable.
## Layers
| Layer | Binary | Speed | What it drives | Assertions |
| --- | --- | --- | --- | --- |
| **Unit** | `NetDeck-tests` | ms | pure logic directly: `bfsPath`, `losClear`, `tryLink`, `severLink`, `stepSim` ticks | game state |
| **Integration** | `NetDeck-tests` | ms | subsystems through their entry points: `pollKeyboard` → `handleKey`, clicks → `registerClick`, multi-tick sim scenarios | state + serial transcript |
| **E2E** | `NetDeck-e2e` (separate build) | ~1–2 min | the real thing: `setup()` → `loop()` iterations, boot grace, inputs through the device pipeline (0x55 keyboard queue, GT911 touch state, trackball pin ISRs) | serial transcript + framebuffer pixels |
E2E is a separate build because it is real-time paced (the scenario runs at
20 Hz wall time) and needs SDL/TTF runtime for text rendering; everything
else is deterministic and instant.
## Running
```sh
make netdeck-test # everything: unit + integration + E2E (from repo root)
make netdeck-test-unit # fast layer only
make netdeck-test-e2e # E2E only
```
From `emulator/` directly: `make test APP=NetDeck`, `make test-e2e APP=NetDeck`.
Both binaries accept a name-prefix filter: `./NetDeck-tests unit`,
`./NetDeck-tests integration/daemon`, `./NetDeck-e2e e2e/network`.
## Adding tests
- **Unit**: append a `TEST(unit/your_case)` block to `tests/unit_tests.h`.
Call `freshScenario()` first (fixed RNG seed + clean state). Step time with
`stepTicks(n)` — 20 ticks = 1 s of sim, no wall time.
- **Integration**: append `TEST(integration/your_case)` to
`tests/integration_tests.h`. Drive input via `test::typeKey()` +
`pollKeyboard()`, `clickNode()` / `clickTile()`, then `stepTicks()`.
- **E2E**: append `TEST(e2e/your_journey)` to `tests/e2e_tests.cpp`. Start
with `reboot()`, schedule inputs with `schedule(t, 'key')` /
`scheduleTap(t, x, y)` (seconds after journey start), pump with
`pumpUntil(deadline, donePredicate)`, assert with `test::serialHas()` and
`test::pixelIs565()`.
## Conventions / gotchas
- `freshScenario()` resets the scenario AND the view mode (`resetScenario`
deliberately keeps the view); `reboot()` additionally rewinds the boot
phase, which plain `setup()` does not do.
- The serial transcript is a 512-line ring (`Serial.sink`); clear it with
`test::serialClear()` before the stretch you assert on, or assert right
after the event (combat logs can flood it).
- Sim RNG is seeded (`0xC0FFEE`) — combat hit/miss rolls are reproducible
per seed, but not across libcs. Prefer structural assertions (someone took
damage / link dropped) over exact hit counts.
- Keypress timing in E2E must clear the 1.4 s boot grace (schedule keys at
t ≥ 2.0 s).
- The firmware build itself is exercised by `make netdeck` — the Arduino
preprocessor catches things the emulator TU does not (e.g. prototype
injection vs custom-type parameters).