Files
lilygo-t-deck/emulator/tests/README.md
T
Dejvino a1d0730124 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
2026-11-14 13:02:41 +01:00

63 lines
3.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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).