agessaman
616fe96d1e
MeshRank slots previously took packets only. The broker tolerates status and
neighbors (and its maintainer intends to look at using the neighbors data), so
those now publish under meshrank/uplink/{token}/{device}/{type}, using the same
type suffixes as the MeshCore layout. Raw stays excluded: it is the
highest-volume topic and the broker does not consume it, so `set mqtt.raw on`
has no effect on a MeshRank slot.
All MeshRank gating funnels through the topic router, so relaxing that single
guard was sufficient - publishStatusToSlot, publishStatus, publishRaw,
publishNeighbors, and eligiblePacketSlots already skip slots that cannot form a
topic. A per-slot token is still required. Because eligiblePacketSlots resolves
topic support before serialising, raw JSON is never built for a MeshRank slot
rather than built and discarded.
observer-firmware sends raw to MeshRank; this supersedes that decision, so raw
must stay excluded when the branches merge. MeshRankTakesEveryTypeExceptRaw
fails if a merge re-enables it.
57 lines
4.8 KiB
Markdown
57 lines
4.8 KiB
Markdown
# Host unit tests
|
|
|
|
Fast, hardware-free unit tests for the fork's pure logic, run on the host with
|
|
GoogleTest via PlatformIO's `native` environment. They cover the extractable
|
|
observer/WebConfig logic (validation, preset table, topic templates, key
|
|
parsing) — the parts that don't depend on the ESP32, radio, or network stack.
|
|
Integration behavior (AsyncTCP transport, WiFi/MQTT, SoftAP) is exercised
|
|
separately; see "Local testing without hardware" in `MQTT_IMPLEMENTATION.md`.
|
|
|
|
## Running
|
|
|
|
```sh
|
|
pio test -e native # all suites
|
|
pio test -e native -f test_webconfig_keys # a single suite
|
|
```
|
|
|
|
A green `[PASSED]` per suite means GoogleTest returned 0 (all assertions
|
|
passed). PlatformIO's "0 test cases" line is just its Unity-style counter and
|
|
does not reflect the GoogleTest count — run the built binary directly
|
|
(`.pio/build/native/program`) to see the per-assertion breakdown.
|
|
|
|
## Suites
|
|
|
|
| Suite | Source under test | Covers |
|
|
|-------|-------------------|--------|
|
|
| `test_mqtt_presets` | `src/helpers/MQTTPresets.h` | preset lookup; table integrity (unique names, non-empty URLs, JWT-audience invariant, names fit the slot buffer); `mqttPresetNeedsSlotCredentials`; slot-count constants |
|
|
| `test_observer_validation` | `src/helpers/MQTTObserverValidation.h` | IATA (exactly 3 alphanumerics), owner key (64 hex), NTP hostname, and the buffer-fit check behind the #17 length validation — including boundaries and nulls |
|
|
| `test_webconfig_keys` | `src/helpers/WebConfigKeys.h` | POST-key allowlist, secret detection, admin-password classification/validation, slot-index bounds, and the short-key out-of-bounds guard (attacker-supplied keys) |
|
|
| `test_topic_template` | `src/helpers/MQTTTopicTemplate.h` | `{iata}/{device}/{token}/{type}` expansion, overflow/NUL-termination, and a buffer-size fuzz |
|
|
| `test_mqtt_topic_router` | `src/helpers/MQTTTopicRouter.h` | complete preset/custom topic-routing contract; MeshRank all types except raw; required identifiers; invalid inputs/slots; exact buffer boundaries |
|
|
| `test_mqtt_connection_policy` | `src/helpers/MQTTConnectionPolicy.h` | reconnect guard/backoff/stagger and breaker transitions; stable reset; JWT lifetime/renewal policy; exact timing boundaries and 32-bit `millis()` rollover |
|
|
| `test_mqtt_packet_queue_policy` | `src/helpers/MQTTPacketQueuePolicy.h` | queue-full eviction; stale-disconnect flush; adaptive drain limits; bounded QoS0 retries; exact timing boundaries and 32-bit `millis()` rollover |
|
|
| `test_mqtt_packet_filter` | `src/helpers/MQTTPacketFilter.h` | per-slot 0-15 allowlist parsing/formatting, numeric and named spellings; exact bounds; membership; candidate/eligible split and retry-completion policy; pre-queue union gate; default-mask detection |
|
|
| `test_mqtt_runtime_buffer_lifecycle` | `src/helpers/MQTTRuntimeBufferLifecycle.h` | idempotent allocation/release; partial-allocation degradation; retry of only missing buffers |
|
|
| `test_mqtt_prefs_codec` | `src/helpers/MQTTPrefsStorage.h`, `src/helpers/MQTTPrefsCodec.h` | binary pre-slot/3-slot/6-slot migration fixtures; v1 header integrity; downgrade preservation; shortest-payload write policy (default filters stay downgrade-readable) |
|
|
| `test_mqtt_prefs_atomic_store` | `src/helpers/MQTTPrefsAtomicStore.h` | transactional MQTT writes and legacy `/node_prefs` handoff; exact short-write detection; begin/finish/rename failure cleanup; original-file preservation |
|
|
| `test_mqtt_payload_builder` | `src/helpers/MQTTPayloadBuilder.cpp` | status/packet/raw JSON contracts; optional fields; escaping; RX metrics and path; score handling; exact buffer bounds; maximum representative payloads |
|
|
| `test_utils` | `src/Utils.cpp` | `Utils::toHex` (upstream) |
|
|
|
|
## Conventions (and how to add a suite)
|
|
|
|
- Each `test/test_<name>/` directory builds into its **own** GoogleTest program
|
|
and must define its own `main()` (`::testing::InitGoogleTest` + `RUN_ALL_TESTS`).
|
|
- Tests are **host-only**: include only pure headers. Arduino/crypto stubs live
|
|
in `test/mocks/` (on the include path via `-I test/mocks`).
|
|
- Firmware headers are included from `src` (via `-I src`, e.g.
|
|
`#include "helpers/MQTTPresets.h"`). Some are guarded or ESP-flavored, so a
|
|
suite may need shims **before** the include — e.g. `test_mqtt_presets` does
|
|
`#define WITH_MQTT_BRIDGE 1` (the preset table is behind that flag) and
|
|
`#define PROGMEM` (the embedded CA-cert strings are PROGMEM-qualified).
|
|
- To add a suite: create `test/test_<name>/test_<name>.cpp` with a `main()`, and
|
|
add any host-only source it links to the `native` env's `build_src_filter` in
|
|
`platformio.ini` (header-only code needs no source entry). No other wiring.
|
|
- Keep logic testable by extracting pure functions into headers (as
|
|
`MQTTObserverValidation.h` / `WebConfigKeys.h` / `MQTTTopicTemplate.h` do) and
|
|
having the firmware call the same functions.
|