TDD Test Generation

Test behavior, not implementation. Assert on what the code does (observable output, return values, side effects), not how it does it (internal calls, private state, execution order).

A test that fails for the wrong reason (syntax error, wrong import) is not a valid Red. Fix the test first, then verify the failure matches the intended behavior gap.

Test Philosophy

Default: Classical (Detroit) style. Use real objects. Mock only at system boundaries.

Principle	Rule
Behavior over implementation	Test public API output, not internal calls
State verification preferred	Assert on result values, not "was X called"
Real objects first	Use real dependencies. Mock only external I/O
Black-box perspective	Treat the unit as a black box via its public interface
Sociable tests	Let collaborators participate. Isolate only at boundaries

When to use mocks (London style exceptions):

• External APIs, databases, file system, network
• Non-deterministic dependencies (time, random)
• Slow dependencies that block the 2-min cycle

RGRC Cycle

Phase	Goal	Rule
Red	Failing test	Verify failure reason
Green	Pass test	"You can sin" - dirty OK
Refactor	Clean code	Keep tests green
Commit	Save state	All checks pass

Baby Steps (2-min cycle)

30s: Write failing test → 1min: Make pass → 10s: Run tests → 30s: Tiny refactor → 20s: Commit if green

Test Design

Technique	Use For	Example
Equivalence Partitioning	Group same behavior	Age: <18, 18-120
Boundary Value	Test edges	17, 18, 120, 121
Decision Table	Multi-condition logic	isLoggedIn × isPremium

Assertion Quality

Every test must verify a specific outcome. Weak assertions alone are forbidden.

Category	Matchers	When acceptable
Weak (existence)	toBeTruthy, toBeDefined, toBeFalsy, toBeNull, toBeUndefined	Only with a meaningful assertion in the same test
Meaningful (value)	toBe, toEqual, toStrictEqual, toMatch, toContain, toThrow, toHaveLength	Always preferred
Meaningful (call)	toHaveBeenCalledWith, toHaveBeenCalledTimes, toHaveReturnedWith	When verifying side effects

Bad: expect(result).toBeTruthy() Good: expect(result).toEqual({ id: 1, name: "Alice" })

One test, one concept. If two tests assert the same function with the same argument pattern, merge or parameterize with test.each.

Mock Rules

Rule	Threshold
Mock count per test	Must not exceed assertion count
Mock scope	External dependencies only (API, DB, file system)
Mock target	Never mock the module under test

Mock Pitfalls

Anti-Pattern	Problem	Instead
Assert mock was called	Tests mock behavior, not component behavior	Assert on observable output or side effect
Test-only production method	Pollutes production API for test access	Extract to test utility or use public API
Mock before understanding	Hides real dependency behavior	Understand dependency first, then mock
Partial mock structure	Missing fields cause false passes	Mirror complete real API structure
Mock overuse	More mocks than assertions = testing wiring	Reduce mocks or add meaningful assertions

Coverage

See rules/development/CODE_THRESHOLDS.md for canonical values.

Naming

Level	Pattern
Suite	describe("[Target]", ...)
Group	describe("[Method]", ...)
Test	it("when [condition], should [expected]", ...)

Framework Detection

Condition	Framework
vitest in deps	Vitest
jest in deps	Jest
bun as runtime	Bun test
No framework found	Vitest

References

Topic	File
Feature-driven	${CLAUDE_SKILL_DIR}/references/feature-driven.md
Bug-driven	${CLAUDE_SKILL_DIR}/references/bug-driven.md
Flaky tests	${CLAUDE_SKILL_DIR}/references/flaky-test-management.md