Luigit
repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by admin

quickshell/nuguland/test-fixtures/ui/README.md

Raw
Rendered preview

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; 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.

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.