# 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//fixtures/suite.mjs` runs as `just ui-test ` 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.