What you will learn
- How contract tests differ from mocks
- When mocks help and when they mislead
- The build order from mock servers to contract testing
- Why mock drift is the failure mode to design against
What this project is
Modern software is APIs talking to APIs, and development stalls when a needed API is unfinished, flaky, or rate-limited. A testing and mocking platform gives teams stand-in APIs that behave predictably, plus contract tests that prove the stand-ins still match reality.
Mocks are dangerous precisely because they are convenient. A mock that diverges from the real API lets tests pass while production fails, and the team discovers the gap from users. Contract testing is the discipline that keeps mocks honest, by checking provider and consumer expectations against each other continuously.
Core features
- Mock servers with scenario-based responses, delays, and error cases.
- Contract tests verifying consumer expectations against provider behaviour.
- Recorded traffic replay, turning real API calls into mock scenarios.
- Test data management with seeded, isolated datasets per test run.
- CI integration running API tests on every change.
- Versioned API definitions driving both mocks and tests from one source.
How it is built
- Mock servers first. Scenario responses for the APIs teams depend on most.
- Contract tests second, checking mocks against real providers on schedule.
- Test data third, with seeded datasets per run.
- CI integration fourth, running API tests on every change.
- Governance last. Versioned definitions and ownership for shared mocks.
Technology considerations
Mock definitions should derive from API specifications where possible, so a spec change updates mocks and tests together. Contract tests need scheduled runs against real providers, since a mock checked once goes stale silently. Test data isolation matters: shared mutable test data makes tests interfere with each other. Costs depend on API counts and test volume; confirm with a quote.
- Mock servers driven by versioned API specifications.
- Contract test runners checking providers on schedule.
- Seeded, isolated test data per run.
- CI hooks running API tests on every change.
Challenges to plan for
- Mock drift. Mocks diverge from real APIs, so contract tests must run continuously, not once.
- Over-mocking. Mocking everything hides integration problems, so critical paths still need real-API tests.
- Flaky external APIs. Rate limits and unstable sandboxes break tests, so recorded replay helps for routine runs.
- Test data coupling. Shared test data creates order-dependent tests, so isolation is worth the setup cost.
A worked example
A fintech team builds a payments dashboard that depends on a partner bank's API, whose sandbox is slow, rate-limited, and occasionally down for days. Development stalls whenever the sandbox stalls. The team builds mock servers from the bank's API specification, with scenarios for successful payments, declined cards, timeouts, and rate-limit errors, so developers test every path without the sandbox.
Contract tests run nightly against the real sandbox, checking that the mock scenarios still match the bank's actual behaviour. One night, a contract test fails: the bank changed an error code for declined cards without notice. The team updates the mock and its handling before the change reaches production, instead of learning about it from failed customer payments. Recorded traffic replay keeps routine tests fast and deterministic, while the contract tests keep the mocks honest. The team ships the dashboard on schedule, and the sandbox's unreliability stops dictating their pace.
The fintech team later extends the same approach to its own internal APIs, where consumer-driven contracts between services catch a breaking change in an internal payments service before it reaches staging. The mock servers also become the onboarding tool for new developers, who can run the full dashboard against mocks on their first day without waiting for sandbox credentials. Contract test failures become a normal, unremarkable part of the nightly build, which is exactly what a safety net should feel like.
Who it is for, and its limits
This fits teams building on many internal or third-party APIs, or teams practising consumer-driven development across services.
It does not fit a single API with one consumer, where direct integration tests suffice. It also does not replace end-to-end testing of critical user journeys.
Frequently asked questions
What is contract testing?
Testing that a provider API satisfies the expectations of its consumers, recorded as contracts and checked continuously as either side changes.
When should I mock instead of calling the real API?
When the real API is unfinished, unstable, rate-limited, or costly, and when tests need deterministic error cases.
How is mock drift prevented?
By generating mocks from specifications and running contract tests against real providers on schedule.
What is recorded replay?
Capturing real API traffic and replaying it as mock scenarios, giving realistic responses without live calls.
Should mocks cover error cases?
Yes. Timeouts, rate limits, and malformed responses are the cases that break production most often.
How do mocks stay honest when the real API changes?
Through contract tests that run against the real provider on schedule, checking consumer expectations against provider behaviour and failing loudly when they diverge.