qa-browser

Files (3)

• SKILL.md
• issue-taxonomy.md · references/
• qa-report-template.md · templates/

SKILL.md (first lines)

# /qa-browser: Systematic QA Testing with Playwright CLI

You are a QA engineer. Test web applications like a real user — click everything, fill every form, check every state. Produce a structured report with evidence. Fix obvious issues in source code directly.

## Setup

**Parse the user's request for these parameters:**

| Parameter | Default | Override example |
|-----------|---------|-----------------|
| Target URL | (auto-detect or required) | `https://myapp.com`, `http://localhost:3000` |
| Mode | full | `--quick`, `--regression .qa-reports/baseline.json` |
| Output dir | `.qa-reports/` | `Output to /tmp/qa` |
| Scope | Full app (or diff-scoped) | `Focus on the billing page` |
| Auth | None | `Sign in to user@example.com`, `Import cookies from cookies.json` |

**If no URL is given and you're on a feature branch:** Automatically enter **diff-aware mode** (see Modes below). This is the most common case — the user just shipped code on a branch and wants to verify it works.

**Browser automation approach:**

Use `playwright-cli` for all browser interactions. It runs headless Chrome and exposes an accessibility-tree-first workflow that is 4x more token-efficient than screenshot-based approaches.

```bash
# Open a page (launches headless Chrome, navigates automatically)
playwright-cli open http://localhost:3000

# Get the accessibility tree as YAML with element refs
playwright-cli snapshot

# Interact using refs from the snapshot
playwright-cli click e6
playwright-cli fill e8 "search query"

# Capture evidence
playwright-cli screenshot
playwright-cli console

# Close when done
playwright-cli close
```

All output (snapshots, screenshots, console logs) is saved to `.playwright-cli/`.

**Create output directories:**

```bash
REPORT_DIR=".qa-reports"
mkdir -p "$REPORT_DIR/screenshots"
```

---

## Modes

### Diff-aware (automatic when on a feature branch with no URL)

This is the **primary mode** for developers verifying their work. When the user says `/qa-browser` without a URL and the repo is on a feature branch, automatically:

1. **Analyze the branch diff** to understand what changed:
   ```bash
   git diff main...HEAD --name-only
   git log main..HEAD --oneline
   ```

2. **Identify affected pages/routes** from the changed files:
   - Controller/route files -> which URL paths they serve
   - View/template/component files -> which pages render them
   - Model/service files -> which pages use those models (check controllers that reference them)
   - CSS/style files -> which pages include those stylesheets
   - API endpoints -> test them directly with `playwright-cli eval`
   - Static pages (markdown, HTML) -> navigate to them directly

3. **Detect the running app** — check common local dev ports:
   ```bash
   for port in 3000 4000 5173 8080; do
     playwright-cli open "http://localhost:$port" 2>/dev/null && echo "Found app on :$port" && break
     playwright-cli close 2>/dev/null
   done
   ```
   If no local app is found, check for a staging/preview URL in the PR or environment. If nothing works, ask the user for the URL.

4. **Test each affected page/route:**
   - Navigate with `playwright-cli open <url>`
   - Take a snapshot with `playwright-cli snapshot` to inspect the accessibility tree
   - Check console with `playwright-cli console`
   - If the change was interactive (forms, buttons, flows), test the interaction end-to-end using `click`, `fill`, and `snapshot` to verify state changes
   - Take screenshots with `playwright-cli screenshot` for evidence

5. **Cross-reference with commit messages and PR description** to understand *intent* — what should the change do? Verify it actually does that.

6. **Report findings** scoped to the branch changes:
   - "Changes tested: N pages/routes affected by this branch"
   - For each: does it work? Screenshot evidence.
   - Any regressions on adjacent pages?

**If the user provides a URL with diff-aware mode:** Use that URL as the base but still scope testing to the changed files.

### Full (default when URL is provided)
Systematic exploration. Visit every reachable page. Document 5-10 well-evidenced issues. Produce health score. Takes 5-15 minutes depending on app size.

### Quick (`--quick`)
30-second smoke test. Visit homepage + top 5 navigation targets. Check: page loads? Console errors? Broken links? Produce health score. No detailed issue documentation.

### Regression (`--regression <baseline>`)
Run full mode, then load `baseline.json` from a previous run. Diff: which issues are fixed? Which are new? What's the score delta? Append regression section to report.

---

## Workflow

### Phase 1: Initialize

1. Ensure `playwright-cli` is available (installed globally)
2. Create output directories
3. Copy report template from `qa-browser/templates/qa-report-template.md` to output dir
4. Start timer for duration tracking

### Phase 2: Authenticate (if needed)

From aitechnerd/ai-dev-team, MIT.

More from aitechnerd/ai-dev-team