browser-qa

Files (1)

• SKILL.md

SKILL.md (first lines)

# Browser QA: exercise the running app, report what breaks

Part of the **Verify** phase — see the `workflow` skill for tiers and sequencing.

You are a QA engineer. Test the app like a real user — load the pages this change
touched, click what a user would click, watch the console. Produce a report with
evidence. **NEVER fix anything.** Fixes go through the normal Build/Verify loop
(see Report-only discipline at the end).

## Tier plan

Match effort to the tier the `workflow` skill assigned (or infer from the change's risk):

| Tier | What to do |
|------|------------|
| **T1** (typo, comment, config-only) | Skip browser QA entirely. Say so and stop. |
| **T2** (normal features, including refactors; bug fixes) | Smoke the affected routes only: load, console clean, no failed requests, screenshot, one DOM assert per route. |
| **T3** (money, auth, user data, migrations — or pre-ship of such work) | Full plan: affected routes **plus** adjacent routes and the top navigation targets, per-page checklist on each, health score with all categories. |

Every run — even T2 — ends with a health score and the plain-language summary.

## Scope: derive routes from the diff

Test what changed, not the whole site. From `git diff main...HEAD --name-only` and
`git log main..HEAD --oneline`, map changed files to routes:

> A multi-route QA run is token-heavy — a delegate trigger. Ask the user
> delegate-or-inline before running it (`delegate` skill).

| Changed file | Routes to test |
|---|---|
| Route/page file (`app/**/page.tsx`, `pages/foo.tsx`, `src/pages/foo.astro`) | The route it serves (`/foo`) |
| Shared component | Grep for importers; test the routes that render them |
| Layout, global CSS, providers | Every route inherits it — test homepage + one route per layout |
| API handler (`app/api/**`, `src/api/**`) | Hit the endpoint directly (fetch in the script or `curl`), plus the page that calls it |
| Model/service/lib code | Routes whose pages call into it |
| Backend/config/infra with no obvious route | Do NOT skip — smoke homepage + top 5 nav targets; backend changes still break pages |

Cross-reference commit messages to understand *intent*: what is this change supposed
to do? Verify it does that, not just that pages load.

## Driving the browser

**Prefer the built-in `verify` and `run` skills** when available in this environment:
`run` knows how to launch this project's app; `verify` drives a changed flow end-to-end.
If they cover the need, use them and fold their observations into the report below.

If the host supplies browser tools, prefer those and adapt the checks and
evidence below to that API. In Codex, follow the installed browser skill;
don't install Playwright or drive it through Bash when the host requires its
own browser tools.

Otherwise, drive Chromium yourself via Playwright through Bash.

**1. Get the app running.** Check common dev ports first — Next.js `:3000`,
Vite `:5173`, Astro `:4321`:

```bash
for p in 3000 5173 4321; do curl -sf -o /dev/null "http://localhost:$p" && echo "UP :$p"; done
```

If nothing is up, start `npm run dev` in the background, wait for the ready line,
and note the port. If the port can't be determined, ask the user for the URL.

**2. Check Playwright is available.**

```bash
node -e "require.resolve('playwright')" 2>/dev/null && echo READY || echo MISSING
```

If MISSING, ask the user once: "Browser QA needs Playwright (dev-only dependency).
OK to run `npm i -D playwright && npx playwright install chromium`?" Wait for a yes
before installing. Never install silently.

**3. Set up an evidence directory** in the session scratchpad (never inside the repo):

```bash
QA_OUT="$SCRATCHPAD/browser-qa-$(date +%Y%m%d-%H%M%S)"   # use this session's scratchpad dir
mkdir -p "$QA_OUT"
```

**4. Write the smoke script** to `$QA_OUT/qa-smoke.mjs` and run it with the route list:

```js
// qa-smoke.mjs — node qa-smoke.mjs <baseURL> [path ...]   (QA_OUT=screenshot dir)
import { chromium } from 'playwright';
const [base, ...paths] = process.argv.slice(2);
const routes = paths.length ? paths.map(p => new URL(p, base).href) : [base];
const out = process.env.QA_OUT || '.';
const browser = await chromium.launch();
const page = await browser.newPage();
const findings = [];
page.on('console', m => { if (m.type() === 'error') findings.push(`[console] ${page.url()} :: ${m.text()}`); });
page.on('pageerror', e => findings.push(`[exception] ${page.url()} :: ${e.message}`));
page.on('requestfailed', r => findings.push(`[netfail] ${r.url()} :: ${r.failure()?.errorText}`));
page.on('response', r => { if (r.status() >= 400) findings.push(`[http ${r.status()}] ${r.url()}`); });
for (const url of routes) {
  const res = await page.goto(url, { waitUntil: 'networkidle', timeout: 15000 })
    .catch(e => { findings.push(`[nav] ${url} :: ${e.message}`); return null; });
  if (!res) continue;
  const slug = new URL(url).pathname.replace(/\W+/g, '-').replace(/^-|-$/g, '') || 'home';
  await page.screenshot({ path: `${out}/${slug}.png`, fullPage: true });
  const body = (await page.textContent('body')) ?? '';
  if (!body.trim()) findings.push(`[blank] ${url} :: body rendered empty`);
  console.log(`VISITED ${url} -> ${slug}.png (status ${res.status()})`);
}
await browser.close();
console.log(findings.length ? findings.join('\n') : 'NO FINDINGS');
```

```bash
QA_OUT="$QA_OUT" node "$QA_OUT/qa-smoke.mjs" http://localhost:3000 / /pricing /dashboard
```

**Per-route DOM asserts and interactions:** extend a copy of the script for the
specific change — e.g. `await page.getByText('Saved!').waitFor({ timeout: 5000 })`
after clicking submit, or `page.getByRole('button', { name: 'Add' }).click()` then
re-screenshot. One throwaway script per flow is fine; they all live in `$QA_OUT`.
For SPAs, click links in-page rather than only `goto` — client-side routing bugs

From AbdurRafay2004/handoff, MIT.

More from AbdurRafay2004/handoff