What contract testing is

An API is useful only because other programs rely on it. A web shop's frontend expects GET /api/Products/1 to return an object with a pricethat is a number. A mobile app expects a 404 for a product that doesn't exist, with a message it can show. Those expectations, taken together, are a contract between the API and the programs that use it. Contract testing checks that both sides still keep it. This lesson explains what that means and why ordinary tests miss the bugs contract tests catch.

Running the examples

The tutorial's code is plain JavaScript with no libraries, so every line is readable, including the validator lesson 3 builds. You need Node.js 22 or later. Download the project, unzip it and run:

$ node --version
v24.14.1

$ cd contract-testing
$ npm test
...
ℹ tests 44
ℹ pass 44
ℹ fail 0

The tests read the API's published OpenAPI document and call the API, and only one of them changes anything: it creates a todo and deletes it again.

Provider and consumer

Contract testing has its own two words for the two sides:

• The provider is the API: here, api.testingapis.com.
• A consumeris any program that calls it: a web frontend, a mobile app, another backend service, a partner's integration, or your own test suite.

A contract covers everything a consumer could reasonably depend on:

Why ordinary tests miss contract breaks

Here is how a contract usually breaks:

Monday     The backend team renames a field in GET /api/Products/{id}:  inStock → available
           Their tests pass: they updated them along with the code.
Tuesday    The release goes out.
Tuesday    The shop's product page reads product.inStock, gets undefined,
           and shows every product as sold out.
Wednesday  Someone notices the sales graph.

Nobody did anything careless. The backend's tests were changed along with the code, which is what good tests are supposed to do, and so they passed. The frontend's tests use a fake API that still returns inStock, so they passed too. Each side was tested against its own idea of the API, and the two ideas had quietly separated. The bug lived in the gap between them.

A contract test closes that gap by checking both sides against one shared description of the API. If the backend renames inStock, a contract test fails before the release, because the contract still says inStock. The team then decides deliberately: keep the old name, add the new one alongside it, or agree a change with every consumer.

How contract tests differ from other API tests

Contract tests check shapes, not values. They don't care that product 1 costs 249.99, only that priceis there and is a number. That makes them fast, and stable when the data changes, but it also means they don't replace functional tests. A price that is a number and wrong passes every contract test.

Two ways to write the contract down

• Provider-driven. The provider publishes a description of its whole API, usually an OpenAPI document, and that file is the contract. Tests check the real API against the file. Lessons 2 to 6 work this way.
• Consumer-driven. Each consumer writes down the requests it makes and the fields it actually uses, and the provider checks it still meets them all. A change no consumer depends on is free to make. Lesson 7 covers this.

Most teams that do contract testing well use both, and lesson 8 runs them in CI.

A contract that said almost nothing

A contract only protects what it describes. When work on this tutorial began, this API's OpenAPI document listed every endpoint, but here is how many of them it said anything about the response for:

$ node demos/spec-coverage.mjs        # the spec as it was when this tutorial began
spec:        https://api.testingapis.com/openapi/v1.json (OpenAPI 3.0.4)
operations:  400
described:   1 have a schema for their success response
             GET /WeatherForecast

One out of 400, and that one was a leftover from a project template. The schemas existed, but no response pointed to them, because the code returned results the documentation generator couldn't see into. A consumer could rely on the spec for which endpoints existed and nothing about what came back. So the first contract test this tutorial ran found its first bug: the contract itself was too weak to test against. The API was fixed for the products, posts and todos resources, which the rest of the tutorial uses:

$ node demos/spec-coverage.mjs        # after the fix
spec:        https://api.testingapis.com/openapi/v1.json (OpenAPI 3.0.4)
operations:  400
described:   20 have a schema for their success response
             GET /api/Products
             POST /api/Products
             DELETE /api/Products/{id}
             GET /api/Products/{id}
             PUT /api/Products/{id}
             ... and 15 more