- 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
63 lines
3.2 KiB
Markdown
63 lines
3.2 KiB
Markdown
# 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).
|