A Claude Code / Codex skill that writes testing instructions for AI agents in your project — short mandatory rules plus a detailed reference — and proposes the minimal test infrastructure those rules rely on. One recipe per technology stack.
Rails projects: all testing instructions live in tramway-skill (
skills/tramway-skill/agents/testing.md). test-magic detects Rails (per unit) and redirects there; it writes nothing for Rails.
| Stack | Recipe | Status |
|---|---|---|
| Next.js (App Router) + React + TypeScript, Prisma/Postgres, Playwright, tsx/vitest, prettier + eslint + tsc | agents/recipes/nextjs-playwright.md |
ready |
| Ruby on Rails | — | redirects to tramway-skill |
| Other stacks | — | not yet; see "Adding a new recipe" |
Investigates the project first (package scripts, Playwright/vitest configs, tests/ tree, CI workflows, how the app and DB run, third-party services) and adapts to what it finds — nothing is invented. Anything missing is marked [ADD] with a minimal implementation proposed. It then writes:
.agents/testing.md— short hard rules, each with a one-line whydocs/agents-reference/testing.md— details, examples, route lists- one
@.agents/testing.mdimport in the rootCLAUDE.md/AGENTS.md(nothing else)
Existing testing instructions are extended, not duplicated. The ten rule sections:
- Tests are mandatory — narrowest layer; e2e when boundaries or user-visible behavior change; not done until green.
- Layout — everything under
tests/(tests/lib/,tests/e2e/<feature>/); sharedfixtures.ts/test-steps.tsone level up. - Running — scoped commands per layer; full suite only on request; fix to green.
- Clean new files —
prettier --check,eslint --max-warnings 0, typecheck; no inline disables. - Visible Playwright steps —
testSetup,userAction,userClick,userFill,checkThat(PLAYWRIGHT_VERBOSE_STEPS). - E2E philosophy — full stack, real DB; only third parties are mocked.
- Third-party policy —
page.route, aborted analytics inmockCommonApis, env-key gates, fake servers behindE2E_TEST_MODE=true, filter by unique email. - Test data — dev-only helpers gated by a
NODE_ENVallow-list; unique data per test. - Stability — parallel, raised
expect.timeout, CI-only retries, readiness gate, nowaitForTimeout, role-based selectors, scroll-sentinel test. - Pre-handoff checklist.
Templates (skills/test-magic/templates/nextjs-playwright/): rules and reference skeletons, test-steps.ts, fixtures.ts, playwright.config.ts, fake outbox server + helpers, lib/test-mode.ts, readiness gate, optional network blocker, infinite-scroll reference spec.
skills/test-magic/VERSION is the human-readable semantic version of the skill's content, bumped on every change per CHANGELOG.md; the skill prints test-magic v<version> when loaded. It is not the plugin update identity — Claude Code's marketplace tracks this repository's git history, so claude plugin update always pulls the latest commit.
This repository is both the source of truth and a Claude Code plugin marketplace. Add the marketplace once:
/plugin marketplace add purple-magic/test-magic
Then install the plugin:
/plugin install test-magic@test-magic-marketplace
No .claude/settings.json edit needed; the plugin registers the skill automatically.
claude plugin update test-magic@test-magic-marketplaceOr turn on auto-update for the marketplace in Claude Code's plugin UI (/plugin → marketplace settings). Manual (cp -R) installs do not auto-update — re-sync them by hand.
git clone https://github.com/purple-magic/test-magic.git
cp -R test-magic/skills/test-magic ~/.claude/skills/test-magicUpdate a manual install:
cd test-magic && git pull
rm -rf ~/.claude/skills/test-magic
cp -R skills/test-magic ~/.claude/skills/test-magicCodex has no plugin marketplace, so installation is manual:
git clone https://github.com/purple-magic/test-magic.git
cp -R test-magic/skills/test-magic ~/.codex/skills/test-magicUpdate: git pull, then rm -rf ~/.codex/skills/test-magic && cp -R skills/test-magic ~/.codex/skills/test-magic.
In a project directory:
/test-magic
Or just describe what you want:
"Write testing instructions for this project" "Set up Playwright e2e rules for agents"
These steps are for people editing this repository.
rm -rf ~/.claude/skills/test-magic && cp -R ./skills/test-magic ~/.claude/skills/test-magic
rm -rf ~/.codex/skills/test-magic && cp -R ./skills/test-magic ~/.codex/skills/test-magicbash skills/test-magic/tests/fake-outbox-server/run_tests.sh
claude plugin validate . --strict- Create
skills/test-magic/agents/recipes/<stack>.mdwith the same shape asnextjs-playwright.md(investigate → write short rules + reference → wire root file → report with[ADD]list) - Create
skills/test-magic/templates/<stack>/ - Add the detection signal to the table in
SKILL.md(Step 1) and to the supported-stacks table above - Keep the Rails redirect (Step 0) untouched
- Bump
MINORinVERSION, add aCHANGELOG.mdentry - Sync locally to test
MIT