qa-only

What this skill does

# QA Report-Only: Test and Document

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. **NEVER fix anything.**

**Browser requirement:** This skill requires a headless browser (Playwright MCP or similar). If no browser tool is available, inform the user.

## 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` |
| Scope | Full app (or diff-scoped) | `Focus on the billing page` |

**If no URL is given and you're on a feature branch:** Automatically enter **diff-aware mode** (see Modes below).

---

## Modes

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

The **primary mode** for developers verifying their work:

1. **Analyze the branch diff:**
   ```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
   - CSS/style files → which pages include those stylesheets
   - API endpoints → test them directly
   - Migration/schema files → identify which models are affected, then trace to pages that display or mutate that data. If migrations exist in the diff, verify the app still loads correctly.
   - Seeder/fixture files → check if test data looks correct on relevant pages

   **If no obvious pages/routes are identified:** Fall back to Quick mode — homepage + top 5 navigation targets.

3. **Detect the running app** — check common local dev ports (3000, 4000, 8080). If none found, ask the user for the URL.

4. **Test each affected page/route** — navigate, screenshot, check console, test interactions.

5. **Cross-reference with commit messages** to verify the change does what it intends.

6. **Check TODOS.md** for known bugs related to changed files.

### Full (default when URL is provided)
Systematic exploration. Visit every reachable page. Document 5-10 well-evidenced issues. Produce health score.

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

### Regression (`--regression`)
Run full mode, then compare against a previous baseline. Diff: which issues are fixed? Which are new? Score delta?

---

## Workflow

### Phase 1: Initialize

1. Ensure browser is available
2. Create output directories for screenshots and report
3. Start timer for duration tracking

### Phase 2: Authenticate (if needed)

If auth is required, navigate to login and authenticate. **NEVER include real passwords in the report** — write `[REDACTED]`.

If CAPTCHA blocks you, tell the user to complete it manually.

### Phase 3: Orient

1. Navigate to the target URL
2. Take an annotated screenshot
3. Map navigation structure
4. Check console for errors on landing
5. **Detect framework** (Next.js, Rails, WordPress, SPA, etc.)

### Phase 4: Explore

Visit pages systematically. At each page:

1. **Visual scan** — layout issues visible in screenshot
2. **Interactive elements** — Click buttons, links, controls. Do they work?
3. **Forms** — Fill and submit. Test empty, invalid, edge cases
4. **Navigation** — Check all paths in and out
5. **States** — Empty state, loading, error, overflow. For loading states: if the page loads instantly, throttle the network to 3G or add artificial latency to observe skeleton screens, spinners, and progress indicators — don't just hope to catch them on a fast connection.
6. **Console & Network** — Check for JS errors after interactions. Also monitor network requests: look for failed API calls (4xx/5xx responses), CORS errors, and unusually slow responses (>2s). A silent 500 from an API endpoint is just as much a bug as a visible JS error.
7. **Responsiveness** — Check mobile viewport if relevant
8. **Accessibility** — Tab through every interactive element on the page. Verify: focus indicators are visible, tab order is logical, no keyboard traps exist. Check that images have meaningful alt text, form inputs have associated labels, and ARIA attributes are used correctly. Test with color contrast in mind — text should meet WCAG AA (4.5:1 for normal text, 3:1 for large text). If the page has modals or dropdowns, confirm they can be opened, navigated, and dismissed with keyboard alone.
9. **Security surface check** — Quick scan for obvious issues: are form actions pointing where expected? Are there open redirect parameters in URLs? Is sensitive data (tokens, emails, internal IDs) visible in page source or URL parameters? Check that the page is served over HTTPS and isn't loading mixed content.
10. **Performance** — Monitor network requests for slow API calls (>2s). Look for oversized assets (images >500KB, JS bundles >1MB). Watch for layout shifts as the page loads. Note if the page takes >1s to become interactive after navigation.

**Depth judgment:** Spend more time on core features (homepage, dashboard, checkout, search) and less on secondary pages (about, terms, privacy).

**Quick mode:** Only homepage + top 5 navigation targets. Just check: loads? Console errors? Broken links?

### Phase 5: Document

Document each issue **immediately when found** — don't batch.

**Interactive bugs:** before/after screenshot pair + repro steps
**Static bugs:** single annotated screenshot + description

### Phase 6: Wrap Up

1. **Compute health score** using the rubric below
2. **Write "Top 3 Things to Fix"** — the 3 highest-severity issues, with enough context that a developer who wasn't in the session can understand and prioritize them
3. **Write console & network health summary** — aggregate JS errors and failed API calls across all pages
4. **Update severity counts** in the summary table
5. **Fill in report metadata** — date, duration, pages visited, screenshot count, framework

---

## Health Score Rubric

Compute each category score (0-100), then take the weighted average.

### Console (weight: 10%)
- 0 errors → 100
- 1-3 errors → 70
- 4-10 errors → 40
- 11-20 errors → 20
- 21-50 errors → 10
- 50+ errors → 0

### Network (weight: 5%)
- 0 failed requests → 100
- 1-2 failed requests → 60
- 3-5 failed requests → 30
- 6+ failed requests → 10

### Links (weight: 10%)
- 0 broken → 100
- Each broken link → -15 (minimum 0)

### Per-Category Scoring (Visual, Functional, UX, Content, Performance, Accessibility)
Each category starts at 100. Deduct per finding:
- Critical → -25, High → -15, Medium → -8, Low → -3
Minimum 0 per category.

### Weights
| Category | Weight |
|----------|--------|
| Console | 10% |
| Network | 5% |
| Links | 10% |
| Visual | 10% |
| Functional | 20% |
| UX | 15% |
| Performance | 10% |
| Content | 5% |
| Accessibility | 15% |

---

## Framework-Specific Guidance

### Next.js
- Check for hydration errors, `_next/data` 404s, CLS on dynamic content
- Test client-side navigation (click links, don't just navigate directly)

### Rails
- Check for N+1 warnings, CSRF tokens, Turbo/Stimulus transitions, flash messages

### WordPress
- Check for plugin conflicts, admin bar, REST API, mixed content warnings

### General SPA
- Check for stale state, browser back/forward handling, memory leaks

---

## Classifying Issues

Since the report is the entire deliverable, clear classification is what makes it actionable. Every issue needs both a **severity** and a **category**.

### Severity

- **Critical** — The feature is broken or data is lost. Users cannot complete a core workflow. Examples: form submission crashes, checkout fails, login loop, data corruption.
- **High** — Significant functionality is impaired but a workaround exists, or the issue affects a core page's usability. Exampl