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