just ui-test runs Quickshell inside niri inside headless Weston, never niri-session or the parent compositor.
Agent contracts live in RULES; this is a human overview.
What it provides
Weston headless backend with the Pixman renderer; 1280 × 720 virtual output by default, WIDTHxHEIGHT overrides it.
A disposable source overlay, private runtime directory, private session bus, and bwrap sandbox denying host HOME, system bus, network, and runtime sockets.
Synthetic service doubles, real pointer and keyboard through the child sockets, screenshots from the child compositor, and retained logs for every phase.
A 300-second deadline per suite sandbox, 30-second command/readiness budgets, and child shutdown escalating from SIGTERM to SIGKILL after two seconds.
Never launch lifecycle.qml or niri-integration.qml directly: the runner's isolated service substitutions are mandatory.
Requirements
just deps holds the host package list; every just recipe checks it first and names anything missing.
Suites
just ui-test [fixture] [WIDTHxHEIGHT]; default all.
all runs shell, controls, popups, privilege, bar, every feature suite, and niri, at most two concurrent sandboxes, and prints one line per suite with its evidence directory; a failed suite leads with its failing check.
Bounded admission prevents software-rendered compositors from starving startup I/O.
Interruption cleans active sandboxes and reports queued suites as not run.
Rerun a single suite by name while iterating.
shell: production composition against private service stand-ins, opening every popup and overlay.
controls: shared PopupButton, PopupSlider, PopupTextField with real input.
popups — clock and registry system popups with isolated service doubles: switching, polling gate, Escape, outside and Bar dismissal, transition diagnostics.
bar: chip presentation, end-slot placement, clipboard/launcher switching, every popup in vertical layout, native dark/light/dark theme switching across shell, terminal, editor and mail client.
Every features/<name>/fixtures/suite.mjs runs as just ui-test <name> on bar.qml, followed by its optional production.mjs proof.
qt-focus, qt-focus-editor — plain-Qt focus diagnostics; not part of all.
niri — native integration: real Niri subscription, Bar pills, the focused application reaching the vault at each opening, overview, hotplug, xdg-shell clients, clipboard paste focus return.
Each selection starts from checked-in synthetic state and runs that suite's assertions, not a recorded input stream.
Evidence
Everything lands in a fresh $TMPDIR/nuguland-ui-test-* directory (default /tmp, cleared on reboot).
Each run first prunes older runs, keeping the newest 3 per fixture and anything written in the last 15 minutes.
The evidence directory contains:
failure.json — original error, phase, latest safe snapshot, capture errors.
replay.json — selected fixture, exact public rerun command, current phase.
failure.png — child-compositor screenshot when capture was possible.
diagnostics.jsonl with the fixture-specific log (bar.log, lifecycle.log, niri-integration.log, etc.): snapshot IDs and popup transitions.
commands.log, fixture and compositor logs, versions.txt, outputs.json.
Suite-specific records: assertions.jsonl, resource-dispatch.jsonl, resource-probe-checks.json, niri-*.json, and the *-*.png screenshots.
Screenshots contain only sandbox fixture data. Revealed nonempty authentication input refuses capture and records the refusal; a missing screenshot is explicit, never a pass.
Approved diagnostic exceptions
At most one expected niri::backend::winit DEBUG software-EGL record, bound to niri.log.
Qt fixture logs additionally tolerate the observed Qt 6.12.0 text-input focus warnings (QTBUG-146211) until the installed Qt changes.
Exact allowed shapes, counts, scope and removal conditions live in RULES.
Tooling
Follow the official Quickshell language-server setup: create .qmlls.ini and let Quickshell generate it.
Use Qt6 executables, particularly /usr/lib/qt6/bin/qmllint on this host.
Do not patch static metadata to pretend it models runtime-only backend registration.
# Nested UI test harness
`just ui-test` runs Quickshell inside niri inside headless Weston, never `niri-session` or the parent compositor.
Agent contracts live in [RULES](../../.system/RULES.md); this is a human overview.
## What it provides
- Weston headless backend with the Pixman renderer; 1280 × 720 virtual output by default, `WIDTHxHEIGHT` overrides it.
- A disposable source overlay, private runtime directory, private session bus, and bwrap sandbox denying host HOME, system bus, network, and runtime sockets.
- Synthetic service doubles, real pointer and keyboard through the child sockets, screenshots from the child compositor, and retained logs for every phase.
- A 300-second deadline per suite sandbox, 30-second command/readiness budgets, and child shutdown escalating from SIGTERM to SIGKILL after two seconds.
Never launch `lifecycle.qml` or `niri-integration.qml` directly: the runner's isolated service substitutions are mandatory.
## Requirements
`just deps` holds the host package list; every `just` recipe checks it first and names anything missing.
## Suites
`just ui-test [fixture] [WIDTHxHEIGHT]`; default `all`.
`all` runs `shell`, `controls`, `popups`, `privilege`, `bar`, every feature suite, and `niri`, at most two concurrent sandboxes, and prints one line per suite with its evidence directory; a failed suite leads with its failing check.
Bounded admission prevents software-rendered compositors from starving startup I/O.
Interruption cleans active sandboxes and reports queued suites as not run.
Rerun a single suite by name while iterating.
- `shell`: production composition against private service stand-ins, opening every popup and overlay.
- `controls`: shared `PopupButton`, `PopupSlider`, `PopupTextField` with real input.
- `popups` — clock and registry system popups with isolated service doubles: switching, polling gate, Escape, outside and Bar dismissal, transition diagnostics.
- `privilege` — prompt focus, typing, reveal, cancel, Escape, failure shake.
- `bar`: chip presentation, end-slot placement, clipboard/launcher switching, every popup in vertical layout, native dark/light/dark theme switching across shell, terminal, editor and mail client.
- Every `features/<name>/fixtures/suite.mjs` runs as `just ui-test <name>` on `bar.qml`, followed by its optional `production.mjs` proof.
- `qt-focus`, `qt-focus-editor` — plain-Qt focus diagnostics; not part of `all`.
- `niri` — native integration: real Niri subscription, Bar pills, the focused application reaching the vault at each opening, overview, hotplug, xdg-shell clients, clipboard paste focus return.
Each selection starts from checked-in synthetic state and runs that suite's assertions, not a recorded input stream.
## Evidence
Everything lands in a fresh `$TMPDIR/nuguland-ui-test-*` directory (default `/tmp`, cleared on reboot).
Each run first prunes older runs, keeping the newest 3 per fixture and anything written in the last 15 minutes.
The evidence directory contains:
- `failure.json` — original error, phase, latest safe snapshot, capture errors.
- `replay.json` — selected fixture, exact public rerun command, current phase.
- `failure.png` — child-compositor screenshot when capture was possible.
- `diagnostics.jsonl` with the fixture-specific log (`bar.log`, `lifecycle.log`, `niri-integration.log`, etc.): snapshot IDs and popup transitions.
- `commands.log`, fixture and compositor logs, `versions.txt`, `outputs.json`.
- Suite-specific records: `assertions.jsonl`, `resource-dispatch.jsonl`, `resource-probe-checks.json`, `niri-*.json`, and the `*-*.png` screenshots.
Screenshots contain only sandbox fixture data. Revealed nonempty authentication input refuses capture and records the refusal; a missing screenshot is explicit, never a pass.
## Approved diagnostic exceptions
At most one expected `niri::backend::winit` DEBUG software-EGL record, bound to `niri.log`.
Qt fixture logs additionally tolerate the observed Qt 6.12.0 text-input focus warnings (QTBUG-146211) until the installed Qt changes.
Exact allowed shapes, counts, scope and removal conditions live in [RULES](../../.system/RULES.md).
## Tooling
Follow the [official Quickshell language-server setup](https://quickshell.org/docs/v0.3.2/guide/install-setup/#language-server): create `.qmlls.ini` and let Quickshell generate it.
Use Qt6 executables, particularly `/usr/lib/qt6/bin/qmllint` on this host.
Do not patch static metadata to pretend it models runtime-only backend registration.