Files
jimmyandClaude Opus 5.5 b2cd242390 docs: describe the v2 controller's API, UI and tests
API.md now documents what the firmware serves: groups, combined
brightness, beat-driven sequences, import/export, /api/audio, patterns
over ESP-NOW, outputs, /ws, driver OTA, and how API calls become driver
messages and group commands. The user guide follows the current UI; the
in-app audio help describes the microphone instead of input devices.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 20:42:03 +13:00

25 lines
1.8 KiB
Markdown

# API tests
HTTP tests against a running controller, ported from the Python app's endpoint tests (`tests/test_endpoints_pytest.py` and `tests/test_endpoints.py`) on both the `animation-engine` and `main` lines, plus `main`'s bundle, audio, group and sequence tests where they work over HTTP. They need `pytest`, `requests` and `websocket-client`.
```bash
make test-api HOST=10.1.1.180
```
or `python3 -m pytest test/api --host <ip>` (or set `LED_HOST`). Without a host every test is skipped.
The tests create and delete profiles, presets, zones and so on. The sequence tests switch mic timing off and run the beat clock at 200 BPM for a few seconds; mic timing is switched back on afterwards. Before the run they save every collection (`GET /db/<name>`), and afterwards they write each one back (`PUT /db/<name>`). Zone play and preset send do go out over ESP-NOW. They use made-up driver names (`pytest-a`, `pytest-nobody`) so real drivers ignore them.
## Marking a missing feature
`helpers.missing("<feature>")` marks a test for behaviour the firmware does not have yet. It is a strict `xfail`: the test shows as `x`, and fails as `XPASS(strict)` once the feature works, so the marker gets removed. No test carries it now. `python3 -m pytest test/api --host <ip> -rx` lists marked tests.
## Not ported
- the model, engine and helper unit tests (`tests/models/`, `tests/engine_tests/`, most of `main`'s `tests/test_*.py`), which test Python modules that have no C counterpart;
- the Wi-Fi/TCP/UDP driver test servers and the bridge tests (the controller has no bridge or Wi-Fi driver transport).
The checks on exact driver messages became checks on status codes and replies, because ESP-NOW frames can't be captured from outside the board.
The Selenium UI tests are in `test/browser/` (`make test-browser HOST=<ip>`).