Mock API for Integration Testing: Mock Servers from a Spec

This is lesson 9.9 of Shift-Left API in Depth, the product track of the learning center. In lesson 9.8, a workflow chained three tests against the live sandbox. Now you spin up a mock server from the spec, and run a test against it instead. Mock servers are in every edition of Shift-Left API, and the demo uses the public sandbox store API.

How do you set up a mock API for integration testing?

A mock API for integration testing lets your tests run before the real service is ready, or while it is down: it answers each call the way the spec says the service will. The questions are where that mock comes from, and how you point a test at it instead of the live API.

What a mock API is

API mocking for testing works like this. A mock server is generated from the API's spec, and it answers the calls the spec describes with a status code and an example body: 200 and the order when it exists, 201 when an order is created, and, with a rule you add in the mock editor, 404 when it doesn't exist. Your app or your tests call the mock instead of the real service, so a team can build and test against the API while the backend is still in progress.

An API mock generator that works from the spec gives you five things:

• One mock for each endpoint, linked to it.
• The success status the spec documents: 200, 201 or 204.
• A body built from the response schema: the spec's own examples, or placeholders of the right type.
• A base URL, while its mock server runs.
• No interception: you point a test at the mock yourself.

Mock or live API?

Use the mock when the service isn't built yet, when a test mustn't depend on someone else's uptime, or when you're checking the contract: the status, the fields, their types. Use the live API when the test needs real data, like the actual price of a product, and for the final sign-off before a release.

Run a test on the live API first

The demo project, Store API Mocks, is built from the sandbox store's spec and has one test so far.

1. Click Products in the Features table, then Get a single product by ID.
2. Click the test's name, Read a product, to open it in the test workbench. It reads one product by its ID: the Wireless Mouse.
3. Click Run. It passes on the Development environment, which is the live sandbox.

Three checks describe the contract: the status code is 200, the product has a name, and its price is a number. The Response tab shows the real product, a Wireless Mouse at 24.99. Close the workbench.

Generate mocks from the spec

1. Click Mocks in the top bar. It opens on the current project, with no mocks yet.
2. Click Generate Mock. The dialog lists every feature and endpoint the spec defines.
3. Open Products, and tick it: 6 of 38 endpoints selected.
4. Click Generate Mocks. You get six mocks, one per endpoint, each named for its method and path, and each one active.

See what a mock answers

On the mock for GET /api/v1/products/{id}, click Test Mock. The status code is 200: the success status the spec documents. The body follows the spec's response schema: success is true, and there's a product with an id, a name, a price and a stock. The sandbox spec gives no example values, so the mock fills each field with a placeholder of the right type: the word string, a zero, a fixed date. Close it.

Start the mock server

Click Start Mock Server. Test Mock answered inside the app; to answer real requests, from a test or any other client, the mocks need this server. The panel reads Mock Server Running, and gives two base URLs:

• Path-based, on the Engine on your machine.
• Subdomain, for a central Engine with its own DNS.

All six mocks are active behind it.

Point the test at the mock

1. Click Project Settings, then Environment Settings. The demo project has two environments: Development, the live sandbox, and Mock, set to the mock server's path-based URL.
2. Select Mock to make it the default. From now on, runs go to the mock.
3. Close the settings.
4. Go back to the same test: click the project, then Products, Get a single product by ID, and Read a product. Click Run.

It passes again, now on the Mock environment. The Request tab shows where the call went: the mock server's URL, on the Engine, not the sandbox. And the Response is the mock's answer: a name of string, and a price of 0. Same test, same three checks, and no call to the live API.

Try it yourself

On the sandbox store, import the spec from https://demo.totalshiftleft.ai/openapi/rest.json, and make one test that reads the Wireless Mouse and checks its status, name and price. Generate mocks for Products, and click Test Mock on Get a single product by ID. Start the mock server, and add an environment whose base URL is the mock's path-based URL. Make it the default, run the test again, and read the Request tab.

Recap

• A mock API for integration testing answers the calls your spec describes, so tests can run without the live service.
• In Shift-Left API, Generate Mock builds one mock per endpoint, with the documented status and a body from the schema, and Start Mock Server gives it a base URL.
• An environment pointed at that URL sends your tests to the mock. The mock checks the contract; the live API checks the real data.

The free edition of Shift-Left API holds up to 50 mocks. Next, in lesson 9.10, you gather tests into a Test Run Pack, run it now, and schedule it for every night. For when and why teams mock an API, read API mocking: how and when to mock APIs.