API Mocking and Service Virtualization

Why it matters

Real dependencies often stop testing: another team's service is not built yet, a third-party sandbox is down, calls cost money or hit a rate limit, and shared data changes between runs. Tests that depend on them fail for reasons unrelated to the code under test.

Above all, doubles make error paths testable. A real payment provider will not return a 503, a 429 or a reply after 15 seconds on request, yet those are the moments when customers are charged twice or orders are lost. The price: a double is only as good as its resemblance to the real API; a wrong one gives green tests and failures in production.

Stubs, mocks and fakes when the dependency is an API

The system under test sends real HTTP requests, and something other than the real service answers them. Only configuration changes: the dependency's base URL, for example PAYMENT_API_URL, points to the double in CI and to the real provider in staging. "Mock" is used loosely in API work, and a "mock server" is usually configured as a stub, so ask what the double actually does:

• Stub: returns a canned response for each request it matches, such as GET /v1/rates/RUH → 200 {"fee": 18}, and remembers nothing. The test checks your system's result, such as the fee shown (state verification).
• Mock: answers like a stub, but is also pre-programmed with expectations about the requests it must receive, such as exactly one POST /v1/charges with an Idempotency-Key header; the test fails if the call is missing, repeated or different (behaviour verification). A test that inspects the request log afterwards uses the double as a spy.
• Fake: a simplified working implementation with its own state, usually in memory: POST /v1/orders stores an order and GET /v1/orders/{id} returns it. Useful when calls depend on each other, but its own logic can be wrong.
• Service virtualization: a simulated dependent system in a shared test environment, often recorded from real traffic, with state, delays and failures, sometimes beyond HTTP. It costs more to build and maintain, and a platform or test-environment team often owns it. Some teams use the term as a synonym for API mocking; the difference is scope and ownership.

Try it: Mock API Response Generator Try it: Mock JSON Generator

When to mock, and when to use the real API

Decide per dependency and per test level: replace what you do not own or control, and use the real thing for what the test must prove. Never replace the system under test itself. Keep the real dependency or the provider's sandbox for system integration and end-to-end checks. Never stub the security control under test: a stub that accepts any token proves nothing about authentication. A double pays off when:

• The dependency does not exist yet: a stub built from an agreed OpenAPI document lets testing start early.
• It is a third party that is slow, charges per call, limits the request rate or has no usable sandbox.
• You need responses the real service will not give on demand: 429 with Retry-After, 503, a timeout, a body that is not JSON, an empty list.
• Tests must be fast and repeatable in CI, whatever the state of shared environments.

Worked example: payment failures at checkout

The payment provider's sandbox returns only a successful charge or a declined card. Requirement R-21: "A declined card leaves the order UNPAID and shows the reason. If the provider is busy or unavailable, the order stays UNPAID and the customer is asked to try again later. With no answer within 10 seconds, the order becomes PAYMENT_PENDING; its charge status is checked later, and it is never charged again." The test environment points the payment base URL at a stub server, one stub per card token:

• Only the first two rows can be produced with the sandbox; without stubs, the other four would most likely be seen for the first time in production, by real customers.
• tok_slow needs more than a stub: besides the order status, the test verifies that exactly one charge request arrived, even after the customer presses Pay again, either as a mock expectation or by reading the request log afterwards (a spy).
• tok_broken is not in R-21: it came from the tester's question "what if the body is not JSON?", and the team chose to treat it like an unavailable provider.

Stub server for the payment provider (test environment only)
Request: POST /v1/charges; the stub is chosen by "token" in the body

token         Stub response                         Expected in our system
------------  ------------------------------------  ------------------------------
tok_ok        201 {"status":"captured"}             order PAID, receipt sent
tok_declined  422 {"error":"card_declined"}         order UNPAID, reason shown
tok_busy      429, Retry-After: 30                  order UNPAID, "try again later"
tok_down      503 {"error":"unavailable"}           order UNPAID, "try again later"
tok_slow      201, but only after 15 s              at 10 s: PAYMENT_PENDING and
                                                    exactly one charge request
tok_broken    200, body is an HTML error page       handled as unavailable, logged

Try it: API Status Code Simulator Try it: Mock Error Response Generator

Risks of mocking and how to contain them

A double is an assumption about another system, written as test code. Each risk is a way that assumption goes wrong:

• Drift: the provider renames a field or changes its error format, the double keeps the old answer, and production fails while the tests stay green. Validate stub bodies against the provider's contract, and run contract tests that send the same requests to the provider's sandbox and compare its answers with the doubles', on a schedule such as once a day and at each provider release. Consumer-driven contracts that the provider verifies close the gap from the other side.
• Unrealistic behaviour: doubles answer instantly and never rate-limit. Add realistic delays where timing matters, and keep a few tests on the real service.
• Over-mocking: so many doubles that only the doubles are tested, or expectations so strict about headers and call order that harmless changes break tests.
• Leaks: a stub URL left in a staging or production configuration. Each environment should state which dependencies are real, and deployment checks should confirm it.
• Recorded data: traffic recorded for service virtualization can contain personal data and access tokens; mask it before storing or sharing it.

Try it: API Schema Validator Try it: Response Contract Comparator

Frequently asked questions

References

• ISTQB Certified Tester Foundation Level (CTFL) v4.0ISTQB · 2023The foundation syllabus of software testing: test levels and types, test design techniques, test management and tools.
• Test Double (Martin Fowler)martinfowler.com · 2006Gerard Meszaros's vocabulary for test doubles — dummy, fake, stub, spy and mock — as summarised by Martin Fowler.
• Mocks Aren't Stubs (Martin Fowler)martinfowler.com · 2007The difference between state verification and behaviour verification, and between the classical and mockist styles of test-driven development.
• Contract Test (Martin Fowler)martinfowler.com · 2011Contract tests: periodic checks that the calls made against a test double return the same results as the same calls to the real external service.