Contract Testing

// Definition

Verifying that two services agree on the shape of the messages they exchange. Catches breaking API changes without expensive end-to-end tests across multiple deployed services.

// Why it matters

Contract testing verifies that a provider and consumer agree on the shape of their API — without spinning up both. It catches the integration break that unit tests miss and E2E tests catch too late/slowly. QA value is speed + precision: a contract failure tells you exactly which field changed, in CI, before deploy.

// How to test

// Consumer-side: assert the response matches the agreed schema
cy.request('/api/users/1').then((res) => {
  expect(res.body).to.have.all.keys('id', 'name', 'email', 'role')
  expect(res.body.id).to.be.a('number')
  expect(res.body.role).to.be.oneOf(['admin', 'editor', 'viewer'])
})
// Dedicated tools (Pact) formalise this as a shared contract both sides verify.

// Code Example

import { PactV3, MatchersV3 } from '@pact-foundation/pact';

const provider = new PactV3({ consumer: 'web', provider: 'api' });

provider
  .uponReceiving('a request for tools')
  .withRequest({ method: 'GET', path: '/tools' })
  .willRespondWith({
    status: 200,
    body: MatchersV3.eachLike({ id: 'cypress', name: 'Cypress' }),
  });

await provider.executeTest(async (mock) => {
  const res = await fetch(`${mock.url}/tools`);
  expect(res.status).toBe(200);
});

// Related terms

• REST

  Representational State Transfer — an architectural style for HTTP APIs where resources are addressed by URLs and manipulated via standard HTTP verbs (GET, POST, PUT, DELETE). The dominant API style for over a decade.

• GraphQL

  A query language and runtime for APIs where clients specify exactly which fields they want in a single request. Replaces multiple REST endpoints with one flexible endpoint and a typed schema.

• Endpoint

  A specific URL exposed by an API that accepts requests and returns responses. Defined by its path, HTTP method, and contract.