Mock servers for local development: stand-in dependencies that answer like the real thing

What it is

A mock server is a process, or in the browser a service worker, that answers HTTP requests in place of a dependency you do not want to run locally: a payment provider, an identity service, a colleague's unfinished API. WireMock's stubbing documentation shows the shape: a stub matches a request (get(urlEqualTo("/some/thing"))) and returns a configured status, headers and body; stubs can be declared in code or as JSON files. Mock Service Worker describes the browser-side variant: it uses the Service Worker API to intercept actual production requests on the network level, so application code keeps calling fetch unchanged. This differs from test doubles inside the code, which replace a function rather than a network endpoint, and from contract tests, which verify an integration. A mock server exists so that development, demos and front-end work can proceed without the dependency.

Why it matters

Waiting for a dependency, sharing one staging tenant, or calling a paid API from every developer machine slows work and makes local runs flaky. A mock makes the dependency's behaviour explicit and repeatable, including the error paths (timeouts, 429s, malformed bodies) that the real system rarely produces on demand.

How to apply

• Generate the baseline stubs from the dependency's OpenAPI document or from recorded traffic, then edit; hand-written stubs drift fastest.
• Keep stubs in the repository next to the code that uses them, one file per scenario (happy-path, card-declined, upstream-timeout), and select the scenario with a header or query flag rather than by restarting the server.
• Include latency and failure stubs and exercise the client's retry and timeout code against them locally.
• Run the same mock in CI for the front end or the integration layer, so a green build does not depend on a third party being up.
• Re-record or regenerate on a schedule and diff against the previous stubs; the diff is an early warning that the dependency changed.

Pitfalls

A mock that always answers 200 trains the code to expect it. Stubs copied from production responses may contain personal data; scrub before committing. Matching too loosely hides routing bugs; matching too strictly (full body equality) breaks on harmless changes. A mock is not evidence that the integration works; contract tests and a run against the real sandbox are.