Contract Tests Between Services

1. 1
   Consumer writes a test against a stub

   Declares the request it sends and the fields it reads from the response.

   fails by Asserting on fields it does not use, over-constraining the producer forever.

2. 2
   Running the test emits a contract

   Produces a machine-readable artifact of that interaction.

   fails by Hand-writing the contract instead, so it describes intent rather than usage.

3. 3
   Consumer publishes it, tagged with its version

   Uploads to a broker or shared repository, associated with the deployed version.

   fails by Publishing from every branch, so producers are blocked by experiments.

4. 4
   Producer verifies in its own CI

   Replays every published request against the real implementation and checks the declared fields.

   fails by Verifying against a mock of itself, which proves nothing.

5. 5
   Build fails on a broken contract

   Names the consumer, the interaction and the field that disappeared.

   fails by Being a warning, which is ignored, or a nightly job, which is read too late.

6. 6
   Deploy gate checks compatibility

   Confirms this producer version satisfies every consumer version currently deployed.

   fails by Checking against latest rather than deployed, so a stale consumer still breaks (API Ownership and the Catalog).

// Rejects anything not in the schema, and any unseen enum value.
const Order = z.object({
  id: z.string(),
  total: z.number(),
  status: z.enum(['pending', 'paid']),
}).strict()                       // <- unknown field => throw

const order = Order.parse(await res.json())

// Producer adds 'currency'      -> every request throws.
// Producer adds status 'refunded' -> every refunded order throws.
// Both are additive changes. Both are outages.

const Order = z.object({
  id: z.string(),
  total: z.number(),
  status: z.string(),              // parse as string; interpret separately
}).passthrough()                   // <- unknown fields preserved, not fatal

const order = Order.parse(await res.json())

const known = ['pending', 'paid'] as const
type Known = (typeof known)[number]
const status: Known | 'unknown' =
  (known as readonly string[]).includes(order.status) ? order.status as Known : 'unknown'

// Producer adds a field   -> ignored.
// Producer adds an enum   -> falls into 'unknown' and is handled explicitly.
// Producer REMOVES 'total' -> still fails, correctly: the contract test caught it first.

Tolerance narrows the set of changes that require coordination down to removals and type changes — exactly the set contract tests are good at catching. A strict consumer makes every addition a coordinated release, which is the cost that makes teams stop evolving the API at all.