Creating Mocks

How Matching Works

Once a project has more than a handful of mocks, two of them will eventually overlap. This page explains exactly how Mocko picks the mock that answers a request, and what happens when no mock matches at all.

Exact paths beat parameterized paths

A route segment is either literal (/users/me) or a parameter (/users/{id}). When both could match a request, the more specific one wins, regardless of the order they were defined in:

mock "GET /users/{id}" {
  format = "json"
  body = <<-EOF
    { "id": {{request.params.id}}, "role": "member" }
  EOF
}

mock "GET /users/me" {
  format = "json"
  body = <<-EOF
    { "id": 1, "role": "admin" }
  EOF
}

$curl http://localhost:8080/users/me

{ "id": 1, "role": "admin" }

This is what lets you mock a general route and then carve out one special case, a pattern the Mock One Edge Case recipe builds on.

Deployed mocks beat file mocks

When a mock created in the UI and a mock loaded from a file declare the same method and path, the deployed one wins. Think of the UI as a temporary override layer: your committed mocks describe the normal behavior, and a deployed mock can shadow one of them while you reproduce a scenario, without editing any file.

Delete the deployed mock (or restart a storeless instance) and the file mock underneath resumes answering. Nothing needs to be undone in the files.

Wildcard methods

A mock declared with * as the method matches any HTTP method on its path. Specific methods are more specific, so a GET mock on the same path takes precedence over the wildcard for GET requests.

mock "* /maintenance-mode" {
  status = 503
  format = "json"
  body = <<-EOF
    { "error": "Service under maintenance" }
  EOF
}

Ties within the same specificity

If two mocks have the same method and equally specific paths, the one declared first in the file wins. Relying on declaration order is fragile, though: treat duplicate routes as a mistake to clean up, not a feature to exploit. The UI flags these situations for you, as described below.

When nothing matches

A request that no mock matches gets a 404 with a message explaining that no mock was found. But if Mocko was started with a proxy URL, unmatched requests are forwarded to your real backend instead:

$mocko -u https://demo-api.mockoapp.net mocks

This turns Mocko into a selective layer in front of a real API: mocked routes answer locally, everything else passes through untouched. Proxying and Hosts covers this in depth.

Behavior details

Mocks scoped to a host with the hostfield only participate in matching for requests carrying that host's Host header. Unscoped mocks match any host.
The UI annotates unreachable mocks. A file mock shadowed by a deployed mock on the same route is marked as shadowed, and two mocks competing for the same route are marked as conflicting, so precedence surprises show up in the panel instead of in your test runs.

So far every response has been computed from the current request alone. Continue to Flags to give your mocks memory between requests.