docs(agents): require end-to-end tests on the headless backend
- commit
- 1e7b844d816991f5482aa0864fa80c44423797ea
- author
- brice · · 2026-10-14 20:48 UTC
- parent
- 3470598
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
1 file · +11 -0
M AGENTS.md +11 -0
| @@ -24,6 +24,17 @@ Test doubles are always generated by Mockery v3 (`testify` template). Never hand | |||
| 24 | 24 | - production constructor parameters such as `NewRenderer func(w, h) (ports.Renderer, error)`, where tests return a generated mock; | |
| 25 | 25 | - channels passed to `app.run` to inject input or observe scenes (channel ports). | |
| 26 | 26 | ||
| 27 | + | ## End-to-end tests (headless backend) | |
| 28 | + | ||
| 29 | + | Unit tests are not enough for user-facing behavior (binds, gestures, window placement, config keys). Test it end to end on the headless backend before declaring it done; see [docs/headless.md](docs/headless.md). | |
| 30 | + | ||
| 31 | + | - Build the branch binary (`CGO_ENABLED=0 go build -o <tmp>/neferwl ./cmd/neferwl`) and run it with a throwaway config: `<tmp>/neferwl --backend=headless --config <tmp>/config --no-xwayland --screenshot <tmp>/shots --input <script> --timeout 10s`. | |
| 32 | + | - Input scripts drive keys and gestures (`key Super+s`, `swipe4 down`, `sleep 1s`); see the table in docs/headless.md. | |
| 33 | + | - Logs go to `$XDG_STATE_HOME/neferwl/runs/headless/latest.log`, not stderr. Read the headless `WAYLAND_DISPLAY` from its `listening` entry. | |
| 34 | + | - Isolate from the user's live session: run the headless compositor, its clients and `neferwl state` with `env -u NEFERWL_STATE -u NEFERWL_SLOT WAYLAND_DISPLAY=<headless>`. `NEFERWL_STATE` wins over `WAYLAND_DISPLAY` and would read the live session's state. | |
| 35 | + | - Check results with `WAYLAND_DISPLAY=<headless> neferwl state` (windows, stash index/count, visibility) and the `latest.png` screenshot. | |
| 36 | + | ||
| 27 | 37 | ## Checks before merge | |
| 28 | 38 | ||
| 29 | 39 | `make check`, `make race`, `make mocks-check` and `staticcheck ./...` must pass. | |
| 40 | + | User-facing changes are also tested end to end on the headless backend. | |
| @@ -24,6 +24,17 @@ Test doubles are always generated by Mockery v3 (`testify` template). Never hand | |||||
| 24 | - production constructor parameters such as `NewRenderer func(w, h) (ports.Renderer, error)`, where tests return a generated mock; | 24 | - production constructor parameters such as `NewRenderer func(w, h) (ports.Renderer, error)`, where tests return a generated mock; | ||
| 25 | - channels passed to `app.run` to inject input or observe scenes (channel ports). | 25 | - channels passed to `app.run` to inject input or observe scenes (channel ports). | ||
| 26 | 26 | ||||
| 27 | + | ## End-to-end tests (headless backend) | |||
| 28 | + | ||||
| 29 | + | Unit tests are not enough for user-facing behavior (binds, gestures, window placement, config keys). Test it end to end on the headless backend before declaring it done; see [docs/headless.md](docs/headless.md). | |||
| 30 | + | ||||
| 31 | + | - Build the branch binary (`CGO_ENABLED=0 go build -o <tmp>/neferwl ./cmd/neferwl`) and run it with a throwaway config: `<tmp>/neferwl --backend=headless --config <tmp>/config --no-xwayland --screenshot <tmp>/shots --input <script> --timeout 10s`. | |||
| 32 | + | - Input scripts drive keys and gestures (`key Super+s`, `swipe4 down`, `sleep 1s`); see the table in docs/headless.md. | |||
| 33 | + | - Logs go to `$XDG_STATE_HOME/neferwl/runs/headless/latest.log`, not stderr. Read the headless `WAYLAND_DISPLAY` from its `listening` entry. | |||
| 34 | + | - Isolate from the user's live session: run the headless compositor, its clients and `neferwl state` with `env -u NEFERWL_STATE -u NEFERWL_SLOT WAYLAND_DISPLAY=<headless>`. `NEFERWL_STATE` wins over `WAYLAND_DISPLAY` and would read the live session's state. | |||
| 35 | + | - Check results with `WAYLAND_DISPLAY=<headless> neferwl state` (windows, stash index/count, visibility) and the `latest.png` screenshot. | |||
| 36 | + | ||||
| 27 | ## Checks before merge | 37 | ## Checks before merge | ||
| 28 | 38 | ||||
| 29 | `make check`, `make race`, `make mocks-check` and `staticcheck ./...` must pass. | 39 | `make check`, `make race`, `make mocks-check` and `staticcheck ./...` must pass. | ||
| 40 | + | User-facing changes are also tested end to end on the headless backend. | |||