cskwork browser-qa - browser QA on anything, for anyone
Skill browser-qa, runtime command superqa. Contract: prompt -> scenarios -> real
browser evidence -> report in the user's language.
Mode (classify the request, state it in one line)
| Signal in request | Mode | Route |
|---|---|---|
| known domain / "QA " / repeat QA on something QA'd before | DOMAIN-QA | load the domain pack, QA per feature area, reuse archived scripts (reference/domain-packs.md) |
| "QA this ", vague target, no scenarios yet | EXPLORE-QA | explore live site, generate scenario cases, run them (reference/agent-qa.md) |
| scenarios exist / "run the cases" / feature finished, verify | REGRESSION | superqa run --all --site <site>; diff vs last run (reference/agent-qa.md step 5) |
| "quick check / smoke / is it up" | AUTO | superqa auto <url> --site <site> |
| non-dev wants to create a test by clicking | RECORD | superqa record <url> or TUI n key (reference/tui.md) |
| "every N minutes / daily / automate" | SCHEDULE | superqa schedule add <scenario> --every <min> + daemon (reference/tui.md) |
| "open the QA app / dashboard" | TUI | web dashboard superqa serve; terminal bash scripts/superqa.sh (reference/tui.md) |
| "test locally / without the dev server / offline", shared env down, destructive cases | LOCAL-OFFLINE | bring the stack up locally, run the same scenarios with --var base_url=... (reference/local-offline.md) |
Hard rules
- Site knowledge stays local. Entry URLs, accounts, login quirks, popup behavior live
in
~/.superqa/sites/<site>/rules.md+ the var store. Never committed, never in a pushed scenario (reference/site-rules.md). - Credentials via the var store only.
superqa vars set <site> username|password <v>; scenarios use{{username}}/{{password}}. Password-like keys auto-mask in reports. - Evidence or it did not happen. Every run writes
~/.superqa/reports/<stamp>-<name>/report.html+ per-step screenshots. Quote the path and the pass/fail counts. - Report in the user's language. Scenario
language:drives report labels; your summary follows the conversation (reference/report.md). - Side effects are findings. Console errors, failed requests, 4xx/5xx, unexpected
dialogs/tabs are collected, deduped, and diffed; new types = regression signal. Declare
known noise in
ignore.yaml, never by hand (reference/side-effects.md). - Popups never block a run. Policy auto-accepts dialogs and follows new tabs; scenario
policy:overrides (reference/scenario-format.md). - Local copies of shared data are read-only at source, subsetted, redacted, uncommitted.
Local config gets dummy secrets only (
reference/local-offline.md). - Archive reusable scripts. Useful helpers go to
<packs_home>/<domain>/<feature>/scripts/with a provenance header; check the pack before writing a new one (reference/domain-packs.md). - Capability picks the engine, then the cascade. Response bodies, popups, or Windows
parity - go straight to the proven engine. One engine per page. Never lightpanda.
Replay is always the browser-qa engine. When the native
agent_browsertool is in your tool registry, prefer it over shelling out to the CLI - same engine, less context (reference/engines.md). - The DAG is the review contract.
dag.nodeswith stableid,story,acceptance,depends_on- no selectors or values, those live in the local runtime binding. Runsuperqa dag check --all --site <site>before executing. Legacysteps:files stay readable (reference/scenario-format.md).
EXPLORE-QA loop (default when only a URL/prompt is given)
- Ground. Read
~/.superqa/sites/<site>/rules.mdif present; ask for credentials only if login is required and vars are missing. - Explore. Drive the live site with the selected engine (snapshot -> click ->
snapshot;
reference/engines.md), mapping entry flow, login, menus, popups/new tabs (reference/agent-qa.md). - Generate cases. Write user-story
dag.nodesYAMLs to~/.superqa/scenarios/<site>/covering happy path, validation, error paths, edge cases, and meaningful popup/tab transitions. Review story/acceptance/dependencies withsuperqa dag check --all --site <site>and the Admin graph, then create the separate local runtime binding (reference/scenario-gen.md). - Run.
superqa run --all --site <site> --headless; without the installed command,python3 -m superqa_tui run ...from the checkout root, wheresuperqa_tui/lives. - Report. Read the report, triage side effects, summarize for the user in their language with the report path. Update the local site rules file with what you learned.
Non-dev lane (what you tell users)
superqa serve- browser dashboard: every scenario with its story DAG, Run button, live progress, history, inline reports. Exposes node IDs, stories, acceptance and dependencies only; selectors and values stay local.bash scripts/superqa.sh- terminal TUI:nrecord by clicking,rrun,arun all,uauto QA,sschedule,vaccounts/vars,oopen report.- Recording floats a panel in the page (pause / add-assertion / save); typed passwords are
stored as
{{password}}(reference/tui.md).
Reference map
| File | When |
|---|---|
reference/domain-packs.md |
DOMAIN-QA: per-domain/feature packs, script archiving, pack location config |
reference/engines.md |
capability gate + engine cascade; one-engine-per-page rule |
reference/agent-browser.md |
agent-browser + chrome-devtools-mcp commands, shared-Chrome login, measured gotchas |
reference/agent-qa.md |
EXPLORE-QA / REGRESSION procedure for the agent |
reference/scenario-gen.md |
prompt -> reviewable DAG scenario case design method |
reference/scenario-format.md |
user-story YAML DAG schema, local runtime binding, {{vars}}, policy |
reference/side-effects.md |
what is captured; triage rules |
reference/site-rules.md |
local per-site knowledge protocol (never commit) |
reference/report.md |
report structure + language rules |
reference/tui.md |
TUI / record / schedule usage for humans |
reference/local-offline.md |
LOCAL-OFFLINE: local stack + data subset, DB-derived fixtures, differential proof |
Done = mode stated. QA runs: scenarios exist as checked YAML DAGs under
~/.superqa/scenarios/<site>/; graph reviewed; run executed with the report path quoted;
side effects triaged; site rules updated, plus the domain pack in DOMAIN-QA; site data
still only in ~/.superqa/. RECORD / SCHEDULE / TUI: the surface is up and the user knows
which keys drive it.