ccqa

library0.6.0jsnpmunverified

ccqa is a browser test recorder powered by Claude Code and agent-browser that turns YAML test specs into deterministic, replayable vitest scripts without requiring an LLM during test execution. Version 0.6.0, actively developed on GitHub. Key differentiators: leverages existing Claude subscription (no extra API key for tracing), generates vitest-compatible scripts for CI, supports drift analysis via Claude on test failures, and uses agent-browser for browser automation. Requires Node.js 20+.

testing

npm install ccqa

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CCQA

ccqa

testingjavascriptv0.6.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Shows full workflow: write a spec in YAML, trace browser actions with Claude, generate deterministic test script, run in CI without LLM.

# Write a spec cat > .ccqa/features/tasks/test-cases/create-and-complete/spec.yaml << 'EOF' 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" EOF # Trace (Claude drives browser) npx ccqa trace tasks/create-and-complete # Generate test script npx ccqa generate tasks/create-and-complete # Run deterministically in CI npx ccqa run tasks/create-and-complete # Run with drift analysis on failure (requires ANTHROPIC_API_KEY or local Claude login) export APP_URL=http://localhost:3000 npx ccqa run tasks/create-and-complete --drift --format github

Debug

Known issues

gotchaagent-browser is a peer dependency and must be installed separately

fix

Run `pnpm add -D agent-browser` (or npm/yarn equivalent)

affects: >=0.0.0

gotchaSpecs reference URLs via `${ENV_VAR}` that must be set at trace and run time

fix

Ensure all referenced environment variables (e.g., APP_URL) are set in your shell or .env file

affects: >=0.0.0

breakingRequires Node.js 20+; older versions will fail

fix

Upgrade Node.js to version 20 or later

affects: >=0.0.0

deprecatedThe `--model` flag accepts model names like `sonnet`, `opus`, `haiku` but these are aliases that may change in future versions

fix

Use full model IDs via `--model claude-sonnet-4-20250514` (or current model ID) to avoid breakage

affects: >=0.0.0

gotchaInteractive `ccqa trace` requires a local Claude Code login; CI drift analysis additionally needs ANTHROPIC_API_KEY

fix

Log in via `claude login` locally; set ANTHROPIC_API_KEY in CI environment

affects: >=0.0.0

Errors

Common errors & fixes

ccqa: command not found

ccqa is not installed globally or not in PATH

fix

Run `npx ccqa` or install with `pnpm add -D ccqa` and use `pnpm ccqa`

Error: Cannot find module 'agent-browser'

Missing peer dependency agent-browser

fix

Install agent-browser: `pnpm add -D agent-browser`

Error: Spec file not found: .ccqa/features/tasks/test-cases/create-and-complete/spec.yaml

The spec path alias doesn't match the filesystem structure

fix

Ensure the spec file exists at .ccqa/features/<feature>/test-cases/<spec>/spec.yaml (e.g., for `ccqa trace tasks/create-and-complete` the file must be at .ccqa/features/tasks/test-cases/create-and-complete/spec.yaml)

Error: ENV_VAR not set: APP_URL

An environment variable referenced in the spec is undefined

fix

Set the variable before running: `export APP_URL=http://localhost:3000`

Error: ESM Only. CJS require() is not supported.

ccqa is an ESM-only package, cannot be imported with require()

fix

Use `import` syntax or run in an ESM context (add `"type": "module"` to package.json)

Upgrade

Version history

0.6.0latest on npm

Audit

Dependencies

agent-browserrequiredPeer dependency required for browser automation

vitestrequiredPeer dependency required for running generated tests

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/shibukazu/ccqa ↗

packageccqa ↗

homepagehttps://github.com/shibukazu/ccqa#readme ↗