// mock server

Mock Server

Resonance's built-in mock server listens on a local port and returns responses derived from your OpenAPI collections. No internet connection needed — the entire thing runs on your machine.

What It Does

  • Serves mock responses for your collections — imported OpenAPI 3.x / Swagger 2.0 specs work best because they carry examples and schemas
  • Uses the spec's examples, or generates payloads from its schemas when no custom response is defined
  • Lets you override the response body, status code, and delay per endpoint
  • Fills placeholders such as {{request.params.id}} in responses, so a mock can echo what it was sent
  • Lets a client ask for a specific documented response (for example the 404) with a Prefer header
  • Logs every incoming request so you can inspect method, path, headers, and body
  • Collections can be enabled or disabled individually without restarting

Before You Start

  1. Import an OpenAPI or Swagger specification — see Getting Started — or use any collection you built yourself
  2. Confirm the collection contains the endpoints you want to mock
  3. Pick a local port that nothing else is using (e.g. 3000)

Starting the Server

  1. Click the Mock Server action in the toolbar
  2. Set the port and enable the collections you want to expose
  3. Review generated routes and their default response settings
  4. Click Start Server
  5. Point your client or frontend at http://localhost:<port>

How Responses Are Generated

  • Each request in an enabled collection becomes a route. Path parameters may be written /users/{id}, /users/{{id}} or /users/:id; requests imported from cURL with a full URL match on their path
  • When several routes match, the most specific wins — /users/me is chosen over /users/{id}
  • The response is the first documented success status (so an endpoint documented only with 201 answers 201) with its example, the first of its named examples, or a body generated from its schema
  • A custom body or status code set in the dialog replaces the documented one

Response Templating

Any string in a response body — custom or taken from the spec — can contain placeholders that are filled from the incoming request:

{{request.params.name}}A path parameter of the matched route.
{{request.query.name}}A query parameter.
{{request.headers.name}}A request header (case-insensitive).
{{request.body}}The whole request body; {{request.body.items.0.id}} reaches into a JSON body.
{{request.method}} / {{request.path}}Method and path of the request.
{{$uuid}} / {{$timestamp}} / {{$isoTimestamp}} / {{$randomInt}}Fresh values on every response.
{
  "id": "{{request.params.id}}",
  "quantity": "{{request.body.quantity}}",
  "createdAt": "{{$isoTimestamp}}"
}

A string that consists of a single placeholder keeps the value's type, so "{{request.body.quantity}}" comes back as a number. Unknown placeholders are left as they are.

Choosing a Documented Response

To test error handling without changing the mock, send a Prefer header (the convention used by the Prism mock server). It overrides the endpoint's custom body and status for that one request:

Prefer: code=404
Prefer: example=userDeleted
Prefer: code=404, example=userDeleted
  • code picks the documented response with that status
  • example picks a named entry of that response's examples

Customising Endpoints

  1. Select an endpoint in the mock server dialog
  2. Change the response status code if needed
  3. Provide a custom JSON body to replace the generated payload
  4. Add an artificial delay to simulate latency
  5. Save the configuration — changes take effect immediately without a restart

Testing Against the Mock

Use the mock base URL exactly as you would a real API. Pair it with an environment variable so switching between real and mocked is a one-click operation.

GET  http://localhost:3000/users
POST http://localhost:3000/orders
Authorization: Bearer {{token}}
  • Set baseUrl → http://localhost:3000 in a Mock environment and switch to it from the selector
  • Use test scripts to chain extracted values between mock requests
  • Artificial delays help verify loading states, retries, and timeout handling in your client

Request Log

Every request that hits the mock server appears in the log — method, path, timestamp, query parameters, and body. Use it to confirm your frontend is calling the right routes with the right payloads.

Typical Workflow

  1. Import an OpenAPI collection
  2. Start the mock server on a local port
  3. Switch your active environment to the mock base URL
  4. Run your frontend, tests, or external client against the mocked routes
  5. Refine custom responses and delays until the behaviour matches your scenario

Troubleshooting

Server will not start

  • Check whether another process is already using the port
  • Try a different port and restart
  • Confirm at least one collection is enabled

Route returns an unexpected response

  • Verify the OpenAPI operation exists for that method and path
  • Check whether a custom override is replacing the generated response
  • Check whether your client sends a Prefer header
  • Review the selected status code in the endpoint configuration

Client cannot connect

  • Confirm the client is targeting localhost on the correct port
  • Verify the server is still running in Resonance
  • Check that local firewall or container networking is not blocking the port

Next Steps