Contract Tests

1. 1
   Consumer declares

   Writes only what it actually relies on: "reserve(sku, 2) returns a reservation with an id and a status of HELD".

   fails by Declaring the whole provider surface, which freezes everything and gives the provider no room (API Stability)

2. 2
   Consumer verifies its double

   Runs the expectations against the double it uses in its own tests, so the double is proven to satisfy them.

   fails by Stopping here — this is a mock with paperwork and checks nothing about reality

3. 3
   Contract is published

   The expectations are stored somewhere the provider's build can fetch — a broker, or a file in a shared repo.

   fails by A manual copy step, which decays within two sprints

4. 4
   Provider verifies

   The provider's pipeline replays every consumer's expectations against the real implementation, before merge.

   fails by Running it nightly or post-deploy, which converts prevention into an alert

5. 5
   Deploy gate

   A provider version may deploy only if every consumer version currently in production still verifies against it.

   fails by Treating a red contract as advisory, at which point the whole mechanism is documentation again

Steps one and four carry all the value. If your budget only covers two steps, run the consumer's expectations against the real provider in the provider's build and skip the broker — a directory of JSON files works (Reversible and Irreversible Decisions).

1// what checkout actually relies on — and nothing more
2contract('checkout -> inventory', (inv) => {
3  it('a successful reservation yields an id we can cancel', async () => {
4    const r = await inv.reserve({ sku: 'A1', qty: 2 })
5    expect(r.status).toBe('HELD')
6    expect(typeof r.id).toBe('string')      // shape
7    await inv.cancel(r.id)                  // and the id is usable
8  })
9 
10  it('reserving the same requestId twice reserves once', async () => {
11    const req = { sku: 'A1', qty: 2, requestId: 'r-1' }
12    const a = await inv.reserve(req)
13    const b = await inv.reserve(req)
14    expect(b.id).toBe(a.id)                 // semantics: idempotency
15  })
16 
17  it('insufficient stock is a typed refusal, not an exception', async () => {
18    const r = await inv.reserve({ sku: 'EMPTY', qty: 1 })
19    expect(r.status).toBe('REJECTED')       // semantics: expected failure
20  })
21})
22 
23// NOT in the contract: field order, the exact wording of messages,
24// how reservations are stored, anything checkout never reads.

The second and third cases are the ones a schema cannot express and a shared type cannot enforce, and they are the ones that break silently. Note also what is absent: no assertion on internal storage, no assertion on fields checkout does not read — every extra assertion is a freedom the provider loses (Exposing Too Much).