ccqa 0.3.10 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 **Your Claude subscription already includes a QA engineer.**
 
-ccqa turns Claude Code into a browser test recorder. Write a spec in Markdown, run `ccqa trace`, and Claude drives your app via [agent-browser](https://github.com/vercel-labs/agent-browser). Every action is recorded and compiled into a deterministic test script you can run in CI. No extra API key. Just `claude`.
+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](https://github.com/vercel-labs/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](./docs/README.ja.md)
 
@@ -10,7 +10,7 @@ ccqa turns Claude Code into a browser test recorder. Write a spec in Markdown, r
 
 ```mermaid
 flowchart LR
-    A["Write spec\n(test-spec.md)"] --> B["ccqa trace\n(Claude drives browser)"]
+    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)"]
 ```
@@ -29,24 +29,22 @@ Requires Node.js **20+**. [agent-browser](https://github.com/vercel-labs/agent-b
 
 **1. Write a spec** — by hand, or interactively with [`ccqa draft`](./docs/draft.md)
 
-```markdown
-<!-- .ccqa/features/tasks/test-cases/create-and-complete/test-spec.md -->
----
+```yaml
+# .ccqa/features/tasks/test-cases/create-and-complete/spec.yaml
 title: Create a task and mark it complete
-baseUrl: http://localhost:3000
----
 
-## Steps
+steps:
+  - instruction: |
+      Open ${APP_URL}/login. Fill in email and password, submit the form.
+    expected: Redirected to /dashboard, user avatar visible in the header
 
-### Step 1: Log in
-- **Instruction**: Fill in email and password, submit the form
-- **Expected**: Redirected to /dashboard, user avatar visible in the header
-
-### Step 2: Create a new task
-- **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"
+  - 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
 
 ```bash
@@ -65,12 +63,18 @@ ccqa generate tasks/create-and-complete
 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.
+
+```bash
+ccqa run tasks/create-and-complete --drift --format github
+```
+
 ## Features
 
 | Feature | Docs |
 |---|---|
 | Write specs interactively with Claude | [Draft](./docs/draft.md) |
-| Reuse login and other setup steps | [Setup Specs](./docs/setup-specs.md) |
+| Reuse login and other shared step sequences | [Blocks](./docs/blocks.md) |
 | Assertion helper functions | [Assertions](./docs/assertions.md) |
 | Auto-fix failing tests | [Auto-fix](./docs/auto-fix.md) |
 | Detect spec/code drift in CI | [Drift](./docs/drift.md) |
@@ -79,15 +83,13 @@ ccqa run tasks/create-and-complete
 
 ```
 ccqa draft [feature/spec]          Co-author a test spec with Claude
-ccqa drift [feature/spec]          Check spec ↔ codebase drift (CI-friendly)
-ccqa trace <feature/spec>          Record browser actions
+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
-ccqa trace-setup <name>            Record actions for a setup spec
-ccqa generate-setup <name>         Generate and validate setup test script
+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; `ccqa drift` additionally honors `ANTHROPIC_API_KEY` for CI.
+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>/`.
 
@@ -95,15 +97,14 @@ All Claude-driven commands accept `-m, --model <name>` (alias `sonnet` | `opus`
 
 ```
 .ccqa/
-  setups/
+  blocks/
     login/
-      setup-spec.md              # Setup definition with placeholders
-      test.spec.ts               # Generated setup script
+      spec.yaml                  # Reusable block (params + steps)
   features/
     tasks/
       test-cases/
         create-and-complete/
-          test-spec.md           # Test definition
+          spec.yaml              # Test definition
           actions.json           # Recorded actions from trace
           test.spec.ts           # Generated test script
 ```