mocking-network-and-time

Mocking Network and Time

Use this skill when a test is unreliable, slow, or unrepeatable because it reaches something the test cannot control: someone else's API, the wall clock, the machine's timezone, or a payment sandbox that rate-limits on Fridays.

Mocking buys determinism and pays for it in fidelity. Every mock is a claim about how the real dependency behaves, and that claim rots silently. The skill is not "how do I stub this", it is "what should stay real, what should be faked, and how do I find out when a fake has drifted from the thing it imitates".

When to Use

• a test fails only when a third-party sandbox is down or slow
• a date-sensitive test passes in November and fails on 1 January
• a suite takes minutes because every test hits a real backend
• a test passes with a mock while the same flow is broken in production
• a team is deciding between MSW, Playwright route, and a real test environment
• fixtures were recorded once and nobody knows whether they still match the API

Operating Principles

• Mock the boundary you do not own. Third-party APIs, payment providers, email, clocks, randomness. Your own code under test stays real.
• Fidelity is the constraint, determinism is the goal. Reach for the least fidelity loss that removes the nondeterminism.
• A mock is a contract copy, so verify the original. Any mocked response shape needs a periodic check against the real API, or it becomes a test that proves your fixtures agree with themselves.
• Fail loudly on unmocked traffic. A handler set that silently passes unknown requests through hides both new dependencies and typos in URLs.
• Freeze time explicitly, never implicitly. Pin the instant, the timezone, and the locale together. Two of the three is still a flaky test.
• State the fidelity you gave up. Every mocking decision is written down with what it stops catching.

Workflow

Phase 0: Name the nondeterminism

Before choosing a tool, say what exactly is uncontrolled. One of: