Test Doubles

Use doubles to control boundaries, not to duplicate object graphs.

Types

• Dummy: passed to satisfy a signature; not used.
• Stub: returns canned data for a specific path.
• Spy: records calls or state for assertions after execution.
• Fake: lightweight working implementation with realistic behavior, such as an in-memory repository or payment gateway.
• Mock: pre-programmed interaction expectation; use when the outgoing interaction itself is the behavior.

Selection Rules

• Prefer fakes for behavior tests because they reduce brittleness.
• Prefer spies/state inspection over strict interaction verification when the result can be observed after the fact.
• Use mocks for true boundaries: out-of-process, slow, nondeterministic, shared, costly, or unsafe dependencies.
• Do not mock internal collaborators that are merely part of the unit's implementation.
• Mock or fake types you own. Wrap third-party libraries behind your own adapter before substituting.

Example Fake

class FakePaymentGateway:
    def __init__(self):
        self.captured = []

    def capture(self, amount, currency):
        self.captured.append((amount, currency))
        return PaymentResult(success=True, transaction_id="fake-123")

Use this when the test cares about the business outcome and captured state.

Example Mock/Spy

class SpyEmailGateway:
    def __init__(self):
        self.sent = []

    def send_receipt(self, email):
        self.sent.append(email)

Use this when the observable behavior is the outgoing message itself.