Hardware TDD
Build the test ladder before claiming a feature is complete. Pure behavior can
often be tested off-target; voltage, pin mux, timing under load, and physical
assembly still require target evidence.
Intake
Record exact board/revision, framework/toolchain, hardware invariants, safety
inhibits, simulator model, available instruments, test fixtures, and the proof
stage required by the user.
Process
- Turn requirements into observable behavior and safety invariants.
- Write host tests for pure C/C++ logic using fakes for time, serial, sensors,
and actuators. Keep hardware adapters thin.
- Use Wokwi or another simulator only for peripherals and timing that its model
actually represents; record model limitations.
- Run an exact-board compile and static checks with the selected toolchain.
- Create a one-change target checklist: power-off continuity, controlled
power-up, input observation, output inhibit, reset/recovery, and logs.
- Ask a physical gate for measurements, photos, or serial output. Do not infer
target success from a host test or compile log.
- Record failures as evidence and keep the next test bounded.
Test matrix
| Layer |
Example |
Proves |
Does not prove |
| Host |
debounce/state/packet parser |
deterministic logic |
pin voltage or wiring |
| Simulation |
modeled sensor/LED/UART |
modeled interactions |
regulator, clone, EMI, thermal behavior |
| Build |
exact FQBN/environment |
source and dependency compile |
upload or behavior |
| Target |
serial, meter, scope, photo |
observed hardware behavior |
field reliability unless loaded |
| System |
integrated load/failure case |
requirement under scenario |
future deployment safety |
Anti-rationalization
| Shortcut |
Response |
| "The unit test passed." |
Keep all physical and system stages open. |
| "Wokwi matches the board." |
List what the model omits and verify those items on hardware. |
| "The sketch compiled." |
Require upload identity and target observations separately. |
| "The photo proves it works." |
Require board identity, measurement context, and observed result. |
| "Mark it done and test later." |
Keep the loop item blocked or needs-review until evidence exists. |
Verification
- Every requirement maps to a test, proof stage, and artifact path.
- Host/simulation/build/target/system results are labeled separately.
- Physical-only steps emit the concrete
Physical gate format from
embedded-project-loop.
- Failed and unverified cases remain visible in the report.
Shared output contract
Use the shared Arduino skill contract:
state assumptions, required tools and versions, implementation steps,
tests/evidence by proof stage, known limitations, and recovery/security notes.
1---
2name: hardware-tdd
3description: Use when planning tests for Arduino, ESP32, ESP32-S3, Pico, or Pico W firmware; deciding what can run off-target; using Wokwi or simulation; writing host fakes; or accepting a physical hardware feature without confusing compile proof with system proof.
4metadata:
5 triggers: "hardware test, embedded TDD, Wokwi, simulation, host test, acceptance test, hardware regression"
6 attribution: "Adapted from Agent Skills eval integrity guidance and the shared Arduino evidence-stage contract."
7---
8
9# Hardware TDD
10
11Build the test ladder before claiming a feature is complete. Pure behavior can
12often be tested off-target; voltage, pin mux, timing under load, and physical
13assembly still require target evidence.
14
15## Intake
16
17Record exact board/revision, framework/toolchain, hardware invariants, safety
18inhibits, simulator model, available instruments, test fixtures, and the proof
19stage required by the user.
20
21## Process
22
231. Turn requirements into observable behavior and safety invariants.
242. Write host tests for pure C/C++ logic using fakes for time, serial, sensors,
25 and actuators. Keep hardware adapters thin.
263. Use Wokwi or another simulator only for peripherals and timing that its model
27 actually represents; record model limitations.
284. Run an exact-board compile and static checks with the selected toolchain.
295. Create a one-change target checklist: power-off continuity, controlled
30 power-up, input observation, output inhibit, reset/recovery, and logs.
316. Ask a physical gate for measurements, photos, or serial output. Do not infer
32 target success from a host test or compile log.
337. Record failures as evidence and keep the next test bounded.
34
35## Test matrix
36
37| Layer | Example | Proves | Does not prove |
38|---|---|---|---|
39| Host | debounce/state/packet parser | deterministic logic | pin voltage or wiring |
40| Simulation | modeled sensor/LED/UART | modeled interactions | regulator, clone, EMI, thermal behavior |
41| Build | exact FQBN/environment | source and dependency compile | upload or behavior |
42| Target | serial, meter, scope, photo | observed hardware behavior | field reliability unless loaded |
43| System | integrated load/failure case | requirement under scenario | future deployment safety |
44
45## Anti-rationalization
46
47| Shortcut | Response |
48|---|---|
49| "The unit test passed." | Keep all physical and system stages open. |
50| "Wokwi matches the board." | List what the model omits and verify those items on hardware. |
51| "The sketch compiled." | Require upload identity and target observations separately. |
52| "The photo proves it works." | Require board identity, measurement context, and observed result. |
53| "Mark it done and test later." | Keep the loop item blocked or `needs-review` until evidence exists. |
54
55## Verification
56
57- Every requirement maps to a test, proof stage, and artifact path.
58- Host/simulation/build/target/system results are labeled separately.
59- Physical-only steps emit the concrete `Physical gate` format from
60 `embedded-project-loop`.
61- Failed and unverified cases remain visible in the report.
62
63## Shared output contract
64
65Use [the shared Arduino skill contract](../../docs/arduino-skill-contract.md):
66state assumptions, required tools and versions, implementation steps,
67tests/evidence by proof stage, known limitations, and recovery/security notes.
wedsamuel1230