Skip to content

About

Skill with instructions for writing high-quality tests across technology stacks (Claude Code / Codex)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

test-magic

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.

Supported stacks

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"

What it does (Next.js + Playwright)

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 why
  • docs/agents-reference/testing.md — details, examples, route lists
  • one @.agents/testing.md import in the root CLAUDE.md / AGENTS.md (nothing else)

Existing testing instructions are extended, not duplicated. The ten rule sections:

  1. Tests are mandatory — narrowest layer; e2e when boundaries or user-visible behavior change; not done until green.
  2. Layout — everything under tests/ (tests/lib/, tests/e2e/<feature>/); shared fixtures.ts/test-steps.ts one level up.
  3. Running — scoped commands per layer; full suite only on request; fix to green.
  4. Clean new files — prettier --check, eslint --max-warnings 0, typecheck; no inline disables.
  5. Visible Playwright steps — testSetup, userAction, userClick, userFill, checkThat (PLAYWRIGHT_VERBOSE_STEPS).
  6. E2E philosophy — full stack, real DB; only third parties are mocked.
  7. Third-party policy — page.route, aborted analytics in mockCommonApis, env-key gates, fake servers behind E2E_TEST_MODE=true, filter by unique email.
  8. Test data — dev-only helpers gated by a NODE_ENV allow-list; unique data per test.
  9. Stability — parallel, raised expect.timeout, CI-only retries, readiness gate, no waitForTimeout, role-based selectors, scroll-sentinel test.
  10. 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.

Versioning

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.

Installation

Claude Code — recommended

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.

Updating

claude plugin update test-magic@test-magic-marketplace

Or 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.

Manual installation (fallback)

git clone https://github.com/purple-magic/test-magic.git
cp -R test-magic/skills/test-magic ~/.claude/skills/test-magic

Update a manual install:

cd test-magic && git pull
rm -rf ~/.claude/skills/test-magic
cp -R skills/test-magic ~/.claude/skills/test-magic

Codex

Codex 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-magic

Update: git pull, then rm -rf ~/.codex/skills/test-magic && cp -R skills/test-magic ~/.codex/skills/test-magic.

Usage

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"

Development

These steps are for people editing this repository.

Sync skill locally after changes

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-magic

Validate

bash skills/test-magic/tests/fake-outbox-server/run_tests.sh
claude plugin validate . --strict

Adding a new recipe

  1. Create skills/test-magic/agents/recipes/<stack>.md with the same shape as nextjs-playwright.md (investigate → write short rules + reference → wire root file → report with [ADD] list)
  2. Create skills/test-magic/templates/<stack>/
  3. Add the detection signal to the table in SKILL.md (Step 1) and to the supported-stacks table above
  4. Keep the Rails redirect (Step 0) untouched
  5. Bump MINOR in VERSION, add a CHANGELOG.md entry
  6. Sync locally to test

License

MIT

About

Skill with instructions for writing high-quality tests across technology stacks (Claude Code / Codex)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages