A hand-written mock starts its life as an act of good engineering. Someone reads the API documentation, writes a JSON fixture that matches the documented response shape, wires it into the test suite, and pushes the commit. The tests pass. The CI is green. The mock accurately represents the API on that day.
Six months later, it does not.
This is not a failure of discipline or care. It’s a structural property of the approach. Mocks that are maintained separately from the API they represent will diverge from that API over time. The question isn’t whether your mocks have drifted. It’s whether you’ll find out before or after a production incident.
The lifecycle of a hand-written mock
The divergence happens in stages, and each stage is individually plausible.
On day one, the mock is written from the API documentation or from a real response someone captured manually. It’s accurate because the person writing it has just looked at the real thing.
By month one, the upstream API has shipped a small update: a new optional field, a change to how one enum member is spelled, a new error code for a previously unhandled edge case. None of these are breaking changes from the upstream API’s perspective. Your mock doesn’t have them. The tests still pass.
By month three, someone on your team updates a code path. They update the mock to match the new behavior. But they only update the mock for the scenario they’re working on. The other fixtures, the ones covering adjacent paths, still have the old shape.
By month six, the cumulative gap between your mocks and the real API is significant. Your tests pass reliably. Your CI is green. And the next time an upstream API behavior change hits a code path that only your mock tests cover, you won’t know until it reaches production.
The specific drift modes
Understanding how drift accumulates makes it possible to defend against it. The failure modes are consistent.
Upstream adds fields. Upstream adds an optional metadata object or a new status field to responses. Your mock doesn’t have it. If your code ignores unknown fields, the tests still pass and the mock silently omits data your code should be handling. If your code deserializes into a strict schema, the mock may continue to produce correct output while real traffic now fails deserialization because the new field violates your schema unexpectedly.
Upstream renames or changes field semantics. A field named amount changes from representing cents to representing the smallest currency unit (which is the same for EUR, different for JPY). A field named status gains new valid values: "pending_review" where previously only "pending" existed. Your mock returns the old values. Your code only handles the old values. Production traffic now includes values your code doesn’t handle.
Enum values grow. This is the most common and most dangerous drift mode. Enums in API responses grow over time: payment methods, error codes, document types, notification categories. Hand-written mocks typically include the enum values that existed when the mock was written. Switch statements in application code cover those values. When a new enum value appears in production traffic, your switch has no branch for it and your mock never exercises that gap.
Error response shapes change. Error handling is almost always underrepresented in mocks. The happy path gets a fixture; error cases get a minimal {"error": "something went wrong"} that roughly approximates what the API used to return. When the upstream API starts returning structured error objects with machine-readable codes, retry hints, or validation details, your error-handling code is working against a fiction.
Pagination and limits shift. An API that previously returned up to 100 items per page now caps at 50. Your mock returns 100 items; your code assumes it can get all records in one call; production requests truncate silently. Or: a new next_cursor field appears in paginated responses. Your mock doesn’t have it. Your code never learns to follow it.
The real world sends payloads you didn’t imagine. This is the root cause underlying all the others. Hand-written mocks are written by people who understand the happy path. They reflect the response shapes that seemed likely, not the response shapes that production traffic actually produces. Consider an API that returns null for an optional nested object when the user has no billing address, a float value where the docs claim an integer, or a unicode character in a field your regex doesn’t expect. All of that appears in production traffic. None of it appears in mocks.
Why green CI doesn’t protect you
The insidious part of mock drift is that it doesn’t produce test failures. It produces false confidence.
When a mock drifts from reality, the tests that use it are still testing something: how your code behaves against the old version of the API. That test is internally consistent: the mock returns value A, your code handles value A, the assertion passes. Nothing is broken in the test, because the test has silently become a test of a different contract than the one your production system operates on.
This is the structural problem. Unit tests with mocks verify consistency between your code and your mocks. They don’t verify that your mocks match the real world. If both your code and your mocks are wrong in the same way, the test passes and the production incident is waiting.
The gap is only visible when the test environment and the production environment diverge, which is exactly the scenario test suites are supposed to prevent.
The mitigation ladder
There’s no single fix, but there’s a hierarchy of approaches that provide progressively stronger guarantees.
Contract tests (consumer-driven contract testing, typically with tools like Pact) allow the consumer and provider of an API to agree on a shared contract. The consumer defines which request/response shapes it depends on; the provider runs a verification suite against those contracts. This catches breaking changes before deployment, assuming the provider participates. It works well for APIs you own on both sides or where you have a close relationship with the upstream team. It doesn’t help when you’re consuming a third-party API whose team isn’t running your contract suite.
Schema validation in tests means running your test fixtures through the same validation layer that production traffic passes through. It catches the cases where a mock’s shape is technically valid JSON but doesn’t match the schema the API actually produces. If you have an OpenAPI spec for the upstream API, validating your fixtures against it during the test run will flag fixtures that have diverged from the spec. This requires the spec to be accurate and up to date, which is a separate maintenance burden.
Periodic re-recording from real traffic is the most effective mitigation for APIs where the upstream team publishes an accurate spec irregularly or not at all. Record real API responses, apply masking, and replace fixtures regularly. The cadence depends on how often the upstream API changes: weekly for fast-moving APIs, monthly or per-release for stable ones. This ensures your fixtures periodically re-sync with production reality rather than drifting indefinitely from it.
Regenerating fixtures from production captures rather than hand-maintaining them removes the maintenance burden entirely. If fixtures are generated from masked captures of real traffic, they reflect what the API is actually returning today, including new fields, new enum values, and edge cases from real requests. The generation step replaces the editing step; updating your fixtures means capturing new traffic, not opening JSON files.
The case for capture-based fixtures
The fundamental issue with hand-maintained mocks is that they model the API based on someone’s understanding of it. That understanding is correct at a point in time and becomes increasingly wrong as the API evolves.
Fixtures generated from real traffic captures model the API based on what it actually does. The representation is continuously anchored to production behavior. New optional fields appear in fixtures because they appear in production responses. New enum values appear in fixtures because real traffic includes them. Unusual payload shapes appear because real requests produced them.
The fixtures preserve the structural shapes, not the personal data values, which are masked before capture. The field names, nesting levels, value types, and edge-case shapes that matter for test coverage are all there. A fixture library built from captures grows more comprehensive over time as production traffic exercises more of the API’s surface area, without any manual maintenance work.
The tradeoff is instrumentation overhead and a cold-start period. You need to deploy capture middleware to a production or realistic staging environment and wait for enough traffic to accumulate before the fixture library is representative. For APIs that see significant traffic, this period is short. For internal APIs with low volume, synthetic generation may still be necessary for the long tail of scenarios.
The decision point is usually: how much API surface area do you need to cover, how often does the upstream API change, and how much ongoing maintenance can you sustain? For narrow, stable APIs you own on both sides, hand-written mocks with contract tests are manageable. For external APIs that evolve independently of your release cycle, the maintenance cost of hand-written mocks is a tax that compounds indefinitely.
Where Stubsmith fits
Stubsmith’s approach to this problem is to automate the capture-and-regenerate loop. Its Express middleware captures real API traffic within your infrastructure, applies masking rules at the capture point, and stores masked bodies and structural fingerprints. Fixtures are generated from those captures rather than written by hand. Fingerprint deduplication groups identical traffic shapes, so the fixture library accumulates canonical examples of each unique request/response shape rather than redundant copies.
The result is a fixture library that stays anchored to production behavior as the upstream API evolves, not because someone remembered to update it, but because the generation step pulls from recent traffic. The docs at docs.stubsmith.dev cover the Express middleware setup; pricing has plan details.
Regardless of what tool or approach you use, the underlying principle is the same: mocks that aren’t continuously validated against or regenerated from real API behavior will drift. The question is how quickly and how painfully you find out.