qa-doctor

Browser QA your agent will actually run.

A static-discovery + live-browser CLI that maps every feature in a running web app, exercises each one with Playwright, and reports pass/fail with screenshots so you can iterate to green. Installs as an agent skill for Claude Code, Codex, Cursor, and Copilot.

Quick start

# 1. install Playwright once
npm i -D playwright && npx playwright install chromium

# 2. start your app
bin/dev          # or `npm run dev`, `bin/rails server`, etc.

# 3. scan
npx -y qa-doctor@latest scan . --url http://localhost:3000

You'll get a per-feature pass/fail report and a 0–100 score:

qa-doctor base http://localhost:3000 · 12 routes · 87 features

Failures (3)
  ✗ /pricing#form.subscribe
     ✗ Form has no <button type=submit> or <input type=submit>.  qa/form-no-submit
  ✗ /dashboard#page
     ✗ 2 console error(s) during load.  qa/console-error
        Cannot read properties of undefined (reading 'name') | …

  ┌─────────┐
  │  ◠ ◠  │   Score: 88/100  Great
  │   ▽   │   84/87 features passing
  └─────────┘

What it tests (v0.1)

For every route discovered:

• Page loads — HTTP 200, no uncaught JS exceptions, no console errors, no failed XHRs.
• Internal links resolve — HEAD on every <a href="/...">.
• Buttons present after load — selector still resolves (catches "vanished button" regressions).
• Forms have submit affordance — at least one <button type="submit"> or <input type="submit">.
• Destructive buttons flagged but not clicked — no accidental data loss during a scan.

What it does not test in v0.1:

• Submission with valid data (planned for v0.2).
• Multi-step flows (login → use feature → logout).
• Visual regression vs a baseline (use design-doctor's vision pass).
• Performance budgets.

The iteration loop

This is the whole point.

1. npx -y qa-doctor@latest scan . --markdown > qa-report.md
2. Open the report. Every failing feature has its own bullet with a screenshot path.
3. Fix the failures.
4. Re-run.
5. Repeat until score is 100.

Don't bundle multiple fixes per iteration. Fix one feature, re-scan, see the score move, fix the next. Tight loop = honest signal.

Auth

If your app needs login, set environment variables:

QADOCTOR_LOGIN_URL=http://localhost:3000/login
[email protected]
QADOCTOR_PASS=secret

For complex flows, point QADOCTOR_LOGIN_SCRIPT at a JS file exporting async login(page). qa-doctor caches the auth state at .qa-doctor/auth.json for 24h.

Companion: rails-doctor + design-doctor

For full coverage of a Rails+Inertia or TanStack app, run all three:

| Tool | What it scores | |---------------|-----------------------------------------------------------------------| | qa-doctor | Does every feature still work in a real browser? | | design-doctor | UX/UI quality (design tokens, microcopy, a11y, shadcn use) | | rails-doctor | Ruby side: routes, models, migrations, security, Inertia conventions |

npx -y rails-doctor@latest scan .       # Ruby side
npx -y design-doctor@latest scan .      # React (static)
npx -y qa-doctor@latest scan .          # React (live browser)

Configuration

Drop .qadoctor.json at the project root:

{
  "url": "http://localhost:3000",
  "routes": ["/", "/pricing", "/dashboard"],
  "routesCap": 25,
  "featuresCap": 200,
  "ignoreSelectors": [".admin-only-button"],
  "destructiveSelectors": [".bulk-delete-button"]
}

Installation as an agent skill

npx -y qa-doctor@latest install

Drops SKILL.md into every detected agent dir (~/.claude/skills/qa-doctor/, ~/.agents/skills/qa-doctor/, etc.). After install, your agent will know how to run qa-doctor and iterate on the report.

CI integration

- run: bin/dev &
- run: |
    until curl -fsS http://localhost:3000/ > /dev/null; do sleep 1; done
- run: npx -y qa-doctor@latest scan . --min-score 90

License

MIT. See LICENSE.