Test-Driven Development

TDD is the fundamental practice. Every line of production code must be written in response to a failing test.

For how to write good tests, load the testing skill. This skill focuses on the TDD workflow/process. For mutation-aware test planning, load the mutation-testing skill and use its resources/mutator-rules.md resource as the source of truth.

---

RED-GREEN-MUTATE-KILL MUTANTS-REFACTOR Cycle

RED: Write Failing Test First

• NO production code until you have a failing test
• Test describes desired behavior, not implementation
• Test should fail for the right reason
• Before finalizing the test, scan the intended behavior against the mutator rules: boundaries, boolean combinations, equality, arithmetic identities, array/string operations, optional chaining, and side effects
• Add obvious missing cases immediately; use the harness's ask-question facility when the expected behavior is a product/domain judgment

GREEN: Minimum Code to Pass

• Write ONLY enough code to make the test pass
• Resist adding functionality not demanded by a test
• Faking it is legitimate: hardcode the return value if that passes, then triangulate — add a second test case that forces the real implementation. Generalize only when a test demands it

MUTATE: Verify Test Effectiveness

• Run mutation-testing skill against the changed code
• Produce a mutation testing report (killed/survived/score)
• This validates whether the RED-phase mutator scan caught the important gaps

KILL MUTANTS: Address Surviving Mutants

• Add or strengthen tests to kill surviving mutants
• Fix obvious gaps directly
• Ask the human with the harness's ask-question facility when a surviving mutant's value is ambiguous
• All tests pass after fixes

REFACTOR: Assess Improvements

• Assess AFTER mutation testing confirms test strength
• Load the refactoring skill before deciding what, if anything, to restructure
• Commit before refactoring
• All tests must pass after refactoring

---

TDD Evidence in Commit History

Default Expectation

Commit history should show clear RED → GREEN → MUTATE → KILL MUTANTS → REFACTOR progression.

Ideal progression:

commit abc123: test: add failing test for user authentication
commit def456: feat: implement user authentication to pass test
commit ghi789: test: strengthen boundary tests (mutation testing)
commit jkl012: refactor: extract validation logic for clarity

Rare Exceptions

TDD evidence may not be linearly visible in commits in these cases:

1. Multi-Session Work

• Feature spans multiple development sessions
• Work done with TDD in each session
• Commits organized for PR clarity rather than strict TDD phases
• Evidence: Tests exist, all passing, implementation matches test requirements

2. Context Continuation

• Resuming from previous work
• Original RED phase done in previous session/commit
• Current work continues from that point
• Evidence: Reference to RED commit in PR description

3. Refactoring Commits

• Large refactors after GREEN + MUTATE + KILL MUTANTS
• Multiple small refactors combined into single commit
• All tests remained green throughout
• Evidence: Commit message notes "refactor only, no behavior change"

Documenting Exceptions in PRs

When exception applies, document in PR description:

## TDD Evidence

RED phase: commit c925187 (added failing tests for shopping cart)
GREEN phase: commits 5e0055b, 9a246d0 (implementation + bug fixes)
MUTATE + KILL MUTANTS: commit 7b8c9d0 (strengthened boundary tests)
REFACTOR: commit 11dbd1a (test isolation improvements)

Test Evidence:
✅ 4/4 tests passing (7.7s with 4 workers)

Important: Exception is for EVIDENCE presentation, not TDD practice. TDD process must still be followed - these are cases where commit history doesn't perfectly reflect the process that was actually followed.

---

Coverage Verification - CRITICAL

NEVER Trust Coverage Claims Without Verification

Always run coverage yourself before approving PRs.

Verification Process

Before approving any PR claiming "100% coverage":

1. Check out the branch

   git checkout feature-branch
   

2. Run coverage verification (adapt to the project's package manager and layout):

   pnpm test:coverage
   # OR
   pnpm exec vitest run --coverage
   

3. Verify ALL metrics hit 100%:

   • Lines: 100% ✅
   • Statements: 100% ✅
   • Branches: 100% ✅
   • Functions: 100% ✅

4. Check that tests are behavior-driven (not testing implementation details)

For anti-patterns that create fake coverage (coverage theater), see the testing skill.

Reading Coverage Output

Look for the "All files" line in coverage summary:

File           | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
---------------|---------|----------|---------|---------|-------------------
All files      |     100 |      100 |     100 |     100 |
setup.ts       |     100 |      100 |     100 |     100 |
context.ts     |     100 |      100 |     100 |     100 |
endpoints.ts   |     100 |      100 |     100 |     100 |

✅ This is 100% coverage - all four metrics at 100%.

Red Flags

Watch for these signs of incomplete coverage:

❌ PR claims "100% coverage" but you haven't verified

• Never trust claims without running coverage yourself

❌ Coverage summary shows <100% on any metric

All files      |   97.11 |    93.97 |   81.81 |   97.11 |

• This is NOT 100% coverage (Functions: 81.81%, Lines: 97.11%)

❌ "Uncovered Line #s" column shows line numbers

setup.ts       |   95.23 |      100 |      60 |   95.23 | 45-48, 52-55

• Lines 45-48 and 52-55 are not covered

❌ Coverage gaps without explicit exception documentation

• If coverage <100%, exception should be documented (see Exception Process below)

When Coverage Drops, Ask

"What business behavior am I not testing?"

NOT "What line am I missing?"

Add tests for behavior, and coverage follows naturally.

---

100% Coverage Exception Process

Default Rule: 100% Coverage Required

No exceptions without explicit approval and documentation.

This applies to code developed with TDD. When working in legacy code, the scope is the change area, not the whole codebase — see the characterisation-tests skill for that workflow.

Requesting an Exception

If 100% coverage cannot be achieved:

Step 1: Document in package README

Explain:

• Current coverage metrics
• WHY 100% cannot be achieved in this package
• WHERE the missing coverage will come from (integration tests, E2E, etc.)

Step 2: Get explicit approval

From project maintainer or team lead

Step 3: Document in CLAUDE.md

Under "Test Coverage: 100% Required" section, list the exception

Example Exception:

## Current Exceptions

- **Next.js Adapter**: 86% function coverage
  - Documented in `/packages/nextjs-adapter/README.md`
  - Missing coverage from SSR functions (tested in E2E layer)
  - Approved: 2024-11-15

Remember

The burden of proof is on the requester. 100% is the default expectation.

---

Development Workflow

Adding a New Feature

1. Write failing test - describe expected behavior
2. Run test - confirm it fails (pnpm test:watch)
3. Implement minimum - just enough to pass
4. Run test - confirm it passes
5. Run mutation testing - verify tests catch real bugs
6. Kill surviving mutants - strengthen tests (ask human when ambiguous)
7. Refactor if valuable - improve code structure
8. STOP and wait for commit approval - present the work and mutation report; never commit without explicit user approval
9. Commit - with conventional commit message, once approved

Workflow Example

# 1. Write failing test
it('should reject empty user names', () => {
  const result = createUser({ id: 'user-123', name: '' });
  expect(result.success).toBe(false);
}); # ❌ Test fails (no implementation)

# 2. Implement minimum code
if (user.name === '') {
  return { success: false, error: 'Name required' };
} # ✅ Test passes

# 3. Run mutation testing to verify test strength

# 4. Kill surviving mutants (ask human when ambiguous)

# 5. Refactor if needed (extract validation, improve naming)

# 6. STOP — present work + mutation report, wait for commit approval

# 7. Commit (after approval)
git add .
git commit -m "feat: reject empty user names"

---

Commit Messages

Use conventional commits format:

feat: add user role-based permissions
fix: correct email validation regex
refactor: extract user validation logic
test: add edge cases for permission checks
docs: update architecture documentation

Format:

• feat: - New feature
• fix: - Bug fix
• refactor: - Code change that neither fixes bug nor adds feature
• test: - Adding or updating tests
• docs: - Documentation changes

---

Pull Request Requirements

Before submitting PR:

• All tests must pass
• All linting and type checks must pass
• Coverage verification REQUIRED - claims must be verified before review/approval
• PRs focused on single feature or fix
• Include behavior description (not implementation details)

Example PR Description:

## Summary

Adds support for user role-based permissions with configurable access levels.

## Behavior Changes

- Users can now have multiple roles with fine-grained permissions
- Permission check via `hasPermission(user, resource, action)`
- Default role assigned if not specified

## Test Evidence

✅ 42/42 tests passing
✅ 100% coverage verified (see coverage report)

## TDD Evidence

RED: commit 4a3b2c1 (failing tests for permission system)
GREEN: commit 5d4e3f2 (implementation)
REFACTOR: commit 6e5f4a3 (extract permission resolution logic)

---

Refactoring Priority

After mutation testing confirms test strength, assess and classify improvement opportunities. For the priority classification table and detailed refactoring methodology, load the refactoring skill — it owns that guidance.

---

Anti-Patterns to Avoid

• ❌ Writing production code without failing test
• ❌ Testing implementation details (spies on internal methods)
• ❌ 1:1 mapping between test files and implementation files
• ❌ Using let/beforeEach for test data
• ❌ Trusting coverage claims without verification
• ❌ Mocking the function being tested
• ❌ Redefining schemas in test files
• ❌ Factories returning partial/incomplete objects
• ❌ Speculative code ("just in case" logic without tests)

For detailed testing anti-patterns, load the testing skill.

---

Summary Checklist

Before marking work complete:

• Every production code line has a failing test that demanded it
• Commit history shows TDD evidence (or documented exception)
• All tests pass
• Coverage verified at 100% (or exception documented)
• Mutation testing run and surviving mutants addressed
• Test factories used (no let/beforeEach)
• Tests verify behavior (not implementation details)
• Refactoring assessed and applied if valuable
• Conventional commit messages used