Contract testing: Test strategy and fixtures

Consumer expectations, including authentication and error shapes, are verified against the real provider in CI before merge; HTTP status codes cannot be mocked away on either side of the contract.

Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.

Decision

Service interfaces are governed by consumer-driven contracts: the consumer publishes the requests it will send and the responses it requires, including authentication headers and error bodies. Provider CI verifies those expectations against the running provider before a breaking change may merge. Tests that replace status codes with always-200 mocks are not contract tests.

Scope

• HTTP or message consumer-provider pairs, contract publication, provider verification in CI, and classification of breaking versus additive change.
• Authn/authz header presence, error object shape, and success payloads.
• Backend services that evolve independently.

Outside this block

• Full end-to-end product journeys and UI snapshot tests.
• Event schema evolution for async topics, which has its own compatibility rules.

Contract

• Each consumer contract names provider, operation, required request headers, and allowed status codes including at least one documented error status.
• Provider verification fails the merge if a required field disappears, a status code changes meaning, or an error code is renamed.
• Authentication schemes used in production (for example bearer access tokens) appear in the contract as required headers or claims, not as omitted happy-path only.
• Error responses keep a stable machine code and HTTP status class agreed in the contract.
• Additive optional response fields are compatible; removing or retyping a consumed field is breaking.
• Contract tests execute against the provider process or a recorded provider fixture that still returns real status codes, never a stub that maps all failures to 200.

Implementation

• Publish contracts from consumer tests as artifacts the provider pipeline fetches on handler, serializer, or auth changes.
• Include unauthorized and not-found operations in the default consumer suite.

Failure handling

• If the provider cannot start, the pipeline fails rather than skipping contracts.
• Breaking changes bump the API version and migrate consumers; they do not weaken the old contract in place.

Verification

• Remove a consumed field on a branch and assert provider CI fails.
• Replay unauthorized requests and expect the contracted 401 or 403 body.

The executable-looking examples in this package are fixtures and acceptance contracts. Run python tools/validate.py from the collection root to check package structure and metadata; then implement and execute the scenarios in the target repository.

Adoption assumptions

• Names and numeric values in example.yaml are an adoption profile, not universal defaults.
• The adopting team must map actors, data classes, error vocabulary, and ownership to its system.

References

• Consumer-driven contracts are described by Fowler at https://martinfowler.com/articles/consumerDrivenContracts.html.
• HTTP interface descriptions may follow OpenAPI 3.1; this block does not require a specific broker vendor.