qa

Files (1)

• SKILL.md

SKILL.md (first lines)

# qa — Browser QA Verification

## Identity

qa tests your app the way a user would: by actually using it. It launches a
browser, navigates to pages, clicks buttons, fills forms, and verifies that
interactions work. Screenshots catch visual bugs. QA catches interaction bugs.

## Dependency: Playwright

qa requires Playwright. It's an optional dependency.

**If Playwright is installed:** full browser QA works.
**If Playwright is NOT installed:** the skill offers to install it, or falls
back to live-preview (screenshot-only verification).

Detection:
```bash
npx playwright --version 2>/dev/null
```

Installation (if user agrees):
```bash
npm install -D playwright
npx playwright install chromium
```

Only installs Chromium (smallest download, ~150MB). Not Firefox or WebKit
unless the user asks for cross-browser testing.

**Setup integration:** During project setup, if the project is a web app (has
React, Next.js, Vue, Svelte, or HTML files), offer to install Playwright:
"I see this is a web project. Want to enable browser QA testing? This installs
Playwright (~150MB) for interaction testing. (y/n)"

If they say no, qa falls back to live-preview. No pressure.

## When to Use

- After building a feature (verify it actually works in a browser)
- As a phase end condition: "QA verification passes for [flow]"
- When the router matches: "qa", "test the app", "does it work", "click through it"
- When campaigns reach the verification phase
- After live-preview shows something renders but you need to verify interactions

## Protocol

### Step 1: DISCOVER

Before testing, understand what to test:

1. Read the project's routes/pages (from file tree, router config, or package.json scripts)
2. Read the PRD or campaign file (if exists) for expected user flows
3. Identify testable flows:
   - Page loads and renders (baseline)
   - Navigation between pages
   - Form submissions
   - Button click handlers
   - Auth flows (login, logout, protected routes)
   - CRUD operations (create, read, update, delete)
   - Error states (invalid input, network errors)

If no PRD or campaign exists, ask: "What should I test? Give me 1-3 user flows."

### Step 2: START THE APP

Before testing, the app needs to be running:

1. Check if a dev server is already running (try curl localhost:3000, 5173, 8080)
2. If not running, check package.json for start/dev scripts
3. Start it: `npm run dev` or equivalent, in background
4. Wait for the server to be ready (poll the health endpoint or main URL)
5. If the app won't start, report the error and stop. Don't test a broken app.

Track whether the agent started the server. If so, kill it on completion.

### Step 3: TEST

For each flow identified in Step 1, write and run a Playwright script:

```javascript
const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({ headless: true });
  const page = await browser.newPage();

  // Navigate
  await page.goto('http://localhost:3000');

  // Verify page loaded
  const title = await page.title();

  // Test interactions
  await page.click('button[data-testid="add-todo"]');
  await page.fill('input[name="title"]', 'Test todo');
  await page.click('button[type="submit"]');

  // Verify result
  const todoText = await page.textContent('.todo-item:last-child');

  // Screenshot for evidence
  await page.screenshot({ path: '.citadel/screenshots/qa-flow-1.png' });

  await browser.close();
})();
```

For each test:
- Navigate to the relevant page
- Perform the user action (click, fill, submit)
- Verify the expected outcome (element appears, text changes, navigation occurs)
- Take a screenshot as evidence
- Log: PASS or FAIL with description

### Step 4: REPORT

Write results to `.citadel/qa-report-{date}.md`:

From special-place-administrator/citadel_codex, MIT.

More from special-place-administrator/citadel_codex