API mocking gets bought for a testing reason and used for a scheduling one. The actual job is almost always the same: the frontend team has a design, a deadline and no backend, and somebody needs to decide whether they wait three weeks or build against something that behaves like the API will.
That framing matters because it changes what “good” means. If mocking is a testing concern, you optimise for determinism and speed. If it is a scheduling concern, you optimise for fidelity, because the entire value proposition is that work done against the mock does not need redoing against the real service. A mock that returns plausible-looking data but the wrong field names converts three weeks of parallel work into three weeks of parallel work plus a week of rework, which is worse than waiting.
Fidelity is where the interesting distinction lives. A mock built by hand encodes what somebody believed the API would return on the day they wrote it. A mock derived from the OpenAPI document encodes what the document says, and the document is at least in the same review as the design. The first one drifts the moment the design changes and nobody notices, because a mock has no consumers to complain. The second one drifts only as fast as your spec does.
The second thing that separates useful mocks from demo mocks is state. Real clients create a thing, then list it, then update it, then get a conflict. A stateless mock that returns the same fixture regardless of what you sent cannot exercise any of that, so every flow with more than one step gets built on assumptions.
Key takeaways
- The real use case is parallel development, which makes fidelity to the contract the property that matters most. A convenient mock with wrong field names costs more than it saves.
- Spec-derived mocks inherit the accuracy of your OpenAPI document. Handwritten mocks inherit the accuracy of somebody’s memory, and nothing tells you when they go stale.
- Stateless mocks cannot exercise create-then-read flows, conflicts or pagination. Decide whether you need state before choosing, because it eliminates most options.
- Latency and error injection are the difference between a frontend that handles failure and one that discovers failure in production.
The real job is parallel development
Set the testing conversation aside for a moment and look at what teams actually use mocks for.
Frontend ahead of backend. The design is signed off, the API is agreed in a document, and the backend is three sprints of work. The frontend builds against a mock derived from that agreement. This is the highest-value use, and it only works if the agreement is written down in a machine-readable form, which is to say if you are working spec-first. Without a spec, the mock is one engineer’s guess and the rework is guaranteed.
Third-party dependencies you cannot hammer. Payment providers, identity providers, shipping APIs. Their sandboxes rate-limit, go down, cost money or require a real card. A local mock removes them from your inner loop and from CI.
Failure paths you cannot reproduce. How does the checkout behave when the payment API returns a 503 after twelve seconds? You cannot ask a vendor to break on demand, so the only way to build and test that path is to fake it. This is the use case teams under-invest in most and the one that produces the worst production incidents.
Demos and environments. A sales demo, a preview environment, a workshop, where the requirement is that things look like they work without a real backend behind them.
Isolating tests. Unit and component tests where a real network call would be slow and flaky.
These pull in different directions. Parallel development wants a shared mock everyone points at and high contract fidelity. Test isolation wants an in-process mock with no network and complete determinism. Failure simulation wants precise control over timing and status codes. A team that picks one tool for all five is going to be unhappy with at least two of them, and running two mocking tools for different jobs is a perfectly reasonable outcome.
Spec-derived versus handwritten, and what drifts
This is the distinction that predicts whether a mock will still be useful in six months.
Spec-derived mocks read your OpenAPI document and generate responses from the declared schemas. Request a GET /orders/123 and you get an object with every declared field, correctly typed, either from the examples in the document or generated from the schema. When the spec changes, the mock changes with it, automatically, with no human step.
The properties that follow are what make this the default recommendation. Field names cannot be wrong, because they come from the same document the backend implements against. Adding a field to the spec adds it to the mock. Renaming a field renames it everywhere. And critically, the mock can validate incoming requests against the spec and reject a malformed one, which turns the mock into an early contract check for the frontend rather than a permissive thing that accepts anything.
The weaknesses are real too. Generated data is structurally correct and semantically meaningless: a string field yields a placeholder string, not a plausible customer name, which makes for ugly demos and hides layout problems with realistic data lengths. And a vague spec produces a vague mock, so this approach inherits every gap in your document, which is the subject of OpenAPI and Swagger tooling.
Handwritten mocks are fixtures somebody wrote: this request gets this response body. Full control over the data, so demos look real and edge cases are exactly what you want them to be. Fast to set up for a handful of endpoints.
The failure mode is drift with no signal. The backend renames a field, the spec updates, the real service ships, and the mock keeps returning the old shape for as long as anyone points at it. Every test against it passes. The frontend team keeps building against a description of an API that no longer exists. There is no mechanism anywhere in that loop that produces an error, which is why this is the more dangerous of the two options despite feeling like the safer one.
The practical middle is a spec-derived mock with examples in the spec itself. The OpenAPI document supports example values per schema and per response, so you write realistic data once, in the spec, and every consumer of the document gets it: the mock, the documentation and the SDK snippets. Examples in the spec are the highest-return small change available in this category, and most teams leave them empty.
Needs first-hand data: Take the mock your frontend team is currently using and diff its responses field by field against the real API in staging for ten endpoints. Count mismatched names, missing fields, wrong types and wrong nullability. That count is the amount of rework already sitting in the current sprint, and it is usually a surprise to everyone.
Stateful mocking is the line most tools do not cross
Most mocks are functions from request to response with nothing in between. That covers reading a page and falls apart on anything transactional.
Consider a mundane flow: create an order, get a 201 with an ID, poll that ID until status is complete, then cancel it and get a 409 because it already completed. A stateless mock returns the same fixture for every call to the status endpoint, so the polling loop either never terminates or terminates immediately, the ID it returns does not match the one you created, and the conflict path cannot be reached at all. The frontend engineer builds something that works against the mock and has never once executed the code that handles the real sequence.
Tools sit at one of four levels here, and knowing which you need eliminates most of the market immediately:
Static. One response per endpoint, always. Fine for reading screens, useless for anything else.
Conditional. Response depends on the request: this path parameter returns a 404, this body returns a validation error. Covers a lot, including most error path testing, without any persistence.
Stateful. The mock holds data between requests, so what you create you can then read, list and delete. This is what create-then-read flows need, and it is where the tooling thins out sharply.
Scripted. Arbitrary logic on each request, usually because you can write code in the mock definition. Maximum power, and at some point you have written a second implementation of your backend that nobody maintains.
Be honest about which level you need before shortlisting. Most teams need conditional and think they need scripted. Teams building anything with a wizard, a shopping basket or an asynchronous job genuinely need stateful, and picking a static tool for that work means the mock gets abandoned within a fortnight.
There is a ceiling on all of this worth naming: the closer a mock gets to being stateful and scripted, the closer it gets to being a parallel implementation of your service, with its own bugs, its own maintenance and nobody assigned to it. When you find yourself implementing business rules in the mock, the correct move is usually to stop and run a real instance of the service against a seeded database instead, which is a preview environment problem rather than a mocking one.
Latency and error injection
The default behaviour of every mock is to answer instantly and successfully, and that trains a frontend to assume both.
Any mock worth using should let you inject, per endpoint:
Latency, including latency that varies, because a loading state that only ever appears for a few milliseconds during development is a loading state nobody has actually looked at. Fixed delays catch the obvious; variable delays catch the race conditions where two requests return out of order.
Error statuses, on demand and ideally probabilistically. The 500, the 429, the 401 after the token expires mid-session. A frontend that has never received a 429 from the mock has untested retry logic, and retry logic that has never run is retry logic that will retry a non-idempotent write.
Malformed and empty responses. Truncated bodies, an empty array where the code expects one item, nulls in fields the client assumed were present. These are where client crashes actually come from, and only a mock can produce them reliably.
Connection failures and timeouts. Distinct from an error status: a hung connection exercises a completely different code path from a 503, and most clients handle one and not the other.
The workflow that makes this stick is making failure modes switchable at runtime rather than requiring a config edit and a restart. If injecting a 500 takes two minutes, nobody does it during development, and the failure paths get written blind. If it is a toggle in a UI or a header on the request, people actually exercise them.
One practice worth adopting: keep a named scenario per failure mode (“payment provider down”, “rate limited”, “slow network”) and make running the frontend against each one a checklist item before a feature is called done. That is cheap, it is the whole point of having a mock, and it is skipped almost universally.
Needs first-hand data: For one real frontend feature, run it against the mock with each of five injected conditions in turn: a 500, a 429, a two-tier slow response, a truncated body and a hung connection. Record which produce a usable message to the user, which produce a stuck spinner and which produce a crash. The stuck-spinner count is the honest state of your error handling, and it is rarely zero.
Prism
Prism is the canonical spec-derived mock server: point it at an OpenAPI document and it serves a mock of that API, generating responses from the declared schemas or returning the examples in the spec. It also validates incoming requests against the document and returns a proper error when they do not conform, which turns the mock into a contract check as well as a stand-in. If you are spec-first, this is the shortest distance between a design document and something the frontend can call.
Pros
- Zero-configuration mocking from an existing OpenAPI document, so a new API is mockable the moment the spec exists
- Validates incoming requests against the spec, catching client-side contract mistakes during development rather than at integration
- Cannot drift from the document, which removes the most dangerous failure mode in this category
- Can proxy to a real backend and validate its responses against the spec, which is a useful drift check in its own right
Cons
- Stateless by design, so create-then-read flows, conflicts and pagination sequences are out of reach
- Generated data is structurally valid and semantically meaningless unless you put examples in the spec yourself
- Entirely dependent on spec quality, so a vague or incomplete document produces a mock that is technically correct and practically useless
Best for: Spec-first teams who want the frontend unblocked from the design document with no handwritten fixtures to maintain.
Pricing: Open source with no vendor and no bill. The real cost is the spec discipline it assumes, including writing examples, which is work you should be doing anyway.
WireMock
WireMock is the heavyweight of the category: a mock HTTP server with request matching, response templating, stateful scenarios, fault injection, proxying with record-and-replay, and a programmatic API. It has been the JVM ecosystem’s default for years and now runs standalone as well, so it is not JVM-only in practice. If your requirement includes stateful behaviour and precise failure simulation, this is the tool with the deepest answer.
Pros
- Genuine stateful scenarios with named states and transitions, which covers create-then-read and conflict flows properly
- Rich request matching on method, path, headers, query and body content, so one mock can serve many conditional cases
- First-class fault injection including delays, malformed responses and connection-level failures, not just status codes
- Record-and-replay against a real service captures accurate fixtures for third-party APIs you cannot control
Cons
- Handwritten stub definitions drift from the spec with nothing to warn you, which is the structural weakness of the whole approach
- Substantial surface area, so a full setup becomes a small internal project with its own conventions and its own owner
- Heavier to run than in-process or single-binary alternatives, which makes it a poor fit for fast unit test loops
Best for: Teams who need stateful mocking and realistic fault injection, particularly around third-party dependencies they cannot break on demand.
Pricing: Open source with no vendor and no bill for the core server; a hosted cloud offering with team features is sold separately. The real cost is the stub library you accumulate and whoever keeps it aligned with reality.
Mockoon
Mockoon is a desktop application for building mock APIs, with a graphical editor for routes, responses, rules and delays, plus a command-line runner for CI. It optimises for a specific and common situation: someone needs a working mock in the next ten minutes and does not want to learn a configuration format. Definitions export as files, so they can be committed and shared.
Pros
- Graphical editor makes a working mock available in minutes with no configuration syntax to learn
- Definitions export to files that can be committed, so mocks are shareable and reviewable
- Command-line runner means the same definition serves local development and CI without a rewrite
- Per-route latency, status codes and rules are configurable in the UI, which means people actually use failure injection
Cons
- Handwritten by nature, so it carries the full drift risk with no connection to a spec
- Stateful behaviour is limited compared with the heavier tools, so complex transactional flows are awkward
- Desktop-first workflow encourages individual mocks per engineer, which quietly produces several divergent versions of the truth
Best for: Small teams and individual engineers who need a working mock quickly and value a visual editor over spec coupling.
Pricing: Open-source desktop application with no licence cost, plus paid hosted and team features. The real cost is the drift and duplication that come from mocks nobody derives from a spec.
MSW
MSW takes a genuinely different approach: rather than running a server, it intercepts requests at the network layer inside the JavaScript runtime, using a service worker in the browser and request interception in Node. The consequence is that your application code makes real requests through its real client with no configuration change, no separate process and no base URL switching. The same handlers work in the browser during development, in component tests and in end-to-end tests.
Pros
- No base URL change and no separate process, so the application runs exactly as it will in production
- The same handlers serve browser development, unit tests and component tests, removing three parallel mock definitions
- Handlers are code, so conditional and stateful behaviour is expressed in ordinary JavaScript without a configuration language
- Interception at the network layer means the real HTTP client, serialisation and error handling are all exercised
Cons
- JavaScript-only, so it does nothing for a mobile client, a backend service or a team with a non-JS frontend
- Handlers are handwritten, so they drift from the spec unless you generate them from it yourself
- Powerful enough to accumulate real logic, and a handler file that has grown business rules is a second implementation nobody owns
Best for: JavaScript frontend teams who want one set of mocks covering development, component tests and end-to-end tests without a separate server.
Pricing: Open source with no vendor and no bill. The real cost is maintaining handlers by hand and resisting the temptation to implement the backend in them.
Beeceptor
Beeceptor is a hosted mocking and request-inspection service: you get a public endpoint that can return configured responses, proxy to a real backend, and capture everything that hits it. The hosted, publicly-reachable part is the differentiator. When you need a URL a third-party system can actually call, for a webhook, a partner integration or a mobile device on a different network, a local mock cannot help you and this can.
Pros
- Publicly reachable endpoints let external systems and partner integrations call your mock, which local tools cannot do
- Request inspection makes it a debugging tool for inbound webhooks as well as a mock, which is a common unmet need
- Nothing to install or run, so it is available to non-engineers and to anyone testing from a device
- Proxy mode with selective overrides lets you fake one endpoint while passing the rest through to a real service
Cons
- Hosted, so request bodies travel through a third party, which is a data-handling decision before it is a tooling one
- Metered usage means high-volume or CI-driven use runs into plan limits, which makes it a poor fit for automated test loops
- Handwritten rules with no spec coupling, so it carries the usual drift risk
Best for: Testing inbound webhooks and partner integrations that need a publicly-reachable URL, and quick shared mocks for people without a dev environment.
Pricing: Free tier with paid plans metered on request volume, endpoints and retention of captured traffic. For the production side of the same problem, see webhook infrastructure.
Microcks
Microcks is the most architecturally ambitious option here: a self-hosted service that imports API definitions from OpenAPI, AsyncAPI, gRPC and other formats, serves mocks from them, and also runs the same artifacts as contract tests against a real implementation. That dual use is the point. The same imported definition both mocks the service for consumers and verifies that the real service conforms, which closes the loop that leaves most mocks quietly wrong.
Pros
- One imported artifact produces both the mock and a conformance test, so the mock cannot silently diverge from the verified contract
- Covers event-driven and gRPC interfaces as well as REST, which is rare and matters in mixed estates
- Self-hosted and centrally managed, giving every team one shared mock catalogue rather than a mock per laptop
- Fits a platform-team model well, where API definitions are registered centrally and consumed by many teams
Cons
- It is infrastructure you now operate, with upgrades, storage and access control, which is a real commitment for a mocking tool
- Heavier than any individual engineer needs, so adoption has to be driven centrally or it does not happen
- Configuration and concepts take longer to learn than single-purpose tools, which slows the first useful result
Best for: Platform teams standardising mocking across many services and protocols, who want mocks and conformance tests from one registered artifact.
Pricing: Open source with no vendor and no bill for the software; the real cost is running it, which is a persistent service with storage and access control rather than a binary you invoke.
Postman
Postman includes mock servers as part of its workspace: a collection with saved example responses can be published as a hosted mock endpoint, returning those examples based on request matching. The appeal is proximity. If your team already keeps its requests in Postman, a mock is a few clicks from the collection you already maintain, with no new tool to introduce, and non-engineers can use it.
Pros
- Available immediately if collections already live there, with no additional tool, process or onboarding
- Hosted and publicly reachable, so external systems and people without a dev environment can call it
- Examples saved from real responses make reasonably accurate fixtures with little extra work
- Accessible to non-engineers, which matters for support, solutions and partner-facing use
Cons
- Mock calls are metered against plan allowances, so anything running in CI consumes a resource you are paying for
- Examples are handwritten snapshots that drift as the API changes, with nothing to flag the divergence
- Ties your mocking to a vendor workspace, which is the coupling many teams are actively trying to reduce
Best for: Teams already standardised on Postman who need an occasional shared mock and do not want a second tool.
Pricing: Included with the workspace subscription, with mock server calls metered against plan allowances. If workspace coupling is the objection, Postman alternatives covers the wider move.
How to choose
One: name the job. Parallel frontend development, third-party isolation, failure simulation, or test isolation. These want different tools and it is normal to end up with two.
Two: decide whether you need state. Static, conditional, stateful or scripted, per the levels above. This eliminates more candidates than any other question, and getting it wrong means the mock is abandoned within weeks.
Three: check whether you have a usable OpenAPI document. If yes, default to spec-derived, because the drift problem is solved rather than managed. If no, that is the more valuable thing to fix first, since mocks, docs, tests and SDKs all depend on it.
Four: work out whether the mock must be reachable from outside your machine. Webhooks, mobile devices and partner systems force a hosted or self-hosted answer regardless of every other preference.
Five: then check the failure injection controls, because that is the capability that gets used least and pays off most.
| Tool | Source of truth | State | Runs where | Picks itself when |
|---|---|---|---|---|
| Prism | OpenAPI document | Stateless | Local or CI | You are spec-first and want zero drift |
| WireMock | Handwritten stubs | Stateful scenarios | Local, CI or a server | You need real state and real fault injection |
| Mockoon | Handwritten, visual | Limited | Desktop or CI | Someone needs a working mock this afternoon |
| MSW | Handwritten handlers | In-process, code | Inside the JS runtime | One JavaScript frontend covering dev and tests |
| Beeceptor | Handwritten rules | Limited | Hosted, public URL | An external system must call the mock |
| Microcks | Imported API definitions | Depends on artifact | Self-hosted service | A platform team standardises mocks across teams |
| Postman | Collection examples | Stateless | Hosted | Collections already live there and needs are occasional |
The arrangement I would reach for by default on a spec-first team is Prism for the contract-accurate mock the frontend builds against, plus an in-process mock inside the test suite for determinism, plus one stateful tool reserved for the two or three flows that genuinely need it. Trying to make one tool serve all three produces a mock that is mediocre at each.
How mocking relates to gateway, documentation, testing and client generation decisions is mapped in API management platforms.
Frequently asked questions
Should mocks live in the same repository as the frontend or the backend?
The mock definition belongs wherever the contract does, which is the backend repository if you are spec-first, because the spec is the mock. If mocks are handwritten fixtures, put them in the backend repository anyway and publish them, so that the team changing the API is the team changing the mock. Fixtures in the frontend repository are fixtures the backend team will never update.
Can I use a mock in CI instead of a real dependency?
For anything third-party, yes, and you should. For your own services, a mock in CI means you are testing against your assumption about your own service rather than your service, which is precisely the drift risk. A spec-derived mock is defensible there; a handwritten one quietly turns your integration tests into assertions about a fixture file.
Does mocking replace contract testing?
No, and conflating the two is a common mistake. A mock lets a consumer build without the producer. Contract testing verifies that the producer still satisfies what consumers expect. Using only a mock means both sides can agree on something that no longer matches the running service. Microcks is interesting precisely because it does both from the same artifact. The wider picture is in API testing tools.
How do I stop the mock becoming a second implementation?
Set a rule and hold it: the mock may encode shape, status codes, latency and state transitions, and it may not encode business rules. The moment somebody wants pricing logic or permission checks in the mock, the right answer is a real instance of the service against seeded data. That line is easy to state and gets crossed gradually, so it needs to be an explicit review point.
What about mocking GraphQL or gRPC?
Same principles, different tooling. Both have machine-readable schemas, so the spec-derived approach applies even more naturally than it does to REST. Microcks covers gRPC and event-driven interfaces directly; for GraphQL, the schema-based mocking built into the major server libraries is usually the better route than a generic HTTP mock, since intercepting HTTP gives you no field-level control. See GraphQL servers and platforms and gRPC tooling.
Related reading
- Best API testing tools — contract testing, which is the verification a mock cannot give you.
- Best OpenAPI and Swagger tooling — the document quality your spec-derived mock inherits.
- Best API documentation tools — a safe target for the try-it-out console, which is the same problem again.
- Best preview environment tools — what to use when the mock has grown into a second implementation.
- Best API management platforms — how mocking, gateway, docs and testing choices constrain one another.