The legacy I2S driver buffers i2s_write() data in a TX DMA ring (8x64 samples = 64 ms @ 8 kHz) and hands a buffer back to i2s_write() only after the DMA finished playing it. After the last queued event the sound task called i2s_zero_dma_buffer(), which memsets the whole ring instantly — erasing everything not yet played. Any sound <= 64 ms was written into free ring space without ever blocking, so the zeroing wiped it before the DMA reached a single sample: completely silent on hardware. Longer tones force i2s_write() to block on a full ring, pacing rendering to real-time playback — hence only long beeps were audible, and the fade-envelope cap never moved the threshold. Every game beep <= 80 ms (link-active 10, laser 30, sever 40, bleep/ICE 50, feedback 80) sat in the dead zone. The emulator never showed it: its i2s_write shim fed SDL directly and had no ring at all. Fix: replace the instant zeroing with a paced silence purge — once the queue drains, write one ring + one chunk of zero samples through i2s_write(), reusing each DMA buffer only after the DMA played it. The sound plays out fully and the ring then loops silence (still kills the tail-replay bug the zeroing existed for). Keep the envelope cap at total/4 so short tones keep a steady-state portion. Emulator shim gains a TX DMA ring model (write/play cursors + bounded DAC-emitted log) so the bug class reproduces headlessly: unit/ sound_short_tone_reaches_dac fails on the zero_dma code, passes on the purge (A/B verified); shim_zero_dma_erases_unplayed pins model fidelity; sound_long_tone_plays_out_fully guards against truncation. SoundEngine gains a pumpOne() test seam and begin(spawnTask) for deterministic driving. Full suite: 26 unit + 7 integration + 4 E2E, 0 failures.
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).