API mock drift
API mock drift is when a mock of an API stops matching the API it stands in for. The real API changes, and the mock keeps returning the old responses, so tests written against the mock keep passing while the code under test would fail against the real thing.
How it happens
A mock is a copy of an API’s responses at one moment. A field is added, renamed or becomes nullable; a status code changes; a response gains an error shape. Nothing re-reads the copy, so nothing notices. Drift is quiet by nature: the tests stay green, and that is the harm.
Drift is not a spec violation
Checking a live API against its OpenAPI document catches an implementation drifting from its own document. Mock drift is a different question: does the mock still match the live API? The two are independent. An API can add a field the spec does not forbid — a spec check passes, and the mock has still drifted — or a mock can be updated to match production while production does something the spec never allowed, so the mock agrees and the spec check fails. The guide below works through both on a real run.
How to check for it
Ask the live API the same questions the mock answers, and compare the shapes. With APIFae that is one command against a running API: apifae diff <url> probes every mocked endpoint and reports what changed. This is a real run against the guide’s example backend, cropped to one of the endpoints that drifted. The summary line counts the whole run:
GET /reports/daily
✗ Drift detected:
+ $.errorCode (String)
Summary: 4 checked, 3 drifted, 3 violating, 1 variant skipped| Exit | Meaning |
|---|---|
| 0 | nothing drifted |
| 1 | drift, a spec violation, or both |
| 2 | the run could not complete — connection refused, timeout, 401, 403 |
Separating 1 from 2 is what makes the check trustworthy: a network problem never reads as a pass.
Run it in CI on a schedule or before a release. It is one line of YAML: apifae diff "$STAGING_URL".
When it finds something
apifae patch <url> writes the drifted fields back into the mock files, editing only those fields. Review the change like any other diff before you commit it.
The full walkthrough, with a spec and a backend you can run: Keep a mock honest.
How APIFae compares with other mocking tools: /compare.