Dev testing + emulation harness #3

Merged

laurence merged 1 commit from feature/dev-testing into main 2026-07-03 12:16:45 +01:00

Conversation 0 Commits 1 Files changed 14 +445 -56

laurence commented 2026-07-03 12:16:44 +01:00

Owner

Copy link

Feature

Emulation + linting harness so every part of OpenScribe can be checked without the physical device.

What was achieved

• Pure firmware logic (wav.h, httprange.h) extracted and unit-tested on the host (pio test -e native).
• Wokwi emulator harness (diagram.json, wokwi.toml, esp32s3_wokwi build) for boot + WiFi + REST API.
• Firmware now brings the API up even if audio/SD init fails, so it stays reachable in the emulator and reports faults.
• CI extended: native tests + cppcheck, OpenAPI validation, Wokwi build (+ full run when a token is set).
• docs/testing.md: the full emulate/lint guide (firmware, server, API, app, case).

How to verify

• cd firmware && pio test -e native runs the WAV-header + Range unit tests.
• pio run -e esp32s3_wokwi builds the emulator firmware; open firmware/ in the Wokwi VS Code extension to run it.
• OpenAPI validates locally (already confirmed: 12 paths, 10 schemas).

Tools used

PlatformIO (native + Wokwi envs), Unity, cppcheck, Wokwi, openapi-spec-validator.

Follow ups

• Optionally set a WOKWI_CLI_TOKEN CI secret to run the emulator end-to-end in CI.
• M3 next: charge/VBUS detection + independent upload.

## Feature Emulation + linting harness so every part of OpenScribe can be checked without the physical device. ## What was achieved - Pure firmware logic (`wav.h`, `httprange.h`) extracted and unit-tested on the host (`pio test -e native`). - Wokwi emulator harness (`diagram.json`, `wokwi.toml`, `esp32s3_wokwi` build) for boot + WiFi + REST API. - Firmware now brings the API up even if audio/SD init fails, so it stays reachable in the emulator and reports faults. - CI extended: native tests + cppcheck, OpenAPI validation, Wokwi build (+ full run when a token is set). - `docs/testing.md`: the full emulate/lint guide (firmware, server, API, app, case). ## How to verify - `cd firmware && pio test -e native` runs the WAV-header + Range unit tests. - `pio run -e esp32s3_wokwi` builds the emulator firmware; open `firmware/` in the Wokwi VS Code extension to run it. - OpenAPI validates locally (already confirmed: 12 paths, 10 schemas). ## Tools used PlatformIO (native + Wokwi envs), Unity, cppcheck, Wokwi, openapi-spec-validator. ## Follow ups - Optionally set a `WOKWI_CLI_TOKEN` CI secret to run the emulator end-to-end in CI. - M3 next: charge/VBUS detection + independent upload.

laurence added 1 commit 2026-07-03 12:16:45 +01:00

test(dev): emulation + linting harness (Wokwi, native tests, CI, docs) ... f84bbca80b

Answers "how do we emulate/lint this?" with runnable tooling for every part, and
factors the pure firmware logic out so it is unit-testable on the host.

What changed:
- firmware/src/wav.h, firmware/src/httprange.h: pure, header-only WAV header builder
  and HTTP Range parser (no Arduino deps), so the tricky byte-layout and range logic
  can be tested on a PC. storage.cpp and api_http.cpp refactored to use them.
- firmware/test/test_pure/: Unity tests for the WAV header fields and Range parsing
  (start-end, open-ended, clamped, unsatisfiable, non-bytes). Run: pio test -e native.
- firmware/platformio.ini: add [env:native] (host tests) and [env:esp32s3_wokwi]
  (emulator build with default WiFi = Wokwi-GUEST so the API comes up in the sim).
- firmware/wokwi.toml + firmware/diagram.json: Wokwi emulator harness (ESP32-S3 +
  microSD + button + LED). Note: Wokwi has no I2S mic part, so audio isn't emulated;
  the harness targets boot + WiFi + REST API.
- firmware/src/main.cpp + config.cpp: bring up WiFi + API even if audio/SD init fails
  (device stays reachable, reports the fault via GET /device); compile-time default
  WiFi honoured when NVS is empty (used by the Wokwi build).
- .forgejo/workflows/ci.yml: add native tests + cppcheck to the firmware job; new
  openapi job (openapi-spec-validator) and emulator job (Wokwi build, plus a full run
  when WOKWI_CLI_TOKEN is set).
- docs/testing.md: the full emulate/lint guide for firmware, server, API, app, case.
- state/: NOTES points at the guide; TODO reflects this branch.

Why:
- The firmware can't be flashed yet (no parts) and doesn't build on this dev host, so
  we need host-runnable checks. Pure-logic unit tests + OpenAPI validation run anywhere;
  Wokwi emulates boot/WiFi/API; CI compiles the real firmware. Verified locally: the
  OpenAPI spec validates (12 paths, 10 schemas).

Notes:
- Native tests and cppcheck run in CI (no compiler on the dev host). The Wokwi full run
  is skipped unless a WOKWI_CLI_TOKEN secret is present; the build is still verified.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

laurence merged commit dc9585a087 into main 2026-07-03 12:16:45 +01:00

laurence deleted branch feature/dev-testing 2026-07-03 12:16:45 +01:00

laurence referenced this pull request from a commit 2026-07-03 12:16:46 +01:00

Merge pull request 'Dev testing + emulation harness' (#3) from feature/dev-testing into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: laurence/openscribe#3

No description provided.