qa-browse

name	qa-browse
description	Drive a real browser from the CLI to QA a flow — navigate, click, fill, verify. Uses @playwright/cli (token-efficient, not MCP). Use with /qa-browse when the user wants to manually check a web flow works, not write a test suite.
argument-hint	<url> <what to verify>

QA Browse — CLI browser driving with @playwright/cli

/qa-browse opens a live browser via @playwright/cli (binary playwright-cli) and walks a flow to verify it works. No test files. No MCP. This is distinct from the standard Playwright CLI (npx playwright, used for test/codegen/show-trace).

Engine: @playwright/cli (Microsoft). Snapshots live on disk, not in context — cheap tokens. Browser stays alive between commands.

Rules

• If not installed globally, run via the scoped package: npx @playwright/cli (NOT npx playwright-cli — that resolves the unscoped name and fails with ENOTFOUND). Never assume global.
• Loop: snapshot → read refs → act → re-snapshot. Always.
• Refs (e5, e12) are valid only for the latest snapshot. Re-snapshot after any navigation/click that changes the page.
• Headless by default. Add --headed only when a human must watch.
• Prefer refs over CSS. Use getByRole/getByText selectors only if a ref isn't available.
• Verify with eval or a snapshot of the result region — don't assume an action worked.
• Screenshot on each pass/fail checkpoint so there's evidence.
• close when done.

Setup

npm install -g @playwright/cli@latest   # or run ad-hoc: npx @playwright/cli
playwright-cli install-browser chromium  # first run in a fresh env (NOT `install` — that inits a workspace)

Core loop

playwright-cli open <url>        # open + navigate (prints a snapshot path)
playwright-cli snapshot          # accessibility tree with refs → read it
playwright-cli click e15         # act using a ref
playwright-cli fill e5 "text"    # fill input (add --submit to press Enter)
playwright-cli type "text"       # type into focused element
playwright-cli press Enter       # key press
playwright-cli snapshot          # re-snapshot to confirm new state
playwright-cli screenshot        # evidence
playwright-cli close

Interact

playwright-cli click <ref> [button]     # left/right/middle
playwright-cli dblclick <ref>
playwright-cli fill <ref> <text> --submit
playwright-cli select <ref> <value>     # dropdown
playwright-cli check <ref> / uncheck <ref>
playwright-cli hover <ref>
playwright-cli drag <startRef> <endRef>
playwright-cli upload ./file.pdf
playwright-cli dialog-accept / dialog-dismiss

Navigate

playwright-cli goto <url>
playwright-cli go-back / go-forward / reload

Inspect & verify

playwright-cli snapshot --depth=4          # shallow tree on big pages
playwright-cli snapshot e34                 # drill into a subtree
playwright-cli snapshot --raw | grep button # script-friendly
playwright-cli eval "document.title"        # read page state
playwright-cli eval "el => el.textContent" e5
playwright-cli eval "el => el.getAttribute('data-testid')" e5
playwright-cli console                       # console messages

Evidence

playwright-cli screenshot --full-page        # full scrollable page (bare `screenshot` = current viewport)
playwright-cli screenshot e5                 # one element
playwright-cli screenshot --filename=step1.png
playwright-cli video-start / video-stop
playwright-cli tracing-start / tracing-stop  # record a trace; view it with: npx playwright show-trace <trace>
playwright-cli pdf --filename=page.pdf

Sessions

State (cookies, localStorage) persists within a session across commands.

playwright-cli --session=qa open <url>       # named session
playwright-cli -s=qa open <url> --persistent # save profile to disk
playwright-cli list                          # running sessions
playwright-cli show                          # live dashboard, take over mouse/kbd
playwright-cli close-all / kill-all

QA flow checklist

1. open <url> → snapshot.
2. For each step: find ref in snapshot → act → re-snapshot → verify expected element/text.
3. screenshot at each checkpoint (pass and fail).
4. On failure: eval the element, capture console, take a --headed re-run or trace.
5. Report: what passed, what failed, with screenshot/snapshot paths. close.

Example — login flow

playwright-cli open https://app.example.com/login
playwright-cli snapshot
playwright-cli fill e1 "[e-mail]"
playwright-cli fill e2 "secret" --submit
playwright-cli snapshot                       # expect dashboard
playwright-cli eval "document.title"
playwright-cli screenshot --filename=logged-in.png
playwright-cli close

When NOT to use

• Want a saved, repeatable test suite → use /tdd or write @playwright/test specs.
• Need long-running autonomous loops or persistent introspection → Playwright MCP may fit better.