Mocks

A mock is a server on a port of your Mac that answers like an API. Front ends, apps and tests can use it before the API exists, or while the real one is down. A mock answers from two sources, alone or together:

• Routes you make by hand: a method, a path, and the JSON, XML or text it answers. Bodies can hold fake data ({{$randomFullName}}, {{$randomEmail}}) that changes on every request, and parts of the request ({{request.params.id}}). No spec needed. See routes and fake data.
• An OpenAPI spec: every operation answers with the responses the spec documents, its examples or a body made from its schemas. Requests that break the spec get a 400 that says why, so the mock also tells you when a client sends the wrong thing.

For answers that need code or state, a mock can also have routes in JavaScript.

Open the page with Mocks in the sidebar's module switcher, or ⌘4.

Creating a mockCopy Anchor Link

Click + in the sidebar's Mocks header, or use the buttons on the empty page:

• New Mock makes a mock of routes. It starts with one route, GET /users, that answers five fake users, so you can start it and see what a body can do. Change it or add your own; see routes and fake data.
• Mock of a spec (in the + menu, or Mock of a Spec on the empty page) makes a mock of a spec in the workspace, such as Mock of Alpenglow demo shop.

The new mock takes the next free port from 4010. Its settings and routes are a file in the workspace's mocks folder, so a team shares its mocks through Git.

A mock of routes can serve a spec too, and a mock of a spec can have routes: Serve a Spec in the Settings card adds one, Change › Stop Serving the Spec takes it away.

Starting and stoppingCopy Anchor Link

Click Start (⌘R). The bar at the top shows the mock's address, such as http://127.0.0.1:4010. When the mock serves a spec whose server URL has a path (https://demo.echolot.dev/v1), the address ends with it (http://127.0.0.1:4010/v1) and the mock answers under it; requests may leave that path out, too. The copy button next to the address copies it.

Try it from Terminal:

curl http://127.0.0.1:4010/users

Stop stops it. The sidebar shows which mocks run: a green dot, and the port beside the spec's title or the number of routes (Alpenglow demo shop · :4010, 3 routes · stopped). Right-click a mock for Start or Stop and Delete…. Delete asks first; the settings file goes to the Trash and the spec stays.

Mocks run while their workspace window is open. A running mock picks up changes to its routes, spec and settings without stopping. A port another program uses can't be taken: Echolot says so; choose another port.

Sending requests to the mockCopy Anchor Link

• Create Requests in the Routes card makes a folder of requests that call the mock's routes, with {{baseUrl}} set to the mock's address. See requests from routes.
• Use in Environment (while the mock runs) makes an environment named Mock: <name> whose {{baseUrl}} is the mock's address, and makes it active. Requests that start with {{baseUrl}}, such as the ones Generate Requests makes from a spec, then go to the mock until you choose another environment. See Environments.

SettingsCopy Anchor Link

Which response a request getsCopy Anchor Link

A request goes to the first of these that has an answer for its method and path:

1. The mock's routes in JavaScript. A route that sets nothing passes the request on.
2. Its routes made by hand. A route can have several responses; a request can ask for one by name or status, rules on the request choose others, and otherwise the route's default answers.
3. The spec's operations, as below.

Literal path segments win over parameters, so /pets/mine is chosen before /pets/{id}, in routes and operations alike.

For an operation of the spec, the mock picks the response in this order:

1. What the request asks for: a Prefer: code=404, example=empty header, or Postman's x-mock-response-code and x-mock-response-name headers.
2. The response chosen for the operation in the Spec Responses card.
3. The operation's first success response.

The Spec Responses card lists every operation with a menu: First success, or one of the documented statuses, and for a status with several examples, the example. The choice is saved with the mock.

The body is the response's named example (the one asked for, or the first), its single example, or else a body made from its schema: fake data that fits each field's type, format and name (an email address for a field of format email), within the schema's limits, made again on every request. A field named like a path parameter repeats it. When the spec documents several media types, the request's Accept header picks one. The documented headers and content type are sent too. A 204, a 304 and answers to HEAD have no body.

Other answers the mock gives:

Browsers may call the mock from a page on another port: it answers preflight requests and sends the CORS headers.

The logCopy Anchor Link

The bottom of the page lists the requests the selected mock answered, newest first: the time, the status, the method and path, the response used (a route's response name, a spec example's name, or generated when the body came from the schema), and how long it took. Problems are on the lines below a request: where it broke the spec, or a fake value a route's body couldn't make. Rest the pointer on a request to see the response body, the request's body and content type; Copy Response copies the body. Clear empties the log.

Where Apple's on-device model is available, the button beside Clear summarizes the log.

Saving examples into the specCopy Anchor Link

For a spec's operations, the spec is the only source of what the mock answers, so a real response you got is saved there as an example: in History, right-click an exchange of a request that follows the spec and choose Save as Mock Example…. Give it a name, such as two tents, and click Save.

The response becomes a named example of its operation's response in the spec the request follows. Choose it in the Spec Responses card, or ask for it with Prefer: example=two tents.

For a path the spec doesn't have, or a mock without a spec, make a route and paste the body.

Sharing on the networkCopy Anchor Link

Turn on Answer other devices on the network to reach the mock from a phone, a tablet or a container. Other devices use your Mac's address on the local network, with the mock's port.

The first time, macOS may ask whether Echolot may find and connect to devices on your local network. Allow it, or other devices can't reach the mock. You can change the answer later in System Settings › Privacy & Security › Local Network.

Anyone on the network can then call the mock. Turn sharing off when you don't need it.

From the command lineCopy Anchor Link

echolot mock alpenglow.yaml serves a spec file, and echolot mock -w <workspace> <mock> serves a mock of a workspace with its settings and routes, spec or not, for CI or a container. See echolot mock. echolot fake makes fake data from the same templates, for fixtures and seed data.

Agents can start mocks and read their logs through Echolot's MCP server, and, when the Mocks toolset is on, create mocks, add and change routes, generate fake data and make requests from routes. See Agents.