ccqa

Your Claude subscription already includes a QA engineer.

ccqa turns Claude Code into a browser test recorder. Write a spec in YAML, run ccqa trace, and Claude drives your app via agent-browser. Every action is recorded and compiled into a deterministic test script you can run in CI. No extra API key. Just claude.

日本語版 README

How it works

flowchart LR
    A["Write spec\n(spec.yaml)"] --> B["ccqa trace\n(Claude drives browser)"]
    B --> C["ccqa generate\n(LLM → test script)"]
    C --> D["ccqa run\n(deterministic replay)"]

trace invokes Claude Code with your spec. Claude drives the browser step by step, recording every action as structured data. generate compiles that data into a vitest-compatible script. run replays it deterministically — no LLM involved.

Install

pnpm add -D ccqa vitest agent-browser

Requires Node.js 20+. agent-browser is a peer dependency.

Quick start

1. Write a spec — by hand, or interactively with ccqa draft

# .ccqa/features/tasks/test-cases/create-and-complete/spec.yaml
title: Create a task and mark it complete

steps:
  - instruction: |
      Open ${APP_URL}/login. Fill in email and password, submit the form.
    expected: Redirected to /dashboard, user avatar visible in the header

  - instruction: |
      Click "New Task", fill in the title "Fix login bug", set priority to High, save.
    expected: Task appears in the task list with status "Open"

URLs live inside instruction strings — either verbatim or via ${ENV_VAR} references for environment-specific values.

2. Trace — Claude drives the browser and records every action

ccqa trace tasks/create-and-complete

3. Generate — convert recorded actions into a replayable test

ccqa generate tasks/create-and-complete

4. Run — replay deterministically, no LLM involved

ccqa run tasks/create-and-complete

In CI you can opt in to drift analysis on test failures by passing --drift — Claude will explain the failure by comparing the spec against the current codebase. Requires ANTHROPIC_API_KEY or a local Claude login.

ccqa run tasks/create-and-complete --drift --format github

Features

| Feature | Docs | |---|---| | Write specs interactively with Claude | Draft | | Reuse login and other shared step sequences | Blocks | | Assertion helper functions | Assertions | | Auto-fix failing tests | Auto-fix | | Detect spec/code drift in CI | Drift |

Commands

ccqa draft [feature/spec]          Co-author a test spec with Claude
ccqa trace <feature/spec>          Record browser actions for a spec (inlines any included blocks)
ccqa generate <feature/spec>       Generate test script from recorded actions
ccqa run [feature/spec]            Execute generated test scripts (add --drift to analyze failures)
ccqa drift [feature/spec]          Standalone spec ↔ codebase drift audit (for scheduled jobs)

All Claude-driven commands accept -m, --model <name> (alias sonnet | opus | haiku, or a full model ID). The flag overrides CCQA_MODEL; when both are unset, the Claude Code CLI default is used. Interactive commands authenticate via your local Claude Code login; commands that talk to Claude in CI (ccqa run --drift, ccqa drift) additionally honor ANTHROPIC_API_KEY.

<feature/spec> is a 2-segment alias for the on-disk path .ccqa/features/<feature>/test-cases/<spec>/.

File structure

.ccqa/
  blocks/
    login/
      spec.yaml                  # Reusable block (params + steps)
  features/
    tasks/
      test-cases/
        create-and-complete/
          spec.yaml              # Test definition
          actions.json           # Recorded actions from trace
          test.spec.ts           # Generated test script

License

MIT