How to protect Python integrations against schema drift, error-shape changes, timeout assumptions and provider behaviour that mocks never reveal.
Record the observable boundary, test provider-owned examples where possible and make compatibility failures visible before deployment.
Describe observable behaviour
An integration contract includes status codes, required and nullable fields, pagination, rate limits, authentication errors, timeouts and retry semantics. Generated schemas are useful, but a schema rarely captures all operational behaviour.
Keep the adapter responsible for translating provider details into a stable domain result. Do not spread provider-specific error shapes across every service layer.
Use more than one kind of evidence
Consumer-driven contracts protect what your service actually relies on. Provider examples, sandbox checks and a small set of live canary calls add evidence about the other side of the boundary.
Do not run live tests on every pull request if the provider is costly or nondeterministic. Separate fast contract fixtures from scheduled compatibility checks and make staleness visible.
Test change and failure
A contract suite should fail when a field becomes nullable, an error payload changes or pagination ordering becomes unstable. It should also verify timeout, retry and rate-limit handling without contacting the provider.
When a provider changes, record whether the adapter can absorb the change, needs a coordinated release or must temporarily degrade the feature. Compatibility is a decision, not just a red build.
Evidence to take into review
- The integration contract includes errors and operational behaviour.
- Provider details are isolated behind an adapter.
- Fast fixtures and scheduled compatibility checks are separated.
- Schema and pagination drift fail before release.
- Provider changes have an explicit compatibility decision.
Explore all engineering notes.
Use PRODUCTION-7 to connect this concern with the other dimensions of a trustworthy backend.
View all articles Get the checklist