maze32/docs/INTEGRATION_TESTING.md

On-device integration testing

This procedure verifies Milestone 010 on the ESP32-C6FH4 without PSRAM or any assumed GPIO. Run it against production firmware and the production LittleFS image. Start from a freshly booted device with no occupied lobby sessions.

Build and delivery

/home/sasa/.platformio/penv/bin/pio run -e esp32-c6-devkitm-1
/home/sasa/.platformio/penv/bin/pio run -e esp32-c6-devkitm-1 --target buildfs
/home/sasa/.platformio/penv/bin/pio run -e esp32-c6-devkitm-1 --target upload --upload-port /dev/ttyACM0
/home/sasa/.platformio/penv/bin/pio run -e esp32-c6-devkitm-1 --target uploadfs --upload-port /dev/ttyACM0

Monitor the USB serial log at 115200 baud. Confirm application version 0.10.0, the 4 MB partition table, successful LittleFS mount, station or fallback network startup, registration of all HTTP/WebSocket routes, and health state serving.

Resource and load scenario

Keep the development host connected to Mazda7; do not switch it to the device fallback access point. When the board has station address 192.168.1.50, run:

python3 scripts/ws_protocol_client.py 192.168.1.50 \
  --verify-m010 --stress-moves 80 --repeat-matches 2

The scenario intentionally takes more than two minutes because both repeated matches use the real 60-second reconnect deadline. It performs these checks:

1. Connect two players and four observers and assemble all four complete 8,192-cell observer projections.
2. Verify heartbeat round-trip latency for all six sessions.
3. Stop consuming one observer stream while Player 1 performs accepted moves; intermediate observer updates may be dropped, but player acknowledgements must remain within the reported 250 ms budget.
4. Flood a second observer with malformed messages. The fixed rate limiter closes sustained abuse, and the players remain responsive.
5. Complete and authoritatively reset two matches through the real disconnect timeout. Each reset generates a new server-owned maze while preserving the connected sessions.
6. Fetch /diagnostics before, during, and after the run. Assert the connection and queue high-water marks remain within six and twelve, internal free heap stays above 32 KiB, the largest internal block stays above 16 KiB, and the post-reset free-heap samples remain within a 32 KiB range.

Capture the command output, the final diagnostics JSON, and serial lines that begin with M010 resources:. The JSON counters are monotonic since boot and include connections, queue use, dropped messages, failures, malformed/rate- limited input, commands, match cycles, maximum handler/send time, and current and minimum internal heap samples.

Station, fallback, and browser recovery

These checks involve network state and must be performed from a separate phone or computer so the development host retains its Mazda7 internet connection.

1. Reboot with the saved Mazda7 configuration and confirm /api/wifi/status reports station_connected. Reload both player pages during an active match and verify their tokens restore the same slots and authoritative state.
2. From the separate client, exercise the established provisioning procedure with an intentionally unavailable test network. Confirm the bounded station attempts return the device to maze32-XXXX at http://192.168.4.1/provision and that the Russian page remains usable.
3. Restore Mazda7 through the provisioning page without recording its password. Reboot and confirm station connection, browser recovery, /health, and /diagnostics again.

Do not record an acceptance result unless the physical logs and samples are available. Do not use an LED, a board pin, or a PSRAM capability as a test oracle.