Understanding Mocks

Overview

API mocks let you create and manage fake responses for your API endpoints. In Shift-Left API you can use them two ways:

• During test execution, so tests don't depend on live services.
• As a standalone mock server, so clients, tools, or teammates can call predictable responses outside a full test run.

Mocks are always scoped to a project — you pick a project on the API Mocks page, then create and manage mocks for that project's endpoints. This article covers what mocks are and how they behave. Explore the capability at mock server.

Before you begin

• This is a conceptual overview. For the click-by-click UI walkthrough — creating, generating, configuring, and serving mocks — see Creating and configuring mocks.
• Open mocks from the top navigation Mocks entry, then choose a project from Select a project. Use All Projects to switch projects later.
• Linking mocks to endpoints (or bulk-generating them) requires a project with at least one endpoint; see Endpoint management.

The high-level flow

1. Select a project — pick a project on the API Mocks page to manage its mocks.
2. Create or generate mocks — add mocks by hand with Create Mock, or bulk-create them from endpoint schemas with Generate Mock.
3. Start the server — click Start Mock Server to serve active mocks; Stop Server ends it (the header shows "Mock server running" while active).
4. Test and use — try responses with a sample request, then use mocks in test execution or via the standalone server.

Mock capabilities

Steering a mock: scenarios

Every response in a mock has a name. To get a specific one, send its name with the request:

• the header X-Mock-Scenario: 404, or
• the query parameter ?mockScenario=404.

Names ignore capital letters and surrounding spaces. With no header, the mock answers as before. If you ask for a name the mock does not have, you do not get the success by accident. You get a 404 that lists the real names, so a misspelt scenario can never make a failure test pass.

Three things add named responses for you:

• Error scenarios. A generated REST mock gets one extra response for each error (4xx or 5xx) the specification documents, named by its status, such as 404 or 500 (up to eight). They are reached only by name, so the normal answer does not change. Generated SOAP and GraphQL mocks have a single response and get no extra ones.
• Answers at the limits. On Generate mocks, tick Also add answers at the limits to add named boundary- responses at the schema's limits: an empty list, the longest allowed text, the smallest and largest numbers, and each optional field missing. A schema with no limits gives few or none.
• A default answer for an environment. In Project settings, the Mock answer field on an environment row names a response (for example 503). Calls that reach the mock server through that environment's address get that response, but only when the mock has a response of that name. A call can still ask for another one with X-Mock-Scenario. Only the response name is set per environment, not a different body.

Fail on purpose

A real service fails in more ways than returning an error status. In the response editor, the How it answers setting has three choices:

• Answers normally (the default).
• Never answers (the call times out). The call is held until the caller gives up, or for the number of seconds you choose (up to 300), then the connection is closed.
• Cuts the connection. The connection is closed at once, before any answer.

Combine this with a scenario name. Call a response down, set it to cut the connection, and a test that sends X-Mock-Scenario: down gets a dead connection while every other call is answered normally.

Mocks that remember

Open More... on a mock, then Remembering, and turn it on. A mock that creates stores what it is sent. A mock that reads, updates, deletes or lists works on the same records, so a create followed by a get returns what was created. Mocks of one project that work on the same resource (for example POST /orders and GET /orders/{id}) share their records.

Records expire after one hour unless you choose otherwise, and a resource holds a limited number of them. Forget what it holds empties them. A call that carries X-Mock-Scenario is answered as written and does not touch the records. These are short-lived test records, not a database.

Check mocks against the contract

On an API's page, Check the mocks against the contract compares each response a mock holds with the schema the API documents. For each response it says one of three things:

• Fits.
• Differs, and exactly where.
• Not checked, and why.

Templates, XML and text bodies, responses the API does not document, and any part of a schema the checker cannot evaluate are shown as Not checked. They are never counted as a pass. This is a check against the documented schema, not a full OpenAPI validation, and it does not guarantee that a mock matches production.

Lifecycle, versions and the contract

• Lifecycle. A mock is a draft, approved, published or retired. Only a published mock can be switched on. A mock you make the usual way is published at once. A draft is for something made for you (an AI suggestion, a dependency mock, a recording) that nobody has read yet: approve it, then publish it, which switches it on. Retiring switches the mock off, needs a reason, and keeps the mock and its history.
• Earlier answers. Every edit to what a mock answers makes a version. Earlier answers lists them, and putting one back is itself a new version, so nothing is lost. Renaming a mock or switching it on or off does not make a version.
• Bring it up to date. Contract on a mock first offers Check what would change, which changes nothing. Bring it up to date then applies it: responses you never touched follow the contract, responses you edited stay, and a response that both you and the contract changed is kept as you wrote it.
• Mock the dependencies. Under More ways to make mocks..., pick an API. Shift-Left API lists the APIs it was seen calling or takes a value from, and creates a draft mock for each one that has none. Draft mocks are switched off and answer nothing until you publish them.
• May be out of date. When an approved specification change touches an API, its mocks show a May be out of date chip. It is only a question for you: the mock keeps answering as before. Check it, then choose I've checked it.

How generation works

Generate Mock builds example responses from each endpoint's OpenAPI/JSON schema (WSDL example XML for SOAP, a GraphQL data envelope for GraphQL). It is deterministic schema-to-example synthesis — no AI model is called and no provider key is needed — so it works fully offline. When a selected endpoint already has a mock, a conflict step lets you skip, update, or duplicate.

Static vs dynamic responses

• Static responses return a fixed body exactly as written (JSON, or XML for SOAP).
• Dynamic responses use {{ … }} templates resolved per request:
  • Utilities: {{uuid}}, {{timestamp}}, {{date}}, {{randomInt}}, {{randomInt(N)}}, {{randomFloat}}
  • Request echoes: {{request.query.name}}, {{request.headers.name}}, {{request.body.nested.path}}, {{request.path.name}}

Serving mocks: two URL styles

When the mock server runs, the UI offers two base URLs (with copy buttons):

• Path-based URL — no DNS needed; use it when the engine runs on your machine or the same server.
• Subdomain URL — for a centralized engine where your company has DNS. Ask your admin if unsure.

A How to Use panel provides ready-to-copy snippets for calling your mocks.

When to use mocks

• The real API is not available, unstable, or still in development.
• You need deterministic negative or edge cases that are hard to reproduce live.
• You want faster CI or isolated workflows without environment flakiness.

Best practices

• Keep mock bodies realistic and aligned with your contract so tests stay meaningful.
• Use clear mock names and descriptions so the list stays scannable.
• Deactivate or remove mocks when you intentionally want tests to hit the real API — only active mocks are served.

Related articles

• Creating and configuring mocks
• Understanding workflows
• Endpoint management
• Reviewing a specification change