Files
lilygo-t-deck/emulator/tests
Dejvino 1dcc87d8d4 Fix trackball click: I2S MCLK was claiming GPIO0; emulator pin-ownership parity
Root cause (on device): sound_engine zero-initialized i2s_pin_config_t,
leaving mck_io_num == 0. i2s_set_pin() then claimed GPIO0 — an
MCLK-capable pin on the S3 and the trackball centre / BOOT line — as
its MCLK output. Verified on device with a diagnostic build: pin0 read
LOW at idle, exactly one latched FALLING edge, clicks never registered.

- sound_engine: set pins.mck_io_num = I2S_PIN_NO_CHANGE explicitly.
- NetDeck: register the trackball click on release with contact-bounce
  collapse (the proven CrtTerminal pattern); pollTouch re-arms when
  isPressed() stays true but getPoint() reports no points (stuck GT911
  IRQ on some units).
- Emulator parity (so this class of bug dies before flashing):
  GPIO-matrix pin-ownership model in the shim — i2s_set_pin() claims
  its pins, claimed pins are dead inputs (digitalRead LOW, no edges,
  loud WARNING on claim/ISR collisions); host pin writes go through
  emu::setPin/togglePin with an edge-accurate ISR latch (a full
  press+release pulse between dispatches no longer gets swallowed);
  E2E inits SDL_INIT_AUDIO so the I2S path actually runs there.
  Regression coverage: e2e/trackball_click (fails on the old engine),
  unit/shim_claimed_pin_is_dead_input,
  unit/shim_edge_survives_same_dispatch_pulse.
- Makefile: firmware step follows the sketch move (root platformio.ini,
  src_dir = src/netdeck).
- HW.md: new notes file for emulator-vs-hardware quirks and the
  on-device debugging recipe.

On-device verified: clicks register in both views (beacon drops, node
routing). Fast layer 23 unit + 7 integration green. Note: e2e
boot_and_controls + network_journey failures are pre-existing at HEAD
(reproduced on a clean stash before this change).
2026-11-15 10:24:30 +01:00
..

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 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).