Use a contract test when the risk is that a service or API you call, or call you, has changed its messages. Use an integration test when the risk is that your own components no longer work together after the upgrade. For a library you embed, integration tests matter more. For a networked dependency, contract tests earn their keep.
Definitions
Contract test. A test of an integration point that checks each side in isolation against a shared, written understanding of the messages. Pact's documentation describes contract tests as asserting that inter-application messages conform to a shared understanding documented in a contract. Martin Fowler describes them as checks that calls against your test doubles return the same results as calls to the real external service.
Integration test. A test that runs several real components together, such as your code, a database and a queue, to prove the wiring works. Pact's documentation calls the alternative of relying on integration tests alone expensive and brittle for service to service checks.
Test double. A stand-in for an external service so your tests are fast and stable.
Which one for which upgrade
| What you upgraded | Main risk | Better fit |
|---|---|---|
| A library compiled into your app (parser, ORM, auth helper) | Behavior change inside your process | Unit and integration tests |
| An SDK or client for a remote API | Request or response shape changed | Contract test against the API |
| A shared internal service you depend on | Another team changed messages | Contract test run by both sides |
| A message queue client or schema library | Serialized messages no longer match | Contract test on messages, plus integration |
| A framework major version | Many small behavior changes | Integration and smoke tests |
The pattern: the further across a network boundary the change sits, the more a contract test helps. The deeper inside your process, the more integration tests help.
How a contract test protects an upgrade
Suppose you upgrade an SDK that wraps a payment or identity API. Your unit tests use a double of that API, and they pass, because the double still returns the old shape. Fowler's point is that this raises the question of whether the double still matches the real service. A contract test answers it: it replays the interactions against the real provider, or a provider stub verified against the contract, and fails when they diverge.
Fowler adds that such tests need not run on every deploy. They follow the rhythm of change in the external service, so running once a day is often plenty. A failure should trigger a task to get things consistent again, and it may start a conversation with whoever maintains the external service, rather than automatically breaking the build.
A practical setup for an upgrade pull request
- List the external services the upgraded package talks to.
- For each, check that you have a contract or recorded interaction, and run it against the upgraded build.
- Run integration tests that use real instances of your database and queue, not doubles.
- Add one smoke test across the whole path. See what a smoke test should check.
- For security checks that should hold across services, see consumer-driven contract tests for security checks.
Common mistakes
- Treating a green test against a double as proof the real service still agrees.
- Relying on a heavy integration suite alone for a remote API change.
- Letting contract tests rot because failures are ignored. Assign an owner.
Safeguard flags vulnerable and outdated dependencies and opens fix pull requests that pass through your policy gates, and your contract and integration suites are what tell you whether those changes are safe to merge. Free scan: gold.safeguard.sh/scan.
Quick check
Do contract tests replace integration tests?
No. They check the agreement between two sides, not that your whole system works wired together. Use both, with fewer broad integration tests.
Do I need a contract test for an in-process library?
Usually not. There is no network boundary, so integration and unit tests cover the risk better.
Sources
Last reviewed: 19 October 2026.
