echolot mock

echolot mock serves a mock: a mock saved in a workspace, with its routes made by hand and its spec if it has one, or an OpenAPI document, whose operations answer with their documented examples or a body made from their schema. Use it to build a client before the API exists, or to give a CI job a server that answers the way you want. It serves the same mocks as the Mocks page.

echolot mock <source> [--workspace <workspace>] [--port <port>] [--share] [--delay <ms>] [--failure-rate <percent>] [--no-validate] [--routes <file>]

<source> is a spec file (YAML or JSON), or with --workspace the name of a mock saved in that workspace.

Mock a specCopy Anchor Link

echolot mock Alpenglow.echolot/specs/alpenglow.yaml --port 4010

Mock of Alpenglow demo shop: 9 operations at http://127.0.0.1:4010/v1 (Ctrl-C stops it)

The mock answers at the path of the spec's first server (here /v1). Each request it answers is a line on standard output: the status, the method and path, the operation it matched, where the answer came from, and the time. Problems with the request are listed below it.

200 GET /v1/products/TNT-MH-2P  → GET /products/{sku} (generated)  0 ms
400 POST /v1/orders  → POST /orders  0 ms
    body $.lines: expected array, got string

Requests are checked against the spec. A request whose parameters or body break the spec gets a 400 that says what is wrong:

{
  "error" : "The request does not match the spec (POST /orders).",
  "problems" : [
    "body $.lines: expected array, got string"
  ]
}

--no-validate answers such requests anyway.

Choosing an answer. By default an operation answers with its first success response and its first example. A request can ask for another one with Prefer: code=404, example=empty, or with Postman's x-mock-response-code and x-mock-response-name headers.

Mock a workspace's mockCopy Anchor Link

With --workspace, <source> names a mock saved on the Mocks page (its file name in mocks/ without .toml, or its name). Its port, delay, failure rate, request checks, chosen responses and routes apply, and the options you give override them. Its routes in JavaScript (mocks/<name>.js) answer first, then its routes made by hand, then its spec; see scripted routes and routes and fake data.

echolot mock shop -w Alpenglow.echolot --delay 300

A mock of routes needs no spec:

echolot mock storefront -w Shop.echolot

Mock of Storefront: 3 routes at http://127.0.0.1:4321 (Ctrl-C stops it)
200 GET /users/42  → GET /users/{id} (OK)  1 ms
404 GET /users/0  → GET /users/{id} (Not found)  0 ms

Each line names the route that answered and, in parentheses, the response it gave. Fake values in the bodies are made again for every request. To make fake data without a server, see echolot fake.

OptionsCopy Anchor Link

Without --share the mock listens on 127.0.0.1 only, so nothing else on the network can reach it. With --share, anyone who can reach your Mac can.

A request body over the mock's limit gets a 413 and never reaches a route.

In CICopy Anchor Link

Start the mock in the background and run against it. Alpenglow's Local environment points {{baseURL}} at http://localhost:8787/v1, so a mock on port 8787 answers its requests:

echolot mock Alpenglow.echolot/specs/alpenglow.yaml --port 8787 &
echolot run Alpenglow.echolot --env local --folder catalog
kill %1

Exit codesCopy Anchor Link

The mock runs until you stop it. It exits with 64 for a wrong option or a mock name the workspace doesn't have, and with 1 when the spec can't be read or the port is taken.