Tutorial
Learn contract testing
An API's clients depend on it to keep its shape: the fields, the types, the status codes and the errors they were built against. Contract testing checks that promise is kept, and catches the changes that would break clients before they ship, including the ones every team's own tests miss.
These lessons start from what a contract is and build up to checks that run on every pull request: reading an OpenAPI document, validating responses, finding drift, spotting breaking changes and verifying consumer contracts. Everything runs against the API at https://api.testingapis.com and its published spec, and the code is plain JavaScript with no libraries, so you can read every line of it. You should be comfortable with JSON and with async JavaScript; the REST tutorial's lesson on schemas and contract testing is a one-page overview if you want one first. Some endpoints need a free account; set your key in TESTINGAPIS_KEY and the example project sends it with every request.
Download the example project
contract-testing-examples.zipThe validator, the diff, a consumer contract and 44 tests. Node.js 22 or later, no dependencies. Unzip and runnpm test.8 lessons3 levelsFree
Beginner
3 lessonsWhat a contract is, how an OpenAPI document writes one down, and how schema validation works.
- 01What contract testing isThe agreement between an API and its clients, the bugs that break it, and how contract tests differ from the rest.
- 02Reading an OpenAPI documentPaths, operations, parameters, request bodies, responses and components, in the API's real spec.
- 03How schema validation worksTypes, required, nullable, additionalProperties, enum and $ref, with a validator small enough to read.
Intermediate
2 lessonsChecking real responses against the spec, and finding the places where the two disagree.
Advanced
3 lessonsChanges that break clients, contracts written by the clients themselves, and checks that run on every change.
- 06Breaking changesWhich changes break clients and which don't, the rule behind them, and a diff that finds them.
- 07Consumer-driven contractsClients write down what they use, the provider checks it, and changes nobody uses stay free.
- 08Contract tests in CITwo checks that stop a release which would break a client, and where each one runs.
Words you'll meet
13 termsEach one is explained properly in its lesson. This list is for looking one up later.
| Term | Meaning | Explained in |
|---|---|---|
| Contract | Everything an API's clients can rely on: endpoints, parameters, bodies, statuses and response shapes | Lesson 1 |
| Provider | The API in a contract | Lesson 1 |
| Consumer | Any program that calls the API, including a test suite | Lesson 1 |
| OpenAPI | The standard format for describing an HTTP API in one document | Lesson 2 |
| Operation | One method on one path in an OpenAPI document, such as GET /api/Products/{id} | Lesson 2 |
| $ref | A pointer from one part of a document to a definition elsewhere, usually in components | Lesson 2 |
| JSON Schema | A vocabulary for describing what a JSON value must look like | Lesson 3 |
| Validator | A program that checks a value against a schema and reports every mismatch | Lesson 3 |
| Drift | Any mismatch between what a spec says and what the API does | Lesson 5 |
| Breaking change | A change that makes a client that worked yesterday fail today | Lesson 6 |
| Expand and contract | Adding the new before removing the old, so a breaking change happens in safe steps | Lesson 6 |
| Consumer-driven contract | A file in which a consumer records the requests it makes and the fields it uses | Lesson 7 |
| Provider verification | Replaying consumer contracts against the real provider | Lesson 7 |
OpenAPI is a specification of the OpenAPI Initiative. Pact, Ajv, Schemathesis, oasdiff and openapi-diff are independent open-source projects, mentioned for reference. This tutorial isn't affiliated with any of them.