Claude
Code
for QA.

The room you just walked into

QA is no longer the last step.
It is the first reader of every commit.

Where Claude Code sits in your stack.

Think of it as a terminal-native pair tester. It speaks files, shells, and — through MCP servers — browsers, Jira, Confluence, Notion, GitHub, calendars, even your inbox. Your job is to orchestrate, not to type.

Setup · macOS / Linux / WSL

Five lines. One terminal.

# 1. install
npm install -g @anthropic-ai/claude-code

# 2. cd into your QA repo
cd ~/work/qa-portfolio

# 3. start a session
claude

# 4. first thing you say
> /init  → writes CLAUDE.md

# 5. then ask anything
> read the repo and tell me what test framework we use

A session has four moving parts.

Most QA workflows live entirely inside Read + Bash + a Playwright MCP. You almost never need root, and you almost never need to leave the terminal.

Three ways to talk to the agent.

> run the login spec and screenshot
  every failure

> /init
> /review
> /compact

> !npx playwright test --headed
> !git status

Rule of thumb · use prompts for thinking, slash commands for workflows you repeat, and shell when you already know the exact command.

The complete cheat-sheet

Every slash command a QA touches.

QA-authored customs to add to .claude/commands/ · /flaky · /smoke · /bug-from-trace · /audit-locators · /gen-pom · /triage-failures · /quarantine · /report-run.

Read · Edit · Write · Bash.
Plus Grep · Glob · WebFetch. Everything else is sugar on top.

> open tests/login.spec.ts, find the assertion
  that checks the toast, and tighten it to verify
  both text and aria-role

// agent will:
  Read(tests/login.spec.ts)
  Edit(tests/login.spec.ts)  // 1 hunk
  Bash(npx playwright test login --reporter=line)
  // reports green ✓

What goes inside CLAUDE.md

Nine sections every QA repo needs.

Treat CLAUDE.md as your team's pair-programming contract. Write it once, every session obeys it. Run /init to scaffold, then edit by hand. Lives at the repo root.

# QA Conventions · qa-portfolio

## 1. Stack
- Framework: Playwright 1.49+
- Test runner: @playwright/test
- Lang: TypeScript strict
- Node: 20.x · pnpm

## 2. Folder layout
- tests/e2e/        · browser specs
- tests/api/        · APIRequestContext
- tests/fixtures/   · shared fixtures
- tests/pom/        · page objects
- tests/data/       · faker builders

## 3. Locators — STRICT
- Prefer getByRole, getByLabel, getByTestId.
- Never raw .locator('xpath=…').
- Brittle CSS must include a "// why" comment.

## 4. Waits
- No page.waitForTimeout.
- Use auto-wait + expect.poll only.
- Retry once, then quarantine.

## 5. Data
- Generate with @faker-js/faker.
- Never hard-code emails / phones / addresses.
- Test users: env-based, not committed.

## 6. Tagging
- @smoke @regression @flaky @wip
- CI runs @smoke on every PR.

## 7. Reporting
- HTML + JSON reporter on CI.
- Attach trace + screenshot on retry.

## 8. Commits
- Conventional Commits.
- No co-author trailers.
- No "🤖 Generated with…" footers.

## 9. Do / Don't
- DO: ask before deleting any spec.
- DO: run the impacted spec after every edit.
- DON'T: edit playwright.config without a plan.
- DON'T: bump deps without a separate PR.

Hire specialists, not generalists.

A subagent is a separate Claude session spawned for one bounded job. Its output is summarised back — your main context stays clean. Think of them as contractors who clock out when done. Note · the Plan subagent below is the planner specialist — distinct from Plan-mode (⇧Tab toggle, read-only thinking on the main agent).

> explore: find every place we
  click "Add to cart"

> plan: add a parallel visual
  regression suite for /pricing

> review the last 3 commits
  for race conditions

> e2e: add coverage for
  password-reset happy path

> tdd: implement the new
  promo-code validator

> security: review the new
  /auth/reset endpoint

Skills are playbooks Claude reads on demand.

A skill is a markdown file + optional scripts. When its trigger phrase fires, Claude loads it and follows the steps. Built-in skills cover testing, SEO, docs, presentations, even spreadsheets.

---
name: flake-hunter
description: Use when a Playwright spec
  fails intermittently. Locates the wait,
  rewrites it to expect-based polling,
  re-runs 10× to confirm stability.
---

## Steps
1. Read the failing spec.
2. Identify any waitForTimeout / sleep.
3. Replace with expect.poll().
4. Run npx playwright test --repeat-each=10.
5. Report flake-rate before vs after.

Build your own skill in under 10 minutes

A Skill is a markdown file with a recipe.

Frontmatter declares name + description. Body holds the procedure. Drop in ~/.claude/skills/<skill>/SKILL.md (global) or .claude/skills/<skill>/SKILL.md (repo-scoped). Claude auto-discovers and triggers on description match.

---
name: flake-hunter
description: Use when a Playwright spec
  fails intermittently or has any sleep /
  waitForTimeout / networkidle wait. Locates
  the bad wait, rewrites with expect.poll,
  re-runs 20x to confirm stability.
allowed-tools: Read, Edit, Bash, Grep, Glob
---

# Flake Hunter

## When to trigger
- Spec failed retry on CI.
- User says "this is flaky" / "intermittent".
- Code contains waitForTimeout / sleep.

## Procedure
1. Read the spec end-to-end.
2. Grep for: waitForTimeout, sleep,
   networkidle, hard delays.
3. For each hit, replace with expect.poll
   or explicit element wait.
4. Run npx playwright test {file} \
     --repeat-each=20 --workers=1.
5. Report flake-rate before vs after
   as a markdown table.
6. If still flaky > 5%, surface the
   most-likely locator candidate.

## Stop conditions
- 20/20 pass · report success.
- Any locator looks brittle · ask user.

> /skill-creator
// or, with the skill name:
> use skill-creator to build a
  skill called "locator-auditor"
  that scans tests/ for raw xpath
  and proposes role-based replacements

Hooks fire around tool calls.

A hook is a shell command the harness runs at a lifecycle event. Use them to auto-format on save, run a smoke test after every write, or block edits to main.

"hooks": {
  "PostToolUse": [
    {
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }]
    }
  ],
  "SessionStart": [{
    "hooks": [{
      "type": "command",
      "command": "echo '🧪 QA mode ready. Run /init.'"
    }]
  }]
}

MCP turns Claude into a browser, a Jira, a Notion, a Gmail.

Model Context Protocol is the USB-C of AI tools. A small server exposes verbs (navigate, click, createJiraIssue); Claude calls them like any other tool. For QA, the killer one is the Playwright MCP.

Demo · authoring a spec without typing locators

"Open saucedemo.com, log in, add a hoodie, screenshot the cart."

import { test, expect } from '@playwright/test';

test('guest adds backpack to cart', async ({ page }) => {
  await page.goto('https://www.saucedemo.com');
  await page.getByRole('textbox', { name: /user/i }).fill('standard_user');
  await page.getByRole('textbox', { name: /pass/i }).fill('secret_sauce');
  await page.getByRole('button', { name: 'Login' }).click();

  await page.getByRole('button', { name: /add to cart/i }).first().click();
  await page.getByRole('link', { name: /cart/i }).click();

  await expect(page.getByText('Sauce Labs Backpack')).toBeVisible();
});

API tests from a single curl.

Paste a curl, an OpenAPI URL, or a Postman export. The agent infers the contract and generates a fixture-based suite — schema validation, negative paths, auth variants, the lot.

> generate API tests for this endpoint with positive,
  negative, schema, and auth coverage. use playwright
  APIRequestContext, group by describe, log only on fail.

curl -X POST https://api.demo.dev/v1/users \
  -H 'Authorization: Bearer $T' \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","plan":"pro"}'

import { test, expect } from '@playwright/test';
import { z } from 'zod';

const User = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  plan: z.enum(['free', 'pro'])
});

test.describe('POST /v1/users', () => {
  test('creates a pro user', async ({ request }) => {
    const r = await request.post('/v1/users', {
      data: { email: '[email protected]', plan: 'pro' }
    });
    expect(r.status()).toBe(201);
    User.parse(await r.json());
  });

  test('rejects bad email', async ({ request }) => {
    const r = await request.post('/v1/users', {
      data: { email: 'not-an-email', plan: 'pro' }
    });
    expect(r.status()).toBe(400);
  });
});

From a screenshot to a filed bug.

> [screenshot.png attached]
  user reports the price chip overflows on
  the pricing card on mobile. reproduce in
  Chromium @ 390×844, capture a trace,
  attach screenshot, file a Jira bug in
  QA project with steps + expected/actual.

Drag a screenshot. Get tests.

Claude is multimodal — it reads images natively. Paste a Figma export, a customer's broken-UI screenshot, a flaky CI run's failure image. It identifies the component, locates it in code, proposes a fix or a test.

QA reviews code too. Now they have leverage.

tests/login.spec.ts:14: ⚠ medium:
  page.waitForTimeout(2000) introduces
  fixed sleep. fix: use expect.poll()
  on the dashboard heading.

src/auth/middleware.ts:42: 🔴 high:
  token comparison uses ==, vulnerable
  to timing attack. fix: crypto.timingSafeEqual.

playwright.config.ts:8: ◇ low:
  retries: 3 hides flakes. fix: cap at 1
  and quarantine instead.

Run Claude in your pipeline.

The same CLI is headless. Put it on GitHub Actions to auto-triage failing tests, generate PR review comments, or open a Jira when a smoke fails on main.

name: qa-bot
on: { pull_request: { types: [opened, synchronize] } }
jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Playwright
        run: npx playwright install --with-deps
      - name: Claude review + smoke
        env: { ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} }
        run: |
          npx -y @anthropic-ai/claude-code -p \
            "review this PR for QA risk, then run npx playwright test --grep @smoke
             and post a summary as a PR comment"

The -p flag (print/headless) gives you a one-shot run that exits with stdout. Perfect for cron, CI, or wrapping in your own scripts.

Plan first. Then let it loose.

large refactors · scary migrations ·
unfamiliar codebases · auth changes

> work on this in a worktree
  so my dev server keeps running

Together these are the two safety belts that let you run the agent autonomously on a long task while you go to lunch. Come back to a green PR.

Things that will save you a workday.

Make your own /commands

Your team. Your verbs.

Drop a markdown file in .claude/commands/. The filename becomes the command. Inside, write the prompt template — with placeholders. Share it via git so every QA in your team has the same playbook.

---
description: Hunt a flaky Playwright spec
argument-hint: [spec path]
---

You are debugging a flaky Playwright test.

Spec path: $ARGUMENTS

Do these in order:
1. Read the spec end-to-end.
2. Find every waitForTimeout, sleep,
   hard-coded delay, or networkidle wait.
3. Replace with expect.poll / explicit
   element wait.
4. Run it --repeat-each=20.
5. Report flake rate before vs after as a table.

Stop and ask if any locator looks brittle.

> /flaky tests/checkout.spec.ts

// claude expands the template, fills
// $ARGUMENTS, and runs the playbook

A QA day · before vs after.

Capstone · channels → skill → site → live URL

Your channels become your portfolio.

Step 1 · package yourself as a Skill

Aggregate 6 channels into one Skill.

The Skill becomes the single source of truth — every later prompt reads from it. Whenever you publish new content, you re-run the Skill and the site updates itself.

> create a new skill at .claude/skills/pramod-me/SKILL.md that
  packages me as data. Aggregate the following channels and produce
  a single data.json file in the same folder:

  - GitHub      → https://github.com/promode
  - LinkedIn    → https://www.linkedin.com/in/thetestingacademy
  - Blog        → https://scrolltest.com
  - YouTube     → https://www.youtube.com/@TheTestingAcademy
  - Instagram   → https://instagram.com/thetestingacademy
  - Medium      → https://medium.com/@thetestingacademy

  For each channel:
    1. Fetch the public page with WebFetch.
    2. Extract: handle, follower count if visible, top 6 items
       (repo / post / video / reel / article) with title, url, date.
    3. Pull a one-line bio + headshot URL where available.

  Then in SKILL.md frontmatter:
    name: pramod-me
    description: Use whenever the user needs current data about
      Pramod Dutta — bio, top repos, latest videos, recent talks,
      newest blog posts — to render a personal site or CV.
    allowed-tools: WebFetch, Read, Write, Bash

  Procedure section must:
    - Read data.json if <= 7 days old, otherwise refresh from sources.
    - Expose 5 helpers: getBio(), getTopRepos(), getLatestVideos(),
      getRecentPosts(), getTalks().
    - Cache to data.json. Pretty-print, ASCII-only, sorted by date desc.

  Verify by running the skill end-to-end and pasting a summary of
  the JSON it produced. Stop if any fetch fails — ask before retrying.

Step 2 · scaffold + content + style

One mega-prompt → full Next.js site.

> using the pramod-me skill, scaffold a Next.js 15 portfolio at
  ./qa-portfolio. Requirements:

  STACK
    - Next 15 (app router), TypeScript strict, Tailwind, MDX.
    - Inter (sans) + JetBrains Mono. Teal accent #1a7c79.
    - Light theme, doc-style layout. No purple gradients, no neon.

  ROUTES
    /              hero · headline · 3 chip tags · CTA "watch on YouTube"
    /work          top 6 repos pulled from getTopRepos()
    /talks         talks + slide decks
    /writing       latest blog + Medium articles via getRecentPosts()
    /videos        embed latest 6 YouTube videos via getLatestVideos()
    /social        LinkedIn / Instagram cards, last 3 posts each
    /contact       email · calendar embed · X / GitHub links

  COMPONENTS
    - <ChannelStrip /> at footer · 6 icons → 6 URLs.
    - <Card /> with title, date, source-badge, hover lift.
    - <Hero /> · pulls from getBio() at build time.

  DATA
    - Read from .claude/skills/pramod-me/data.json.
    - getStaticProps for /work /talks /writing /videos.
    - ISR every 24h on prod.

  SEO + META
    - OpenGraph image generated dynamically per route.
    - JSON-LD Person schema on home.
    - sitemap.xml + robots.txt.

  After scaffold finishes, run pnpm dev and confirm the
  home page renders without console errors. Take a screenshot at
  390x844 and 1440x900, save them as docs/hero-mobile.png
  and docs/hero-desktop.png. Then stop and report.

Step 4 · Vercel + Testing Academy upload

From localhost to thetestingacademy.com.

> deploy ./qa-portfolio to vercel.
  - run vercel login if needed (hand
    me the OTP prompt).
  - project name: pramod-qa
  - link to repo github.com/promode/qa-portfolio
  - env vars (encrypted):
      ANTHROPIC_API_KEY
      YOUTUBE_API_KEY
      MEDIUM_RSS_URL
  - run vercel --prod.
  - print preview + prod URLs.
  - run playwright suite against
    the PROD url; paste HTML report.
  - finally, attach custom domain:
      pramod.thetestingacademy.com

> publish this masterclass deck to
  app.thetestingacademy.com/masterclass
  /ClaudeCode.html.

  Steps:
  - rename index.html → ClaudeCode.html.
  - SSH/SFTP to the app host using
    creds from ~/.ssh/tta_deploy.
  - place under
    /var/www/app/masterclass/.
  - chmod 644, chown www-data.
  - reload nginx.
  - verify with curl + a Playwright
    snapshot of the live URL.
  - commit the deck source to
    github.com/thetestingacademy/
    masterclass-decks on a new
    branch · open a PR.

Live demo · fill the form → see your portfolio appear

Try the portfolio generator right here.

Fill in your channels. Click Generate. A complete single-file portfolio renders in the preview pane on the right. Download it, deploy it. This is the same HTML Claude Code produces in the capstone — only here it runs in your browser so you can preview it instantly.

After download · ship it to Vercel

# 1. install vercel cli once
npm i -g vercel

# 2. make a folder, drop the file in
mkdir my-qa-portfolio && cd my-qa-portfolio
mv ~/Downloads/portfolio.html ./index.html

# 3. push to vercel · prod
vercel --prod

# follow prompts → pick project name → done.
# you get a https URL in ~20s.

# add a custom domain
vercel domains add pramod.thetestingacademy.com
vercel alias set <deployment-url> pramod.thetestingacademy.com

# add CI: redeploy on every push
vercel link
git init && git add . && git commit -m "init"
gh repo create pramod-qa --public --source=. --push

# vercel auto-detects the repo and
# rebuilds on every push to main.

Don't do these. Ever.

The new QA toolbelt.

Where to go next.