ahtishamshahzad Contract Testing
Purpose
Catch API-contract breakage between separately deployed parts (frontend↔backend, service↔service, you↔a partner) in CI — so a provider change that would break a consumer fails the build, not a customer.
When to Use
- When client and server (or two services) deploy independently and must agree on request/response shapes.
- When a mobile client (slow to update) consumes an evolving API.
- Not for a single deployable where API integration tests already exercise both sides in one process.
Inputs
- The contract source of truth (OpenAPI / GraphQL schema —
../../backend/api-contracts). - Consumers and their update cadence (mobile store cycles, partner systems).
Discovery Questions
- What parts deploy independently and could drift out of sync?
- Is there a single contract source, or types hand-copied between repos (drift risk)?
- Which consumers lag furthest (mobile), setting the deprecation window?
Responsibilities
- Anchor tests to the contract source of truth; verify the provider's actual responses conform to it, and that consumers only depend on what the contract promises.
- Choose the approach: schema-conformance (validate live/recorded responses against OpenAPI/GraphQL schema) for simpler setups; consumer-driven contracts (each consumer publishes expectations the provider verifies) when many consumers and independent teams justify the tooling.
- Run in CI on both sides: provider build fails if it breaks the agreed contract; drift between contract and implementation fails (
../../backend/api-contracts). - Enforce the breaking-change policy: additive changes pass; removals/renames/retypes/newly-required fields fail unless versioned with a deprecation window covering the slowest consumer.
- Complement, not replace,
api-integration-testing(behavior) — contract tests check shape agreement, not business correctness.
Required Workflow
- Confirm the contract source of truth and its CI drift check.
- Choose schema-conformance vs consumer-driven per team/consumer count.
- Wire provider-side verification into CI (fail on incompatible change).
- Encode the breaking-change policy + deprecation window.
- Keep contract tests distinct from behavior tests.
Decision Rules
- One source of truth — hand-synced types across repos are the drift this skill exists to kill.
- Schema-conformance is enough for one-team, few-consumer setups; reach for consumer-driven tooling only when the coordination cost is real.
- The slowest consumer sets the deprecation window (mobile release cadence).
- A breaking change without a version bump fails CI — that's the whole point.
Rules
- Contract changes reviewed as part of code review (
../../code-review). - Generated/contract artifacts never hand-edited.
- Deprecations documented for consumers before removal.
Anti-Patterns
- Relying on manual coordination ("tell the mobile team") instead of a failing test.
- Copy-pasted types between client and server repos.
- Treating contract tests as behavior tests (or vice versa).
- Silent breaking changes shipped because nothing checked the contract.
- Deprecation windows shorter than the mobile release cycle.
Validation Checklist
- Contract source of truth confirmed; drift check in CI.
- Approach chosen (schema-conformance vs consumer-driven) with reason.
- Provider-side CI verification fails on incompatible change.
- Breaking-change policy + deprecation window encoded.
- Distinct from behavior tests.
Definition of Done
Contract verification wired into CI on the provider side against a single source of truth — incompatible changes fail the build, additive ones pass, and the deprecation window covers the slowest consumer.
Related Skills
../../backend/api-contracts, api-integration-testing, ../../backend/rest-api-design, ../../backend/graphql-api-design, ../../code-review, ../../devops/ci-cd.
Related Knowledge
../../../knowledge/ (consumers, release cadences).
Related References
../../../references/testing/ (contract patterns, when populated).
Context Loading Guidance
- Requires: contract source, consumer list + cadences.
- Does not require: business-logic internals, full app source.
- May load:
../../backend/api-contracts,api-integration-testing. - Stop when: provider-side contract verification gates CI.
Token Efficiency Guidance
Reference the contract file, not its contents; the compatibility policy table (change type → pass/fail) is the artifact.