- stampImage16_P(): PROGMEM 16bpp stamp with color-key transparency (ND_TRANS16 pixels leave the destination untouched) — TFT_eSprite has no transparent pushImage variant, so it composites via drawPixel on both backends (sprite RAM on device, host framebuffer in the emulator) - shim: pgm_read_byte/word/dword macros (flash is memory-mapped on host and ESP32 alike) - pattern: 2px checker of black dots + transparent cells — half-visible dither, map/units stay readable underneath - E2E now proves the transparency itself: wall pixels survive under transparent cells, dots render black, key color never rendered
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
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 totests/unit_tests.h. CallfreshScenario()first (fixed RNG seed + clean state). Step time withstepTicks(n)— 20 ticks = 1 s of sim, no wall time. - Integration: append
TEST(integration/your_case)totests/integration_tests.h. Drive input viatest::typeKey()+pollKeyboard(),clickNode()/clickTile(), thenstepTicks(). - E2E: append
TEST(e2e/your_journey)totests/e2e_tests.cpp. Start withreboot(), schedule inputs withschedule(t, 'key')/scheduleTap(t, x, y)(seconds after journey start), pump withpumpUntil(deadline, donePredicate), assert withtest::serialHas()andtest::pixelIs565().
Conventions / gotchas
freshScenario()resets the scenario AND the view mode (resetScenariodeliberately keeps the view);reboot()additionally rewinds the boot phase, which plainsetup()does not do.- The serial transcript is a 512-line ring (
Serial.sink); clear it withtest::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).