In 05-02 we finished openapi.yaml: a complete contract, validated, linted and published at /docs. It is an excellent document. And there is absolutely nothing guaranteeing that the server complies with it.

That sentence is worth pausing on. Right now somebody could add a mandatory field to POST /orders, rename priceEuros to price, or make a 404 return a different body, and it would all go through: the tests from 03-08 would stay green because they check what the code does, not what the contract promises; Spectral would stay green because the YAML is syntactically correct; and the SPA, Aroma Mobile and SwiftShip would find out in production.

That is the problem for this lesson: closing the loop between the contract and reality, in both directions. That real responses satisfy the schema. That a breaking change in the contract is detected before it is merged. And, along the way, that the SPA can be developed against a mock of the contract without waiting for the endpoint to exist.

We are going to add to the project a mock with Prism, schema validation inside the Supertest tests we already have, a breaking-change gate with oasdiff, and an end-to-end purchase journey. And we will see when Pact solves a real problem and when it is expensive over-engineering.

1. Five consumers and an API that changes
2. The contract as an executable artefact
3. Mock servers: Prism on top of openapi.yaml
4. Static versus dynamic mocks, and their limits
5. Doubles on the consumer side: msw in the SPA
6. Doubles on the provider side: nock for SwiftShip
7. Provider contract tests: validating the responses
8. Validating the requests too
9. Detecting breaking changes with oasdiff
10. oasdiff as a gate in continuous integration
11. Consumer-driven contract testing: Pact
12. When Pact pays off and when it is over-engineering
13. The table of test types
14. End-to-end tests: the purchase journey
15. Ephemeral environment, seeded data and isolation
16. The Postman collection in CI with Newman
17. Load and security: where they fit
18. What runs when

The inventory of who depends on the Aroma Store API, and what happens if something breaks:

The Aroma Mobile row is what makes everything in this lesson unavoidable: you cannot deploy to mobile clients. A version of the app from eight months ago is still calling your API, and it will carry on doing so. Any breaking change is permanent for somebody.

And a clarification about "breaking the contract": it takes neither bad faith nor carelessness. The typical breakages are unintentional and subtle:

• A refactor of the mappers makes tastingNotes stop appearing when empty, instead of returning [].
• An optimisation changes the order of the results and a consumer was relying on it.
• Somebody adds .strict() to an input schema and an old app that was sending an extra field starts receiving 400.
• An enum gains a new value (roast: "very_dark") and the generated TypeScript client from 05-02 does not account for it.

None of these is caught by reading the diff. They are caught with tools.

The idea that organises the lesson: openapi.yaml is not documentation, it is code. Everything that can be derived from it:

Seven uses of one file. Each of them makes maintaining it badly more expensive and maintaining it well more profitable, which is exactly the incentive you want.

A concrete situation: the SPA team has to build the "my orders with shipment detail" screen, which needs a GET /v1/orders/{id}/shipment that does not exist yet. Without a mock, they wait two weeks or invent data that later does not match.

Prism (from Stoplight) brings up an HTTP server that implements your specification:

That body comes from the firstPage example we wrote in 05-02. Here you see why we insisted that the examples be consistent: they are what the front-end team consumes for two weeks, and examples with absurd data produce an interface designed for absurd data.

Important Prism options:

That last one is what turns the mock into something serious:

Without this, the front end lays out the happy path and discovers in production that it never thought about the insufficient-stock screen. With this, every error state can be tried in the browser on day one.

And --errors gives an unexpected gift: it validates the consumer. If the SPA forgets the Idempotency-Key, the mock answers 422 in development, not in production.

We add the scripts to the project:

Prism has a second mode worth mentioning, prism proxy, which forwards requests to the real API and validates both directions against the specification, reporting every deviation. It is a cheap way to audit an entire staging environment.

Dynamic mocks have one very specific and valuable use: breaking assumptions. If the SPA fails with --dynamic, it was assuming something the contract does not guarantee —that tastingNotes is never empty, that total is less than 1000, that names are short. That failure in development is a failure avoided in production.

The limits of any mock, and they must be kept firmly in mind:

1. There is no business logic. The mock accepts an order for 500 units of a coffee with 120 in stock. It will never return insufficient_stock unless you ask for it with Prefer.
2. There is no state. You create an order with POST and GET /orders still returns the same old example. Complete journeys cannot be tested this way.
3. There is no real authentication. The mock validates neither tokens nor permissions.
4. A passing mock proves nothing about the real API. It is the most dangerous trap: the front end is all green against the mock and fails against the real server.

Hence the rule: the mock unblocks parallel development; it replaces no integration test. And the moment of connecting the SPA to the real API should come as early as possible.

Prism is a separate process, useful while developing. For the front end's automated tests you need something that runs inside the test process: Mock Service Worker (msw), which intercepts requests at the network level without the application code noticing.

onUnhandledRequest: 'error' is the key option: any request the SPA makes that is not declared fails the test. That is how you discover unexpected calls —analytics, a forgotten endpoint— instead of letting them slip through silently.

The structural risk of msw, and it must be said plainly: these handlers are a third description of the API, written by the front-end team, which can drift from the real one. If the backend changes priceEuros to price, the front-end tests stay green. Two mitigations: generate the handlers from openapi.yaml with tools such as msw-auto-mock, or —what solves the problem at the root— the contract testing in section 11.

The symmetrical problem: our API is also a consumer. It calls SwiftShip to create a shipment and sends it signed webhooks. The tests from 03-08 cannot really call an external service: it would be slow, fragile and would create real shipments.

nock intercepts Node's outbound HTTP requests:

nock.disableNetConnect() is a practice worth adopting always: it guarantees that no test calls the internet. A suite that depends on the network is a suite that fails on Friday afternoons for reasons that have nothing to do with you.

The second test illustrates something only doubles can test: behaviour when a dependency fails. Provoking a real 503 from SwiftShip is impossible; simulating it is trivial.

Now for the core. The question is: do our API's real responses satisfy openapi.yaml?

The technique: extract the contract's schemas, compile them with AJV and validate the response bodies against them inside the Supertest tests that already exist.

New file tests/helpers/contract.js:

And its use in the integration tests, which barely change:

What this catches that the 03-08 tests did not:

The last row matters as much as the others. Remember that in 05-02 we deliberately left the output schemas without additionalProperties: false. If we closed them, every new field would break these tests and the team would end up disabling them.

A warning about coverage: these tests only validate the endpoints and codes you have actually exercised. If you never write a test that provokes the 429, nobody checks that its body satisfies the contract. A cheap way to raise coverage is a wrapper that validates every response automatically:

The contract has two sides. It is also worth checking that the bodies we document as valid really are valid for the server, and that invalid ones are rejected:

This test looks minor and catches a very common, very damaging failure: the documentation example that does not work. It is the first thing anyone integrating with you copies and pastes, and if it fails, your API loses credibility in the first five minutes.

The previous tests check that the server satisfies the current contract. The other question is still open: does the new contract break anyone relative to the previous one?

oasdiff compares two versions of a specification and classifies the differences:

Typical output when somebody slips up:

The classification oasdiff makes coincides, not by chance, with the rules from 02-07:

That table is the operational translation of backwards compatibility. And the important thing is that it no longer depends on the pull request reviewer remembering it: a tool checks it.

Note the nuance in the two enum rows: the direction matters. Widening what you accept is safe; widening what you return can break a client that did a switch over the known values. It is exactly the roast: "very_dark" case from section 1, and that is why the contract in 05-02 warns in the field's description that new values may be added.

To compare you need a reference. Two strategies:

1. Against the main branch, with git show main:openapi.yaml. Simple and good enough for most teams.
2. Against the specification published in production, downloaded from https://api.aromastore.example/docs/openapi.json. More correct —what matters is what is deployed, not what is on main— and somewhat more fragile.

A script that works locally and in CI:

With oasdiff in the pipeline, the conversation changes in nature: instead of arguing in review over whether a change breaks something, the tool says so and the discussion becomes what to do about it. This is the gate 05-05 will integrate into ci.yml.

So far the contract is defined by the provider (us) and consumers adapt. It is the correct model for a public API. But there is another model that solves a different problem.

Imagine Aroma Store grows and inventory-service, payments-service and recommendations-service appear, calling each other. Uncomfortable questions: which fields of inventory-service's response does each consumer actually use? Can I remove one? The honest answer is usually "I do not know, so just in case I will not touch anything", and that is how services fossilise.

Pact reverses the direction: each consumer declares what it needs, and the provider verifies that it delivers.

The consumer side:

The provider side:

What Pact gives that OpenAPI cannot:

• Knowing which fields are really used. If no pact mentions tastingNotes, you can remove it with confidence. It is the only reliable way to know.
• can-i-deploy. Before deploying, the broker tells you whether the version you want to deploy is compatible with the deployed versions of all its consumers. It is a deployment gate with real information, not with guesses.
• Concrete interactions, not abstract shapes. The pact says "when I ask for this, with these parameters and in this state, I need this response".

Pact has a high cost and it is worth being honest about it: you have to operate a broker, write and maintain the stateHandlers —the part that hurts most—, coordinate two repositories and train two teams.

For Aroma Store today the answer is no, and it is worth reasoning it out: two of the five consumers are outside our control (SwiftShip and CataBox), one has permanently old versions (Aroma Mobile), and the API is essentially public. In that scenario, the provider's contract rules and openapi.yaml with oasdiff covers 90 % of the value for 10 % of the cost.

The answer would change the day Aroma Store splits into internal microservices with separate teams. Pact between orders-service and inventory-service would then be exactly the right tool.

And an idea that sums the choice up: Pact answers "what do my consumers need?"; OpenAPI answers "what do I promise?". With known consumers, the first question is more useful. With unknown consumers, it is impossible to answer, and only the second remains.

The "how many to have" row is the testing pyramid from 03-08 seen from the contract's point of view. The rule has not changed: many fast ones at the bottom, few slow ones at the top. What this lesson adds is a new layer —the contract— that is almost as cheap as the integration layer because it sits on top of it: they are not new tests, they are extra assertions in the ones that already exist.

End-to-end tests run against the system as actually deployed: a real process, a real database, real Redis, a real network. They are the only ones that catch a wrong environment variable in staging, a load balancer eating a header, or a migration that was not applied.

And they are expensive and fragile. Hence: few, and well chosen. The criterion is to cover the journeys whose breakage would stop the business. In Aroma Store there is one: the purchase.

Look at the three header assertions in step 2. They are the whole reason this test exists: no in-process test can check them, because in Supertest there is no reverse proxy, no Redis and none of the production environment variables. If the load balancer strips Aroma-Trace-Id or rate limiting is not configured in staging, this is the only thing that catches it.

End-to-end tests have a reputation for fragility, and almost always for the same reason: shared state. Four rules that solve it.

1. An ephemeral environment. The environment is created at the start and destroyed at the end. With docker-compose (which we will see in 05-05) it is straightforward:

--wait waits for the healthchecks to go green: without it, the tests start before the database and fail because of a race, not because of a real fault.

2. Seeded, known data, always fictional. The same npm run seed from 03-05: cof_001, cus_842, ord_5001. Never real customer data in a test environment, not even half-anonymised (04-02 and GDPR).

3. Isolation between runs. If the environment is shared —the usual case with staging— each run must use its own data:

4. Test idempotency. It must be possible to run it twice in a row with the same result. That means not depending on state left behind by the previous run, and cleaning up at the end even on failure (t.after always runs).

Classic mistakes that break these four rules: tests that depend on the order they run in, one that creates a customer with a fixed email and fails the second time as a duplicate, and —the worst— the one that eats cof_001's stock until it runs out and makes every other test fail from that day on.

The collection from 05-01 fits here naturally: it is an end-to-end test with a graphical interface for writing and debugging it.

Newman or end-to-end tests in code? They do not compete; they cover different needs:

The practical recommendation for Aroma Store: Newman for the post-deployment smoke tests —fast, broad, easy for anyone to extend— and code for the purchase journey, which has logic, clean-up and fine-grained assertions.

Two more families, mentioned to place them on the map but not developed here.

Load tests. You already know them from 04-06 with autocannon. They run against staging, never on every pull request —they take time and need a stable environment— but on a schedule, weekly or before a launch. What matters is comparing against a baseline and watching the p99, not the average:

Security tests. Scanners such as OWASP ZAP in baseline mode crawl the API looking for missing headers, insecure configurations and known vulnerabilities; they complement but do not replace the controls from 04-02 or a manual review of the authorisation logic, which is where an API's serious flaws live (no scanner detects BOLA from the OWASP API Top 10). Alongside them, npm audit covers the dependencies, and it is wired into CI in 05-05.

The table that orders everything above in time, and which is the direct lead-in to 05-05:

Two principles hold it up:

• The later a failure is detected, the more expensive it is. A malformed 400 caught on save costs a minute; in production it costs an incident, a rollback and a call from SwiftShip.
• The later in the pipeline, the fewer and slower the tests. Thousands of unit tests on save; five smoke tests in production. Inverting that ratio produces forty-minute pipelines that people learn to skip.

• Trusting the mock as if it were the API. A front end that is all green against Prism can fail entirely against the real server. Connect to the real API as soon as possible.
• Unrealistic examples in the contract. They feed the mock, the documentation and the input tests. An example with "name": "string" produces an interface designed for rubbish.
• Closing output schemas with additionalProperties: false. Every new field breaks the contract tests and the team ends up disabling them. Close them on inputs only.
• Writing the contract tests separately. They duplicate work and get abandoned. Build them as extra assertions inside the integration tests you already have.
• Too many end-to-end tests. A half-hour pipeline, intermittent failures and, three weeks later, somebody marks them as optional. Few and critical.
• Not cleaning up after the end-to-end test. The environment degrades until the tests fail on junk data and nobody knows why.
• Adopting Pact because it sounds good. Without controllable consumers and without discipline in the stateHandlers, it is constant maintenance with no return. Start with OpenAPI and oasdiff.
• oasdiff with no stable reference. Comparing against a moving branch produces noise. Compare against main or, better, against the specification published in production.
• Ignoring the direction of the enum. Adding a value to what you accept is safe; adding it to what you return can break generated clients. Warn about it in the field's description.
• Tip: validate the contract on the error response, not just the success one. Errors are the part of the contract that breaks most, because almost nobody tests them.
• Tip: nock.disableNetConnect() in every suite. A test that calls the internet is a test that will fail some Friday for reasons that are not yours.
• Tip: if a breaking change is unavoidable, make it deliberate. Label the pull request, write the ADR, notify the consumers and apply the deprecation cycle from 02-07. The tool detects; the process decides.

For each proposed change to openapi.yaml, state whether oasdiff breaking would flag it as breaking, justify it from the point of view of a specific Aroma Store consumer, and propose a compatible alternative where it is:

1. Adding the optional roastingCountry field to the GET /coffees response.
2. Changing limit from a maximum of 100 to a maximum of 50.
3. Adding the value decaf to the roast enum in the response.
4. Renaming tastingNotes to notes.
5. Making the method field mandatory in the body of POST /orders/{id}/payment.
6. Adding the 429 response to an operation that did not document it.
7. Changing totalEuros from number to string to avoid floating-point problems.

Write the integration test that verifies that POST /v1/orders satisfies the contract on its error path: when more stock is requested than is available it must answer 409 with code: insufficient_stock, a body satisfying the Error schema and details naming the affected field. Use the matchesSchema and matchesContract helpers from section 7, and add a second assertion checking that the stock has not been modified.

Aroma Store is adding POST /v1/orders/{id}/return: a customer requests the return of a shipped order within the following 14 days; the API validates the window, creates the request, notifies SwiftShip for collection and sends the customer an email.

Design the complete strategy: which tests you would write of each type (unit, integration, contract, e2e, consumer mock), what each one checks, what is simulated at each level, and at which moment in the table in section 18 each one runs. Also state what you would not test and why.

Notes on the design of this test:

• Two items for the same coffee with 99 units each is a better case than a single item of 200: it additionally tests that the service sums the quantities per coffee instead of validating them separately, a real and frequent bug.
• Checking the version as well as the stock catches compensating writes (decrease then increase again), which would leave the stock the same but the version different.
• The test uses matchesSchema('Error', ...) and matchesContract('/orders', 'post', 409, ...): the first validates against the generic schema, the second additionally checks that openapi.yaml documents that 409. If somebody implements the error but forgets to document it, the second fails. That is exactly the drift we want to catch.

Testing strategy for POST /v1/orders/{id}/return

Level 1 — Unit (service, with the in-memory repository; runs on save):

The clock is the key design decision: the window logic must receive the current date as an injected dependency, not call Date.now() internally. Without that, boundary tests are impossible or fragile.

Level 2 — Integration (Supertest over app + temporary SQLite + nock; on save and in the PR):

The two dependency-failure tests are the most valuable and the ones nobody writes: they document that a third party's failure must not undo a customer's operation.

Level 3 — Contract (inside the integration tests; in the PR):

• matchesContract('/orders/{id}/return', 'post', 201, body) on the happy path.
• matchesSchema('Error', body) on the 403, the window 409 and the duplicate 409.
• Before writing the code: add the operation to openapi.yaml, including the new error codes (return_window_expired) in the Error schema's enum. If it is not in the contract, matchesContract fails, and that is the point: contract first.
• oasdiff breaking: adding an endpoint and a value to the error enum is not breaking, so the gate will pass green. It is worth verifying anyway.

Level 4 — Consumer mock (msw in the SPA; in the front-end PR):

• The "request a return" screen with 201, with the expired-window 409 (a specific message, not a generic one) and with 403.
• A handler with Prefer: code=409 in Prism to lay it out before the endpoint exists.

Level 5 — End-to-end (after deploying to staging):

No new test. And this is a decision, not an oversight: the purchase journey already covers login, catalogue, order and payment, which are the pieces that break the business if they fail. A return is a secondary flow, it requires an order in shipped status —which means simulating the carrier's step— and its test would be slow and fragile. It is covered by integration, which gives 95 % of the confidence for 5 % of the cost.

Exception: if the return actually moves money towards the gateway, it does deserve one smoke test against the gateway's sandbox, run weekly and not on every deployment, because payment integrations are where a failure costs most.

What I would NOT test, and why:

• The email's content. That is the email service's responsibility. It is enough to check it is asked to send with the right data; verifying the template is testing somebody else's library.
• That SwiftShip collects the parcel. It is outside our system. We test that we ask them correctly and that we know how to handle their failure; the rest is their contract with us.
• Every combination of returned items. The amount calculation is unit-tested with three or four representative cases and the boundaries. Testing every combination in integration is slow and adds nothing new.
• The SPA's interface in e2e. This is an API; interface tests belong to the front end's repository and are done there with msw or with an automated browser.

When each runs (according to the table in section 18): unit tests on save; integration and contract on save and in the pull request; msw in the front-end PR; no new e2e; the gateway smoke test, weekly.

The loop is closed. openapi.yaml has stopped being a document that describes intentions and become an artefact from which seven different things are derived and —most importantly— against which reality is verified. You have brought up a mock with Prism that lets the SPA lay out the catalogue, the insufficient-stock screen and every error state with Prefer: code=409 weeks before the endpoint exists, knowing exactly where its limits are: with no logic, no state and no authentication, a mock unblocks parallel development but proves nothing about the real API. You have seen doubles on both sides of the conversation: msw intercepting in the SPA's tests, with onUnhandledRequest: 'error' so that no call slips through, and nock with disableNetConnect() to test what would otherwise be impossible —that a 503 from SwiftShip does not reverse a charge that has already been made.

The core of the lesson is the provider contract tests: the new tests/helpers/contract.js helper compiles the OpenAPI 3.1 components.schemas with AJV and validates the real bodies inside the Supertest tests from 03-08, without writing a separate suite. That catches what no manual assertion caught: a required field that disappears, a date with no Z, an error code invented outside the catalogue. And in the other direction, oasdiff turns the compatibility rules from 02-07 into an automatic gate with tools/check-contract.sh, which distinguishes what breaks from what does not and —a detail that is expensive to learn— knows that widening an input enum is safe and widening an output one is not. On Pact you take away a criterion, not an implementation: it answers "what do my consumers need?", a superb question when the consumers are known internal services and an impossible one when they are Aroma Mobile with versions from eight months ago and CataBox. For Aroma Store today, the provider's contract rules.

The project's new artefacts: tests/helpers/contract.js, tests/e2e/purchase-journey.test.js with the full journey login → catalogue → order with idempotency genuinely verified → payment → lookup, tools/check-contract.sh, the mock and mock:dynamic scripts, and @stoplight/prism-cli, ajv, ajv-formats, yaml and nock in devDependencies. And a table that orders all the course's work in time: what runs on save, what in the pull request, what on deployment and what in production.

That last table is literally the script for the next lesson. In 05-05, Continuous integration and deployment, we turn it into a pipeline that runs by itself: we will package the API in a multi-stage Dockerfile with a non-root user, a HEALTHCHECK on /health and the graceful shutdown on SIGTERM we wrote in 03-07; we will bring up the whole environment with docker-compose.yml including Redis; we will write .github/workflows/ci.yml with the gates in order —npm ci, lint, Spectral, tests with coverage, npm audit, oasdiff, building and publishing the image, and Newman against staging—; we will see why migrations have to be backwards-compatible and what happens when a DROP COLUMN meets the previous version still alive; and we will compare recreate, rolling, blue-green and canary, with the exact role /health and /health/ready play in keeping traffic out before it is time.