web/e2e/README.md

Real-device E2E messaging suite

Playwright tests that drive the real web app in Chromium against a real Meshtastic device over the HTTP(S) phone API and verify text messaging in both directions across a two-node mesh.

By default the "devices" are two simulated meshtasticd firmware nodes running in Docker, meshed over the firmware's built-in UDP multicast LAN transport (224.0.0.69:4403) — real firmware, real encryption, distinct node numbers, and no MQTT/relay. The same tests can run against physical hardware.

   Playwright (headless Chromium)                 Python peer (meshtastic lib)
   ── HTTPS phone API :9443 ────┐                 ┌──── TCP phone API :4403 ────
                                ▼                 ▼
                    ┌─────────────────┐  UDP multicast  ┌─────────────────┐
                    │  Node A (DUT)   │  224.0.0.69     │   Node B (peer) │
                    │ meshtasticd sim │◀─── mesh ──────▶│ meshtasticd sim │
                    └─────────────────┘                 └─────────────────┘

• Node A is the device-under-test the browser connects to (HTTPS).
• Node B is driven/observed by the Python peer (e2e/peer/peer.py) over TCP.

Layout

Path	What
playwright.config.ts	Config (root): chromium, serial, dev server on :3100, global setup/teardown
e2e/global-setup.ts / global-teardown.ts	Bring the mesh up / wait for readiness / tear down
e2e/device/docker-compose.yml + nodeA.yaml / nodeB.yaml	The two meshtasticd sim nodes
e2e/peer/peer.py + requirements.txt	The off-browser mesh peer (TCP meshtastic lib)
e2e/fixtures/	peer.ts (peer wrapper) + test.ts (page-object + device fixtures)
e2e/pages/	ConnectionPage.ts, MessagesPage.ts
e2e/tests/	connect, messaging.broadcast, messaging.direct

Running locally (Docker sim — default)

Prerequisites: Docker, Node + pnpm (11.5.2), Python 3.11+.

pnpm install
pnpm exec playwright install chromium
python -m venv e2e/peer/.venv && e2e/peer/.venv/bin/pip install -r e2e/peer/requirements.txt

pnpm test:e2e            # brings up the mesh, runs the suite
pnpm test:e2e:report     # open the HTML report

Global setup runs docker compose up -d (idempotent) and waits for the device. The mesh is left running between runs for speed; set E2E_DOCKER_DOWN=1 to tear it down on exit. CI leaves the containers up through the run (so the workflow can dump device logs on failure) and tears them down in a final step.

Environment variables

Var	Default	Purpose
E2E_DEVICE_MODE	docker	docker (sim) or hardware (skip compose)
E2E_NODE_A_URL	https://127.0.0.1:9443	Device-under-test the browser connects to
E2E_PEER_HOST / E2E_PEER_PORT	127.0.0.1 / 14404	TCP phone API the Python peer drives
E2E_WEB_PORT	3100	Dev-server port for the app under test
E2E_PEER_PYTHON	e2e/peer/.venv/bin/python	Python used to run the peer
E2E_DOCKER_DOWN	unset	1 to compose down on teardown (CI tears down in a final workflow step)

Running against real hardware

Point the suite at two physical devices on the same channel/region. Node A must expose the HTTP(S) phone API (Wi-Fi); the peer reaches Node B over TCP (Wi-Fi) — both on the same LoRa mesh, so the radio is the bridge (no MQTT):

E2E_DEVICE_MODE=hardware \
E2E_NODE_A_URL=https://<deviceA-ip> \
E2E_PEER_HOST=<deviceB-ip> E2E_PEER_PORT=4403 \
pnpm test:e2e

What the tests cover

• connect — add an HTTP(S) connection in the UI, complete the config handshake, land on the messages view.
• messaging.broadcast — mesh → web (peer broadcasts, the browser renders it) and web → mesh (the browser sends, the peer node confirms receipt over the real mesh).
• messaging.direct — fixme (see Known limitations).

Gotchas baked in (firmware/sim specifics)

• Image tag: use meshtastic/meshtasticd:daily-debian. :latest is 2.7.15 and predates the EnableUDP multicast feature (no mesh between sim nodes).
• Do not pass --sim: force_simradio takes an early branch in portduinoSetup() that skips config-file loading — Webserver / EnableUDP / MACAddress would all be ignored. Select the sim radio via Lora: Module: sim in the config instead.
• Distinct MACAddress per node → distinct node numbers (else the UDP handler drops the peer's packets as "spoofed local origin").
• Webserver is HTTPS-only (self-signed cert on 9443) — Playwright uses ignoreHTTPSErrors + --ignore-certificate-errors; the dialog's HTTPS toggle is on. The app is served over plain HTTP to avoid mixed-content.
• Send readiness: the composer renders before the SDK chat client is ready (the SQLite/OPFS sqlocal store times out in headless Chromium and falls back to in-memory). MessagesPage.waitReady() gates on the "Connected" status so an immediate send isn't silently dropped.

Known limitations

• Direct messages (messaging.direct) are fixme — a SimRadio limitation, not a web-app issue. DMs go out PKI-encrypted. PKI keygen is gated on a set LoRa region (NodeDB.cpp:3051; the sim boots region-UNSET) — setting lora.region via admin does make the nodes generate and exchange keys (verified: both learn each other's public key). But a PKI DM still can't traverse the SimRadio: the PKC overhead exceeds its payload limit (Payload size larger than compressed message allows! Send empty payload), so the packet is truncated and the receiver NAKs NO_CHANNEL (No suitable channel found for decoding, hash 0x0). The firmware skips PKC under --sim (Router.cpp:730) for exactly this reason, but --sim also disables the config-file loading (Webserver/EnableUDP/MAC) the web app needs, so the two are mutually exclusive. The app behaves correctly (key-refresh dialog). Broadcast covers bidirectional messaging; re-enable against real hardware, where real LoRa carries PKC fine.

App bugs surfaced by this suite (fixed on this branch)

1. Connect-on-save race (apps/web/src/pages/Connections/useConnections.ts): connect() read the just-added connection from a stale memoized closure, so "Save" never actually connected ("unknown connection id"). Fixed to read from the live store.
2. ReferenceError: nodeDB is not defined (apps/web/src/core/subscriptions.ts): the device-metrics telemetry handler called a node store the #1050 migration removed, throwing on every telemetry packet. Fixed by folding device metrics into the node inside the SDK NodesClient (onTelemetryPacket) and dropping the dead app-side handler.