Advanced Matching Overview

By default Mimic matches a mock to a request based on method and path. That’s enough for most cases, but real-world APIs often need finer control. Mimic supports matching on:

Query parameters — different responses based on ?type=admin vs ?type=user
Headers — different responses based on Authorization or Content-Type
Request body — different responses based on JSON, text, or form fields

All three can be combined in a single mock, and Mimic uses a priority scoring system to pick the best match when multiple mocks could apply.

The big picture

Each matcher lives at the top level of your mock file:

{
  "method": "POST",
  "path": "/api/search",
  "status": 200,

  "query_params": { /* match on query string */ },
  "headers":      { /* match on headers */ },
  "body":         { /* match on request body */ },

  "response": { /* ... */ }
}

Any matcher you omit is treated as “don’t care.” A mock with no matchers will accept any request that hits the right method and path.

Strict mode

Most matchers support a strict flag (default false):

strict: false — the request can have extra params/headers/fields beyond what you specified. Only the ones you listed are checked.
strict: true — the request must have exactly what you specified. Extra anything causes the match to fail.

Strict mode is useful for security-style tests (you don’t want a request with extra auth headers to silently pass) but loose mode is a better default for most app development.

Where to go from here

Query Parameters

Match on URL query strings with exact values, regex, or “any value.” See Query Parameters.

Headers

Match on header values, prefixes, regex patterns, or forbidden headers. See Headers.

Request Body

Match against JSON, plain text, or form-encoded body content. See Request Body.

Match Priority

Learn how Mimic picks a winner when multiple mocks could match the same request. See Match Priority.