Contract testing sequence
Consumer and provider verifying API contracts in isolation.
Microservice teams test their integrations two ways: either spin up the entire stack and pray nothing is flaky, or mock the dependencies and hope the mock matches reality. Contract testing splits the difference. The consumer defines what it expects from the API, tests against that contract in isolation, and uploads it. The provider downloads the same contract and verifies the real service satisfies it. Both sides deploy independently, and a broken contract is caught by CI before anything ships.
The key is the Pact Broker — a shared registry where contracts are stored, versioned, and used to gate deployments. If the consumer changes the contract, the provider's CI fails immediately, so the provider team knows a consumer is waiting for a change. If the provider changes the service in a way that breaks the contract, the consumer's deployment blocks until the contract is updated.
When to use this template
- Microservice architectures — when you have 5+ services, contract testing is the only way to avoid the "test the entire stack" tax.
- Cross-team API design — use this to agree on who owns the contract, when it gets updated, and how changes are communicated.
- Zero-downtime deployments — show this flow to explain why the provider can deploy independently of the consumer: the contract is the shared source of truth.
How to adapt it
Rename "Pact Broker" to your tool — SpringCloud Contract, Prism, or a versioned JSON repo — and add your deployment gates:
- Insert a CI/CD approval step before "Block consumer deploy" if your team requires manual sign-off on breaking changes.
- Add a notification channel (Slack, email) from the Pact Broker when a contract fails, so developers see it immediately.
- Extend the happy path with a test data sync step if your provider needs seed data in a certain state for the contract to pass.
Visual edits let you adjust the sequence and add your tooling without writing syntax, so the diagram becomes your team's runbook for contract changes.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
sequenceDiagram
participant ConsumerTest as Consumer Test
participant Pact as Pact Broker
participant ProviderTest as Provider Test
participant Provider as Provider Service
ConsumerTest->>Pact: Define expected API contract
ConsumerTest->>ConsumerTest: Run in isolation, mock provider
ConsumerTest->>Pact: Upload consumer contract
ProviderTest->>Pact: Download contracts
ProviderTest->>Provider: Verify real service matches
Provider-->>ProviderTest: Response OK or FAIL
alt Verification passes
ProviderTest->>Pact: Mark contract verified
Pact-->>ConsumerTest: Consumer can deploy
else Verification fails
ProviderTest->>Pact: Mark contract broken
Pact-->>ConsumerTest: Block consumer deploy
end
Frequently asked questions
- What is contract testing and why is it better than mocking?
- Contract testing captures the actual API contract — the requests and responses — in a shared format (Pact), then verifies that the consumer's mock matches the provider's real service. Unlike traditional mocks, which can drift from reality, contracts are validated by both sides. The consumer tests in isolation against the contract; the provider confirms the real service respects it. Broken contracts are caught before deployment.
- What is Pact and how does it work?
- Pact is a contract testing framework that records API interactions as JSON contracts, then plays them back to verify both consumer and provider. Each side runs independently: the consumer writes code against the mocked contract, the provider runs the same contract against the real service. The Pact Broker is the central registry where contracts are stored and versioned, so CI/CD can check before deploying whether a change breaks downstream consumers.
- Why do consumers and providers test in isolation?
- Because integration tests are slow, flaky, and require the entire stack running. Contract testing splits the work: the consumer tests 'if the API returns X, does my code handle it?' The provider tests 'when I receive request X, do I return the response the consumer expects?' Both run in seconds, in parallel, and each team can deploy without waiting for the other. Integration tests then verify the end-to-end happy path, not the contract itself.
- How do I start using contract testing if we don't have a Pact Broker?
- Start simple: save your consumer test mocks as JSON files in a git repo that both teams can access. The consumer commits the contract, the provider checks it out and verifies against it in CI. Once that workflow is solid, introduce a Pact Broker for centralized versioning, cross-team discovery, and automatic CI gating. The flow stays the same; the broker just scales it.