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:

• external service - a system you do not deploy
• internal service - a system your team owns, deployed separately
• time - now, durations, timers, expiry, scheduling
• environment - timezone, locale, random values, IDs, ports
• data - state left over from other tests or other people

A test can suffer more than one. Fix them separately; a single "make it deterministic" change that touches all four is unreviewable.

Phase 1: Decide what stays real

Work through ./resources/when-to-mock.md. It maps test level against dependency type and gives the default for each cell.

The two defaults worth stating up front:

• Unit and component tests: mock everything across the process boundary.
• End-to-end tests: keep your own stack real. Mock only what you do not own or cannot control.

If the answer is "mock our own API in an end-to-end test", the test has stopped being end-to-end. Say so and either accept it as an integration test or keep the backend real.

Phase 2: Pick the interception layer

Recipes for each are in ./resources/playwright-route-recipes.md, ./resources/msw-recipes.md, and ./resources/clock-and-timezone.md.

Prefer the highest layer that solves the problem. Mocking at the module boundary to fix a network problem couples the test to your import graph and survives no refactor.

Phase 3: Write the stub

Every stub carries four things:

1. A precise matcher. Match method and path, not a bare substring. A loose glob that also catches the analytics beacon will hide the day the real call disappears.
2. A realistic body. Status, headers, and content type that the real service actually returns. Copy from a captured response, not from memory.
3. The failure cases. A stub that only ever returns 200 tests one branch. Add the 4xx, the 5xx, the timeout, and the malformed body that your error handling claims to survive.
4. Unhandled-request enforcement. onUnhandledRequest: 'error' in MSW, or an explicit catch-all route that fails the test in Playwright. Default to strict.

Phase 4: Control time and environment

When time matters:

• pin the instant (clock.setFixedTime / vi.setSystemTime) to a date with no special properties, and one that is not near a DST boundary unless DST is the thing under test
• pin the timezone through config or TZ, never rely on the CI agent's default
• pin the locale when any assertion reads formatted dates, numbers, or currency
• advance time explicitly rather than waiting for it; a test that sleeps to let a timer fire is a slow test with a race in it

./resources/clock-and-timezone.md has the per-runner spellings and the DST and leap-day cases worth a deliberate test.

Phase 5: Guard against drift

A mock without a drift guard becomes false documentation. Pick at least one:

• A contract check against the real spec or a live sample, run on a schedule rather than per commit. Hand off to testing-api-contracts.
• A refresh command for recorded HAR files, documented next to the fixtures, with the date of the last refresh recorded.
• A thin real-dependency smoke test that exercises the same endpoint unmocked, tagged so it can be excluded from the main run.

Record which guard applies. "None" is an acceptable answer only for a dependency that is genuinely frozen, and it still gets written down.

Phase 6: Record the fidelity trade

Close with a short note next to the stub or in the test README:

• what is mocked and at which layer
• what the mock stops the suite from catching
• what guards the mock against drift, and when it was last verified

Use ./resources/mocking-decision-record.md.

Common Failure Modes

• mocking your own backend in a test you still call end-to-end, then trusting it as release evidence
• a handler set that passes unknown requests through, so a renamed endpoint silently keeps testing nothing
• stubs that only return success, next to error-handling code no test ever executes
• a single giant HAR recorded eighteen months ago, refreshed by nobody, matched loosely
• fake timers installed without restoring them, so an unrelated later test hangs on a real timeout
• freezing the clock but not the timezone, so the suite passes in Warsaw and fails in the CI region
• reaching for vi.mock on a module to solve what is actually a network problem

Resource Map

• ./resources/when-to-mock.md - decision table by test level and dependency type, with the fidelity cost of each choice
• ./resources/playwright-route-recipes.md - route, fulfill, abort, request modification, and HAR record and replay
• ./resources/msw-recipes.md - node and browser setup, handler patterns, strict unhandled-request config, per-test overrides
• ./resources/clock-and-timezone.md - fake clocks, fixed timezone and locale, DST and leap-day cases, per-runner spellings
• ./resources/mocking-decision-record.md - short template for recording the fidelity trade and the drift guard

Related Skills

• testing-api-contracts - when the mock needs a drift guard against the real specification
• ui-playwright-test-developer (planned) - when the stub is part of a wider browser test being written or refactored
• api-playwright-test-developer - when the API side of the flow is under construction
• writing-unit-tests - when the question is about test doubles at the module boundary rather than the network
• stabilizing-flaky-tests (planned) - when nondeterminism remains after the network and clock are controlled
• unslop-tests - when the suite is mock-heavy and may be proving nothing

Definition of Done

This skill is complete when:

• the nondeterminism is named and classified, not just suppressed
• the decision about what stays real is explicit and matches the test level
• every stub matches precisely, returns a realistic body, and covers at least one failure branch
• unhandled requests fail the test rather than passing through
• time-dependent tests pin instant, timezone, and locale together
• each mock has a named drift guard or a written statement that it has none
• the fidelity given up is recorded where the next reader will find it