docs

QA harness CLI

Every hugin qa subcommand for release-time validation — walkthroughs, wiring and settings audits, runtime traversals, backend exercise, E2E gates, and design audits.

The hugin qa commands are the release-time validation harness. They drive the running Hugin binary through its UI command socket (~/.hugin/ui_command.sock) to walk every sidebar tab, exercise controls, and assert the design system hasn't drifted. Use these before cutting a release.

All commands write a JSON report to the output directory and exit non-zero on failure (configurable per command).

walkthrough

Walk every sidebar tab: navigate to it, list registered components, read their state, and optionally capture a screenshot. The broadest smoke test.

hugin qa walkthrough --out /tmp/hugin-release-0.1.0
hugin qa walkthrough --capture --settle-ms 400
hugin qa walkthrough --views SiteMap,Repeater,Scanner --strict-views
FlagDefaultDescription
--out/tmp/hugin-release-0.1.0Output directory for report JSON + PNGs
--captureoffCapture per-tab window screenshots (needs screencapture on macOS)
--settle-ms250Milliseconds to wait after NavigateView before probing
--strict-viewsoffTreat unknown views (no from_name match) as fatal
--viewsallComma-separated filter using variant names or labels

wiring-audit

Runtime wiring audit: navigate tabs, list registered controls, read supported state. Similar to walkthrough but focuses on control readback rather than screenshots.

hugin qa wiring-audit --out /tmp/hugin-ui-wiring --fail-on-unreadable
FlagDefaultDescription
--out/tmp/hugin-ui-wiringOutput directory for report JSON
--settle-ms250Wait after NavigateView before probing
--strict-viewsoffUnknown views are fatal
--viewsallComma-separated filter
--fail-on-unreadableoffExit non-zero when readable components fail state readback

settings-audit

Settings window wiring audit: open Settings and read each nested tab.

hugin qa settings-audit --fail-on-unreadable
FlagDefaultDescription
--out/tmp/hugin-ui-settingsOutput directory for report JSON
--settle-ms250Wait after settings tab changes
--fail-on-unreadableoffExit non-zero when components fail state readback

runtime-traversal

Runtime traversal: navigate tabs and exercise safe controls through UiAction dispatch. Goes beyond wiring-audit by actually interacting with controls, not just reading their state.

hugin qa runtime-traversal --strict
FlagDefaultDescription
--out/tmp/hugin-ui-runtimeOutput directory for report JSON
--settle-ms250Wait after view changes or UI actions
--strict-viewsoffUnknown views are fatal
--viewsallComma-separated filter
--strictoffExit non-zero on any failed runtime probe

e2e

Launch E2E gate: seed data and verify core UI/backend workflows through the live socket. The gate that must pass before a release ships.

hugin qa e2e --strict
FlagDefaultDescription
--out/tmp/hugin-ui-e2eOutput directory for report JSON
--settle-ms300Wait after view changes or UI actions
--strictoffExit non-zero on any failed workflow

exercise

Backend exercise: drive each covered view's principal control and then assert the effect through the internal REST surface — not the UI echo. This is the gate that answers "is this function actually connected to its backend?", which a wiring audit cannot: a control can publish truthful state, echo every write back correctly, and still never reach the store.

hugin qa exercise --strict
hugin qa exercise --views "Wordlists,InterceptRules" --strict
FlagDefaultDescription
--out/tmp/hugin-ui-exerciseOutput directory for report JSON
--settle-ms300Wait after a view change or a dispatched action
--strictoffExit non-zero when a covered view has a control that does not reach its backend
--viewsallComma-separated view filter (variant name or label)

Each covered view gets a unique qa-exercise-<id> fixture, the assertion polls the backend until the write lands (a write goes out through a spawned REST call, so reading once is a race), and the fixture is deleted afterwards. A view that cannot be exercised safely is reported uncovered with the specific reason rather than counted as a pass, and a control measured as not reaching its backend is reported disconnected with the evidence.

design-audit

Static design-system audit: checks primitive token drift and inventories raw Dioxus controls. Does not need a running binary — this is a source-tree scan.

hugin qa design-audit --strict-shared-controls
hugin qa design-audit --fail-on-raw-controls
FlagDefaultDescription
--out/tmp/hugin-ui-designOutput directory for report JSON
--strict-shared-controlsoffFail on raw Dioxus controls in shared components already migrated to UI primitives
--fail-on-raw-controlsoffAlso fail while raw Dioxus controls exist outside UI primitives

The QA harness requires a running Hugin binary (except design-audit). Start the desktop app or a headless instance before running walkthrough, wiring-audit, settings-audit, runtime-traversal, e2e, or exercise.

Last updated 2026-07-10.