Mock, sandbox or real service: how to test external integrations
A payment gateway or partner API may be slow, unavailable, or capable of creating real side effects. A mock speeds up feedback but cannot show that the real systems understand each other. Use each layer to answer a different question.
Why one testing layer is not enough
A mock is a controlled substitute for the external service. It can return a predefined response or error, or introduce a controlled delay, making timeouts, invalid payloads, and outages repeatable.
Mocks are fast and deterministic: the same input can produce the same condition. They prove only how the application behaves against the team’s programmed interpretation of the interface. A test can pass when the mock uses an outdated field or incorrect status code while the real connection remains broken. Our API testing checklist describes useful error conditions to cover at this layer.
A sandbox is a test environment operated by the provider. You interact with the provider’s software and authentication mechanisms using test accounts, without the agreed production side effects. It is suitable for checking request formats, credentials, callbacks, and the states that the provider makes available.
A sandbox may not reproduce production data, timing, fraud controls, or every feature. Some outcomes may themselves be simulations. Payment integrations need an explicit understanding of what a gateway’s test mode cannot prove rather than treating one sandbox transaction as evidence for the live process.
The real service gives stronger evidence that the current configuration and connection work for a controlled scenario. A check may modify data, send messages, consume a quota, or fail outside your product. Run it narrowly and safely, agree it with operations, and limit its frequency according to its side effects.
Choose according to the question, not apparent realism
State what the result needs to demonstrate before choosing a layer:
- How does the application respond to an error or slow dependency? Use a mock so the condition is deliberate and repeatable.
- Does the provider accept the request we send? Exercise the sandbox and add a contract check.
- Do both sides conform to the same agreement? A contract test compares recorded client expectations with provider behaviour in the covered scope.
- Does the critical journey work with the current live configuration? Consider a small, non-destructive check of the real service or carefully designed production monitoring.
Also consider test-data ownership, permitted side effects, call limits, environment availability, and required feedback speed. The most realistic test is not automatically right for every change.
Combine layers to reduce blind spots
Begin with broad mock coverage: success, known errors, a timeout, invalid data, retries, and partial completion. These scenarios can run without the partner.
Anchor the mock in an interface agreement. An OpenAPI schema can check message shape, while a consumer-driven contract records the client’s specific expectations. Tools such as Pact can verify recorded interactions against the provider implementation. A contract knows only about covered interactions, however, and does not replace the wider integration strategy.
Keep a representative successful journey and the important failure states supported by the sandbox. Add only essential checks against the real service. Label results so the team can distinguish a product defect from an unavailable dependency, as it must when stabilising intermittent tests.
Important limitations
Do not build a mock by copying one successful response without its rules. Preserve required fields, types, state transitions, and errors on which the application relies. When the contract changes, update the agreement first and then adjust both the mock and its tests.
A production check must not send uncontrolled customer emails, charge customers, or alter stock. Use dedicated accounts, recognisable test data, idempotent operations where the interface supports them, and an agreed clean-up process. Even a safe successful run covers only its selected state, not every production condition.
What you gain
- Fast feedback across a broad set of failure scenarios.
- Earlier warning when a mock and the real interface begin to diverge.
- Less dependence of routine tests on a third party’s availability.
- Proportionate evidence of the real connection without unnecessary live side effects.
Next step
List your external dependencies and ask three questions about each one: which failure must the application handle, which agreement must remain compatible, and what can only be demonstrated through a real connection? Assign each question to the lowest layer that can answer it credibly, then document the limitations that remain.