@app-studio/qa-cli
One command surface for humans and agents.
qa demos run autonomously records changed API and canonical browser scenarios
with QA's native CSS browser and FFmpeg, without Playwright. qa demos plan
explains selection; qa demos check checks source/artifact freshness without
launching anything. Configure scenario/code/shared inputs in qa.demos.json
and ignore tmp/qa/ in Git. Keep current proof through local review/commit;
push triggers best-effort cleanup of owned proof without scanning or rejecting
commits. If a run is active, its proof stays intact until the run finishes, then
cleanup retries. Install/reinstall with qa demos install-hook after a
clone or CLI replacement; see the shared-checkout recipe in Automatic demos. Only the latest complete success and latest relevant failure are
retained per demo. --stage and --committed are rejected before execution;
evidence is never staged. Cleanup preserves active, symlinked or unowned output
and reports deferred cleanup without blocking the push. See Automatic demos.
qa api studio --base-url <url> opens the real HTTP workbench; qa api run
uses the same assertions headlessly. Configure --checkpoint-adapter <module>
to save a prefix with --save-checkpoint <id> --until <step>, then restore and
run only its suffix with --checkpoint <id>. qa api restore restores for site
inspection without running the suffix. See API Studio.
qa state validate
qa state list
qa state inspect --id <id>
qa state run --id <id> [--mode mock|live] [--engine <name>] [--profile fast|proof|record] [--screenshots] [--video mp4|webm|gif] [--diagnostics=false]
qa design record --file <acceptance.json> --reviewer <designer-id>
qa design validate [--feature <key>]
qa design list
qa scenario validate
qa scenario list
qa scenario coverage
qa scenario run --id <id> [--mode mock|live] [--engine <name>] [--profile fast|proof|record] [--screenshots] [--video mp4|webm|gif] [--diagnostics=false]
qa scenario run [--mode mock|live] # complete release-candidate portfolio
qa scenario benchmark --id <id> --engine lightpanda [--runs 5]
qa browser list [--json]
qa browser build lightpanda --source <checkout> [--dir <bundle-dir>]
qa browser install lightpanda [--release <tag> | --artifact <bundle-dir>] [--dir <path>]
Validation reads the original App Studio feature/form specs (or explicit
Scenario v3 migration files). A feature compiles to <feature>:best plus one
ID per if condition. Runtime commands resolve the live host from
qa.bindings.json and pass the selected ID through environment variables.
Named engines select application-owned commands; capability declarations stop
a DOM-only engine from being used for visual proof or video. The CLI does not
maintain a copied flow catalogue or a second browser implementation.
QA installs the matching native CSS browser on macOS/Linux ARM64 and x64 through optional dependencies. qa browser list identifies it; qa browser install lightpanda uses the included build. --release nightly selects upstream explicitly. Keep optional dependencies enabled. Explicit Lightpanda runs require a verified native bundle; use QA_LIGHTPANDA_EXECUTABLE with a locally built bundle when developing.
Puppeteer suites retain bounded console/request/error/heap diagnostics by default. Add --video gif, mp4 or webm to record the actual scenario page (FFmpeg required). The shared launchLightpanda API owns a loopback daemon and its engine output. See native capture integration.
For Lightpanda diagnostics, add --screenshots to a fast state or scenario run.
The shared Puppeteer host captures the current page, including failures, and emits
a JSON index with absolute PNG paths and fidelity: "markdown" by default.
For the modified native bundle, set QA_LIGHTPANDA_FIDELITY=native-css.
See Native capture builds for macOS/Linux builds,
verified artifact installation and the bundled PNG/video/GIF helper. The CLI passes
QA_BROWSER_SCREENSHOTS=true and QA_STATE_OUTPUT_DIR/QA_SCENARIO_OUTPUT_DIR
from the subject's evidence binding, or test-results/qa-states/qa-scenarios.
Use --screenshots=false to disable an inherited request. PNG diagnostics do not
prove that a host preserves the full checkpoint contract. A native host can
declare visual proof/record when it uses the verified native CSS build, the
canonical checkpoint collector and real PNG/video captures; this does not
certify desktop-browser pixel parity.
qa browser install lightpanda stages the native browser, proves it runs with
lightpanda version, and only then moves it into ~/.local/bin (or --dir).
The native recorder and migrated suites require no Playwright installation.
Use QA Browser for their acceptance and report capability failures with the
exact command and evidence. Legacy engine-management commands remain available
for existing external consumers; these runners never fall back to them.
Use qa run --list to inspect the progressive proof layers and qa run --from <layer> only after lower layers are known green.
Standalone capture hosts can use the exported beginProofOutput(root, output, id)
to write into an owned scratch directory, then call finish(passed) in finally
after closing their browser/world. It retains one success and latest relevant
failure, shares the output lock with CLI cleanup, and leaves assertions and
provenance with the host. A push requests cleanup; if this output is still active,
the host finishes first and then retries the pending cleanup.