test-casebook

A playbook that stops an AI from writing happy-path-only tests for your frontend.

Most "AI, write my tests" runs stop at a few green checks on the components that were easy to reach — permissions, edge cases, and refactor-fragile selectors left untested. test-casebook forces an agent to plan every case from the source before writing anything, drive tests through dedicated data-test-* attributes that stay stable across refactors, and enforce strict typing and a real coverage floor.

It's paired with env-attr-cleaner, which strips those data-test-* attributes from production builds — so the test hooks never ship. It's running in production today across several Xefi business units, on both Nuxt and React/Next.js codebases.

Quickstart

npx test-casebook init --force

# then, in Claude Code, opened on your project:
# invoke the `test-casebook` skill

That drops AGENTS.md, docs/, and .claude/ (skill + agents) into your project. AGENTS.md Step 1 reads package.json/composer.json and auto-detects the stack — no manual setup.

Supported stacks (auto-detected)

| Stack | Auto-detected | Dedicated guide | Cleaner (Part A) | |---|---|---|---| | Nuxt | ✅ | docs/testing-guide/README.md | ✅ env-attr-cleaner | | React / Next.js | ✅ | docs/testing-guide/react.md | ✅ env-attr-cleaner | | Vue (no Nuxt) | ✅ | follows AGENTS.md Step 3/5's per-framework equivalents | ✅ env-attr-cleaner | | Svelte | ✅ | same | ✅ env-attr-cleaner | | Astro | ✅ | same — uses Astro's Container API | ✅ env-attr-cleaner | | Bun (runtime build) | ✅ | — | ✅ env-attr-cleaner-bun | | Laravel / Livewire / Blade / Folio | ✅ | docs/testing-guide/laravel.md | N/A — Blade-directive alternative in the guide | | Angular | ❌ Not supported — env-attr-cleaner can't strip Angular templates; AGENTS.md stops immediately on detecting @angular/core | — | ❌ |

Nuxt, React and Laravel additionally ship a full cookbook with copy-paste snippets; the other JS stacks follow the same playbook with adaptations spelled out directly in AGENTS.md.

$ php artisan test
...
Tests:    28 passed (72 assertions)
Duration: 4.12s

Full walkthrough, including the permission-matrix (roles + a private article) it was run against, in docs/testing-guide/laravel.md.

Get involved

Contributions are very welcome — this doctrine only gets sharper by running into real projects. No permission or big change needed: a one-line fix, a missing case, a new guide all count — see CONTRIBUTING.md.

Prior art

Stripping test attributes at build time isn't new — babel-plugin-jsx-remove-data-test-id is the closest thing to a de facto standard (React/Babel only), and smaller Vite-plugin variants exist for Vue and Svelte individually. What env-attr-cleaner adds is breadth: one tool across Nuxt/Vue/React/Next.js/Svelte/Astro/Bun and Vite/Rollup/Webpack/esbuild, instead of picking a new plugin per framework/bundler pair.

Core idea

Write dedicated data-test-* attributes for testing. The same selectors drive unit, integration and E2E tests, stay out of production, and stay stable across refactors because they're decoupled from style, structure and text.

The playbook's job is to make coverage exhaustive instead of happy-path: plan from reading the source, enumerate every case (props, branches, states, interactions, guards, permissions), and verify each one.

What's inside

• AGENTS.md — the playbook: detect the stack, wire the cleaner if applicable, plan every case in task-test.md, execute block by block with a reviewer, enforce strict typing and coverage, verify. Includes the permission matrix and anti-mock-drift rules.
• .claude/skills/test-task/ (project manager, upstream) — turns a story into a shared test-task.md: interviews to close gaps, reads the real permission model.
• .claude/skills/test-casebook/ + .claude/agents/{test-writer,test-reviewer} (developer, downstream) — executes that contract: plan per unit, write, review, verify.
• docs/strategy.md — why data-test-* over CSS/structural/text selectors.
• docs/conventions.md — naming rules for data-test-id/data-test-class.
• docs/testing-guide/ — ready-to-use scenario snippets, one guide per stack.

The flow

Story → test-task skill (PM) writes one test-task.md → given to the front and back developer → each runs the test-casebook skill on their side, deriving expected outcomes from that same test-task.md. One contract, two implementations; permission cases assert both layers, so a front/back divergence surfaces immediately.

How it's consumed

Three channels, one source of truth (this repo's AGENTS.md + docs):

• Claude Code skill + sub-agents — the primary path, shown in Quickstart.
• npx scaffolder — npx test-casebook init [--force], which also checks the npm registry for a newer published version and prints an update hint if one exists (silent, non-blocking, if offline).
• Docs directly — the guides in docs/.

Releases are automated: merging a PR to main that changes package.json's version triggers CI to publish that version to npm (see CONTRIBUTING.md).

Same doctrine, other stacks

Same method — plan first, exhaustive not happy-path, permission matrix dense on refused cases, independent review gate, enforced coverage floor — ported to each ecosystem's own tooling:

• test-casebook-back-php — PHP backends
• test-casebook-back-js — Node/TypeScript backends

License

MIT