Design a contract testing strategy

---
name: design-a-contract-testing-strategy
category: code
description: Design contract testing across schemas, examples, provider behavior, consumer assumptions, compatibility, versions, and deployment gates. Use when independently released systems must integrate safely.
---

# design-a-contract-testing-strategy

Test the assumptions consumers rely on, not only the provider’s schema.

## When to use

- Use for APIs, events, files, webhooks, SDKs, databases, or command interfaces.
- Do not expose production secrets or customer payloads in fixtures.

## Preconditions

- Inventory providers, consumers, owners, contracts, versions, environments, release cadence, and critical journeys.

## Procedure

1. Define normative schema, semantics, errors, ordering, defaults, retries, idempotency, and side effects.
2. Inventory consumer assumptions and classify supported versus accidental behavior.
3. Create minimal privacy-safe valid, boundary, invalid, and historical examples.
4. Run provider verification against published consumer expectations.
5. Test additive and breaking changes, unknown fields, version skew, and deprecation.
6. Separate contract, integration, and end-to-end responsibilities.
7. Gate publication and deployment with attributable results and override authority.
8. Monitor real compatibility signals and retire contracts only after consumer evidence.

## Failure plan

- Preserve the old contract or version when a relied-on behavior cannot migrate safely.

## Worked example

A provider adding an enum value passes its schema but fails a consumer that treats unknown values as impossible, prompting compatible parsing before rollout.

## Done

- A contract-testing plan records semantics, consumers, examples, versions, suites, gates, ownership, and retirement
- Provider, consumer, historical, unknown-field, error, side-effect, skew, and deployment-gate tests verify compatibility