Chapter 09 of 10
When Not to Mock
A passing run against a mock is a statement about the mock. The four questions mocking cannot answer, what takes over in each of them, and proxy mode as the path between a stand-in and the real service.
Every technique has a sentence that describes its limit, and for mocking the sentence is short. A mock only knows what you told it, so anything it tells you back is something you already knew.
That is not a weakness to work around. It is the definition, and the trouble starts only when a result from a mock is read as evidence about the service the mock stands in for.
The four questions a mock cannot answer
Each of these looks like something a mock covers, and in each case the mock is answering a different question than the one being asked.
Does the provider behave as documented? The mock was built from the documentation, so of course it matches it. Whether the implementation matches is a question only the implementation can answer, which is what contract tests against a real deployment are for.
How long does it take? A configured delay is a number you chose. It tells you how your client behaves at that latency, which is useful, and it tells you nothing about the service. Performance is measured against the thing being measured.
Does authorisation refuse what it should? A mock returning 403 for a request without a token is performing a rule you wrote. The real question is whether the provider enforces the same rule, and a stand-in cannot be the witness for that.
Will the integration actually work? Two systems fail to integrate over the details neither document mentions, such as an encoding, a redirect, a header a proxy strips or a timeout further up the chain. The mock has none of those, because it is not the system.
What takes over, and where
The replacement is never one thing, because the questions above belong to different moments.
| Question | Answered by | Running against |
|---|---|---|
| Can the consumer handle this shape | The mock | Nothing real, by design |
| Does the provider still match the contract | Contract tests | A deployed environment |
| Does the whole path work end to end | Integration tests | Real services, real data |
| Is it still true in production | Monitors | The live environment |
The two guides next door cover the second and fourth rows in full. Contract testing against integration testing is the distinction that matters most here, and API monitoring is the same check moved to the other side of the release.
The shape of the mistake
The failure mode is worth naming precisely, because it is rarely a decision anybody made.
A team mocks a dependency in a unit test, which is correct. The mock gets reused in an integration test, which is now an integration test with the integration removed. The suite goes green, the coverage number goes up, and the one thing nobody is testing is the boundary that both services meet at.
The tell is a test that fails when you break the mock and passes when you break the service. If you cannot say which of those it would catch, it is a consumer test with a misleading name.
Proxy mode as the middle path
Integration rarely happens on one day, and for the weeks in between there is a position between a full stand-in and the real service.
A proxy forwards anything the mock has no rule for to a real backend. The endpoints you are working on are mocked, the endpoints that already work are real, and the client does not change at all. It is the most useful mock setting during the handover period, because it moves the boundary between invented and real without moving any code.
It also has an honest limit. A response that came through a proxy is a real response, and a response that came from a rule is not, so a run that touches both proves whatever its real half touched. Keeping track of which is which is the whole job, and a log that marks each response with its source is what makes that possible.
In Routebase
Proxy Mode is a per-server setting with a target URL, available on the Starter plan and above. Unmatched requests go to the backend you name, proxied responses are marked as such in the request log, and switching it off puts the mock back in charge without touching a rule.
Where the mock stops, two other parts of the same contract take over. Test suites run against a real environment and validate the response against the version that environment is pinned to, and monitors do the same on a schedule after the release. Both read the specification the mock was generated from, so the stand-in and the checks that replace it are describing the same interface rather than two copies of it.
Four things the mock deliberately does not do are worth stating plainly. It does not record live traffic and replay it, and it answers HTTP rather than GraphQL, gRPC or WebSocket traffic. It runs as a hosted service rather than inside your own network, and it does not verify a consumer's expectations against a provider the way a consumer-driven contract tool does. What it does instead is stay attached to the contract everything else in the lifecycle is generated from. That is the property which keeps the mock, the documentation, the tests and the monitors describing one interface. The Mock Server Settings guide covers proxy mode, and the Test Suites guide covers the checks that run against the real service.
Frequently asked questions
Does a passing test against a mock prove anything about the API?
It proves something about the consumer, which is that it can handle the response it was given. It proves nothing about the provider, because the provider was not involved, so a suite that is entirely green against mocks is compatible with a service that has been broken for a week. The two questions need two different setups and confusing them is how outages reach production with a full board of passing checks.
What is the difference between mocking and contract testing?
Mocking gives a consumer something to call, while contract testing checks that a real response still matches the agreed description. One stands in for the provider and the other interrogates it, which is why a mock belongs in development and a contract test belongs in a pipeline against a running deployment.
When should you use a real API instead of a mock?
Whenever the question is about the provider rather than about the consumer. That covers verifying that an endpoint behaves as documented, measuring how long it actually takes, checking that authorisation refuses what it should refuse, and anything where a third party's real semantics are the subject. A mock answers none of those, because a mock only knows what you told it.
What is proxy mode on a mock server?
Proxy mode forwards any request that no mock rule matches to a real backend, so the endpoints you are working on are mocked and everything else reaches the live service. It is the practical middle position during integration, since it lets a client be partly on the stand-in and partly on the real thing without a change in the client itself.
Last reviewed by The Routebase Team.