Build a contract test suite

---
name: build-a-contract-test-suite
category: code
description: Build a contract test suite that verifies provider and consumer compatibility across versions, examples, errors, and deployment order. Use when independently released components share an interface.
---

# build-a-contract-test-suite

Test the behavior consumers depend on, including failures.

## When to use

- Use for APIs, events, schemas, files, SDKs, queues, or database views shared across release boundaries.
- Do not let provider mocks become the only evidence of provider behavior.

## Procedure

1. Inventory producers, consumers, versions, environments, owners, and compatibility policy.
2. Define request, response, event, field, error, ordering, auth, timing, and semantic obligations.
3. Capture consumer expectations as minimal versioned examples and invariants.
4. Verify expectations against the real provider implementation in a controlled environment.
5. Add optional, unknown, deprecated, invalid, timeout, pagination, duplicate, and retry cases.
6. Test old consumer with new provider and new consumer with old provider where rollout can overlap.
7. Publish results with artifact versions and block only changes that violate supported contracts.
8. Remove stale contracts through an explicit consumer retirement process.

## Done

- A contract suite records provider, consumers, versions, compatibility rules, success, error, and edge cases
- CI evidence verifies real-provider behavior and supported mixed-version deployment orders