---

name: testing description: "Testing: TDD, E2E, preferred patterns, test-value audits, verification, agent testing." user-invocable: false allowed-tools:

• Read
• Write
• Bash
• Grep
• Glob
• Edit
• Task
• Skill
• Agent agent: testing-automation-engineer routing: not_for: "code review (use review), linting (use code-quality)" triggers:
  • "TDD"
  • "test first"
  • "red green refactor"
  • "write tests first"
  • "test-driven"
  • "tests before code"
  • "flaky test"
  • "brittle test"
  • "test smell"
  • "test quality issue"
  • "slow tests"
  • "over-mocking"
  • "test audit"
  • "audit tests"
  • "low-value tests"
  • "prune tests"
  • "test bloat"
  • "delete useless tests"
  • "test agents"
  • "agent testing"
  • "subagent testing"
  • "run vitest"
  • "JavaScript tests"
  • "TypeScript tests"
  • "playwright"
  • "E2E test"
  • "end-to-end"
  • "browser test"
  • "verify completion"
  • "run tests"
  • "final verification" category: testing pairs_with:
  • review
  • code-quality
  • workflow

---

Testing

Seven modes. Match the request to one mode and follow its section. Read repository CLAUDE.md first -- project conventions override defaults here.

Mode Selection

| Request matches | Go to | |---|---| | Write tests first, TDD, red-green-refactor | TDD | | Flaky, brittle, test smell, over-mocking, slow tests | Pattern Quality | | Audit or prune low-value, duplicate, or implementation-coupled tests | Test Audit | | Test an agent, subagent testing, validate agent | Agent Testing | | Run vitest, JavaScript/TypeScript tests | Vitest Runner | | Playwright, E2E, end-to-end, browser test | E2E (Playwright) | | Verify completion, final check, defense in depth | Verification |

---

TDD

RED-GREEN-REFACTOR cycle with strict phase gates. Each feature gets its own cycle. Do not batch multiple features into one cycle.

Phase 1: RED -- Write a Failing Test

Write a test describing desired behavior before implementation exists. Use Arrange-Act-Assert, descriptive names, one concept per test. Run the test and show full output.

Every new or changed test, in any mode, must first pass the authoring gate in references/audit-test-value.md.

Gate -- proceed only when all true:

• Test file created and saved
• Test executed
• Output shows FAILURE (not syntax/import error)
• Failure indicates missing implementation

If test passes before implementation: assertions are too weak, or the feature already exists. If test fails for wrong reason (syntax, import, setup): fix those first, then re-run until it fails for the right reason.

Phase 2: GREEN -- Minimum Implementation

Write ONLY enough code to make the failing test pass. No extra features. Hardcoded values are acceptable initially. Run the test and the full suite; show complete output.

Gate -- proceed only when all true:

• New test passes
• Full suite executed
• No other tests broken

Phase 3: REFACTOR

Improve code quality without changing behavior. Establish a green baseline, refactor incrementally, run tests after every step. Test behavior, not internals.

Gate -- proceed only when all true:

• Full suite passes
• Code quality evaluated

Phase 4: Commit

Commit test and implementation as an atomic unit. Run the full suite first.

TDD Error Recovery

| Symptom | Cause | Fix | |---|---|---| | Test passes in RED phase | Weak assertions or feature exists | Strengthen assertions; check for existing implementation | | Wrong failure reason | Setup incomplete, missing deps | Fix syntax/imports first, re-run | | Tests green but feature broken | Tests miss actual usage | Add integration tests; test with real data | | Refactoring breaks tests | Tests coupled to internals | Test behavior not implementation; refactor in smaller steps |

---

Pattern Quality

Identify and fix testing mistakes across unit, integration, and E2E suites. Test behavior, be reliable, run fast, fail for the right reasons.

Phase 1: SCAN

Locate test files (*_test.go, test_*.py, *.test.ts, *.spec.js). Scan for these 10 failure modes:

| # | Pattern | Detection Signal | |---|---|---| | 1 | Testing implementation details | Asserts on private fields, spy on private methods | | 2 | Over-mocking / brittle selectors | Mock setup > 50% of test code, CSS nth-child | | 3 | Order-dependent tests | Shared mutable state, numbered test names | | 4 | Incomplete assertions | != nil, > 0, toBeTruthy(), no value checks | | 5 | Over-specification | Exact timestamps, hardcoded IDs, asserting defaults | | 6 | Ignored failures | @skip, .skip, xit, empty catch, _ = err | | 7 | Poor naming | testFunc2, it('works'), it('handles case') | | 8 | Missing edge cases | Only happy path, no empty/null/boundary/error tests | | 9 | Slow test suites | Full DB reset per test, no parallelization | | 10 | Flaky tests | sleep(), time.Sleep(), unsynchronized goroutines |

Document each finding with file:line, severity, issue, and impact.

Gate: At least one quality issue identified with file:line reference.

Phase 2: PRIORITIZE

1. HIGH -- Flaky, order-dependent, ignored failures (erode trust)
2. MEDIUM -- Over-mocking, incomplete assertions, missing edges (false confidence)
3. LOW -- Poor naming, over-specification, slow suites (maintenance burden)

Fix one pattern at a time. Preserve test intent. Prevent over-engineering.

Gate: Findings ranked. User agrees on fix scope.

Phase 3: FIX

For each issue (highest priority first): show current code, show fixed code, apply fix, run tests. Guide toward behavior testing:

• Asserts on private fields -> test the public behavior those fields enable
• Spies on _getUser() -> test what happens when a user exists or not
• Checks exact regex -> test that validation succeeds/fails for representative inputs

Run the specific fixed test first, then the full file or package. If a fix breaks a previously-passing test, investigate before proceeding.

Gate: Each fix verified. Tests pass after each change.

Phase 4: VERIFY

Run full suite. Verify flaky tests are now deterministic (run 3x). Confirm no no tests were accidentally removed or disabled. Report: bad patterns fixed, files modified, tests affected, suite status.

Gate: Full suite passes. Summary delivered.

Pattern Error Recovery

| Problem | Fix | |---|---| | Cannot determine if pattern is a quality issue | Check comments, consider test layer, flag MEDIUM with trade-offs | | Fix changes test behavior | Identify original intent, write correct assertion, note as separate finding | | Suite has hundreds of quality issues | Fix HIGH severity first, recommend TDD going forward, suggest fix-on-touch |

---

Test Audit

Find and remove tests that do not earn their maintenance cost, and the test-only production seams they keep alive. Load references/audit-test-value.md and follow it; it holds the authoring gate, junk patterns, retention bar, evidence fields, validation, and handoff.

Use Pattern Quality to fix a test that guards real behavior badly. Use Test Audit to decide whether a test should exist at all.

| Scope | Sub-mode | |---|---| | Writing or changing a test | Authoring gate | | Focused sweep of a few candidates | Audit | | Every test one subsystem owns | Campaign |

Gate: Every deletion has all candidate evidence fields recorded. Owner and full suites pass. Production and test LOC reported separately.

---

Agent Testing

TDD methodology applied to agent development. Test what the agent DOES, not what the prompt SAYS. Each test runs in a fresh subagent to avoid context pollution.

Minimum Test Counts

| Agent Type | Min Tests | Coverage | |---|---|---| | Reviewer | 6 | 2 real issues, 2 clean, 1 edge, 1 ambiguous | | Implementation | 5 | 2 typical, 1 complex, 1 minimal, 1 error | | Analysis | 4 | 2 standard, 1 edge, 1 malformed | | Routing/orchestration | 4 | 2 correct route, 1 ambiguous, 1 invalid |

No agent is simple enough to skip testing.

Phase 1: RED -- Observe Current Behavior

Read the agent file and referenced skills. Extract testable claims (inputs, output structure, routing triggers, error conditions). Write a test plan to a file. Dispatch subagent via Task tool with test inputs. Capture results verbatim. Identify failure patterns.

Gate: All cases executed. Outputs captured. Failures documented.

Phase 2: GREEN -- Fix Agent Definition

Prioritize failures by severity. Make one fix at a time. Re-run ALL test cases after each fix. If a fix causes regression, revert and try a different approach.

Gate: All cases pass. No regressions.

Phase 3: REFACTOR -- Edge Cases and Robustness

Add edge case tests (empty, large, unusual, ambiguous inputs). Run consistency tests (same input 3x; outputs should have same structure and key findings). Run full regression suite.

Gate: Edge cases handled. Consistency verified. Full suite green.

---

Vitest Runner

Run existing Vitest tests and report results. A check-only request does not authorize changing tests, assertions, dependencies, or configuration.

Check package.json, vitest.config.*, and vite.config.* to confirm Vitest. Use the installed project version; avoid implicit npx downloads. If Vitest is unavailable, report setup needed rather than installing it. Always use run; bare vitest enters watch mode.

| Scope | Command | |---|---| | Full suite | npx vitest run --reporter=verbose 2>&1 | | File or directory | npx vitest run path/to/test.ts 2>&1 | | Test-name pattern | npx vitest run -t "pattern" 2>&1 | | Coverage | npx vitest run --coverage 2>&1 |

Capture exit code and full output. Report pass/fail, scope, counts, duration. For failures: retain file, test name, assertion diff, relevant stack. Nonzero exit is failure; partial output is not a passing run.

Vitest Recovery

| Problem | Fix | |---|---| | Vitest missing / no node_modules | npm install or npm install -D vitest | | No test files found | Check naming (*.test.ts, *.spec.ts) and include/exclude globs | | Missing DOM environment | Check for jsdom/happy-dom in config; suggest devDependency | | Out of memory | Batch by directory, use --pool=forks or --shard=1/N | | Failing assertions | Report mismatch; if fixing authorized, determine whether implementation or test is wrong |

---

E2E (Playwright)

Playwright-based E2E testing: Scaffold, Build, Run, Validate. Each phase produces an artifact and must pass its gate.

Phase 1: SCAFFOLD

1. Verify @playwright/test installed: npx playwright --version. If missing: npm install -D @playwright/test && npx playwright install.
2. Create directory structure: tests/e2e/{auth,features,api}/, pages/, artifacts/{screenshots,traces,videos}/.
3. Write playwright.config.ts. Bake in failure diagnostics: screenshot: 'only-on-failure', trace: 'on-first-retry', video: 'retain-on-failure'. CI retries: retries: process.env.CI ? 2 : 0.
4. Verify: npx tsc --noEmit.

Gate: playwright.config.ts exists AND tests/e2e/ exists.

Phase 2: BUILD

Write POM classes in pages/ for each feature area. All locators use data-testid via page.getByTestId(). No inline locators in spec files. Write spec files in tests/e2e/<area>/. Verify: npx tsc --noEmit.

Gate: At least one .spec.ts under tests/e2e/ AND npx tsc --noEmit exits 0.

Phase 3: RUN

1. Ensure app is running (or document BASE_URL).
2. Run: npx playwright test.
3. If failures, isolate with --repeat-each=5 to distinguish flaky from broken.
4. Quarantine confirmed flaky tests with test.fixme() and a tracking TODO. Never delete a failing test. Use test.skip() only for environment guards.

Gate: playwright-results.json exists and parses as valid JSON.

Phase 4: VALIDATE

1. Deterministic checks first: parse JSON, extract