Select and implement the right test double with a default preference for fakes, stubs, and spies over mocks. Use when writing or refactoring tests, especially when users mention test doubles, mocking strategy, interaction assertions, or flaky tests caused by over-mocking.
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Select and implement the right test double with a default preference for fakes, stubs, and spies over mocks. Use when writing or refactoring tests, especially when users mention test doubles, mocking strategy, interaction assertions, or flaky tests caused by over-mocking.
Write tests that describe behavior and state, not implementation details. Avoid mock-by-default.
Default Rule
Prefer state/output assertions first.
Choose the lightest double that makes the test clear.
Use mocks only when interaction contract is the behavior under test.
Decision Tree
Can the test assert state (persisted data, returned value, emitted event)?
Yes -> use a Fake (in-memory or lightweight real implementation).
No -> continue.
Do you need to force a branch (success/failure/timeout) with controlled responses?
Yes -> use a Stub.
No -> continue.
Do you need to observe an outbound effect (email, message, metrics) without prescribing internal construction?
Yes -> use a Spy.
No -> continue.
Do you need to verify interaction contract (never called, called once, call order/protocol)?
Yes -> use a Mock, with minimal expectations.
If one test needs many interaction expectations, treat it as a design smell and raise the abstraction of the port.
Naming and Placement
Names
FakeXxxRepo, InMemoryXxxRepo
StubXxxGateway, FailingXxxStub, FixedClockStub
SpyXxxPublisher, SpyEmailService
MockXxxClient only for contract-driven tests
Paths (cross-platform style)
Python: tests/doubles/
TypeScript: test/doubles/ or __tests__/doubles/
Always use forward slashes in paths.
Style Constraints
Prefer state/output assertions over called_with assertions.
For spies, assert only relevant facts (for example count, recipient, subject).
Keep stubs configurable per scenario; do not build mini-systems.
Keep fakes honest to domain invariants; add contract tests for real adapters when needed.
What Can Be Doubled
Usually yes: ports to I/O (database, network, queues), time/randomness, email, logs, metrics.
Usually no by default: value objects, entities, pure domain logic, internal mappers.
Quick PR Smell Check
Would renaming an internal method break the test without behavior change? If yes, likely over-mocked.
More than 2-3 interaction expectations in one test? Prefer fake/spy or redesign the port.
Could the fake diverge from the real adapter? Add a contract test.
Minimal Templates
See references/examples.md for Jest-based JavaScript and TypeScript templates for fake, stub, spy, and contract-focused mock.
See references/usage.md for trigger prompts and copy-paste templates.
See references/quick.md for single-page fast reference.
