qa

name	qa
description	Run quokka's real-device E2E layer (QA strategy layer 5): drive the real qk binary against connected iPhone/Android devices through tmux, apply deterministic verifiers, and write a report. Use when the user asks to "run /qa", "run the device QA suite", "test against the real device", or before a release. Optionally finishes with an advisory exploratory UX pass (layer 6).

/qa — real-device E2E runner

You are the driver for layer 5 of the QA strategy (docs/superpowers/specs/2026-06-01-qa-strategy-design.md). You run the real binary against attached hardware and decide pass/fail deterministically.

Hard rule

Pass/fail is decided ONLY by the deterministic predicates below (exit code, regex over captured text, golden-frame compare, JSON validity). You do not use your own judgment to pass or fail a case. Subjective UX judgment belongs to the optional exploratory pass at the end, which is advisory and never a gate.

Preconditions

1. tmux and jq installed. If tmux is missing, stop and tell the user brew install tmux.
2. A current build: run cargo build (debug qk at target/debug/qk).
3. At least one device attached. Detect platforms: tests/llm/lib/drive.sh platforms → prints ios and/or android. If empty, stop and tell the user to connect a device.

All mechanics go through tests/llm/lib/drive.sh (see its header for the subcommands). Never reimplement the tmux dance inline.

Procedure

Read every tests/llm/*.yaml (not lib/, not golden/, not reports/). For each case, in file order:

1. Check requires against the detected platforms.

   • any → at least one device present.
   • ios / android → that platform present.
   • Not met → record SKIP with the reason. Never fail on absence.

2. Run it.

   • No interact block (non-interactive): drive.sh run <command>. The output ends with __QA_EXIT__=<code>. The captured text above that line is the output.
   • Has interact (interactive TUI):
     • drive.sh start <session> <command> (use a unique session like qa_<id>).
     • For each step: wait_for: X → drive.sh wait <session> "X" <timeout>; keys: [..] → drive.sh keys <session> <k1> <k2> ....
     • After the steps, capture the frame: drive.sh capture <session>.
     • Send quit_keys (default q) and drive.sh stop <session>.
     • If wait times out, that is a FAIL (the TUI never reached the expected state).

3. Apply every verify predicate against the captured output/frame:

   Predicate	Check
   exit_code: N	the __QA_EXIT__ value equals N
   output_matches: R	regex R matches the captured output
   frame_matches: R	regex R matches the captured frame
   frame_excludes: R	regex R does not match the frame
   json_valid: true	the captured output parses as JSON (jq . <<<output)
   golden_frame: name	the frame equals tests/llm/golden/<name>.txt exactly
   A case PASSES only if every predicate holds. A case with no predicates and a
   clean run is a PASS but flag it as "smoke-only".

4. Always tear the session down even on failure (drive.sh stop).

Report

Write tests/llm/reports/<YYYY-MM-DD-HHMM>.md containing:

• a summary line: N passed, M failed, K skipped and the detected platforms;
• per case: id, status (PASS/FAIL/SKIP), which predicate failed (if any), and the captured frame in a fenced block (the trajectory, for debugging).

Then print the summary to the user. If anything failed, lead with the failures.

Optional: exploratory UX pass (layer 6, advisory)

Only if the user asks for it, or it is pre-release. After the deterministic suite, drive a connected device freely beyond the scripted cases — open each TUI, trigger an error path (e.g. unplug mid-command if the user is present), resize, navigate. Report UX smells ("this error doesn't say what to do", "the dashboard wraps awkwardly at 80 cols") as observations, NOT pass/fail. The user decides what becomes a ticket. Never gate a release on this pass.