Scenarios

File structure

scenarios.json contains an array of rules:

  {
    "rules": [
      {
        "method": "GET",
        "match": "/v1/example",
        "enabled": true,
        "active_scenario": "success",
        "scenarios": { ... }
      }
    ]
  }

  # hot workflow
  Change "active_scenario" from "success" to "error"
  See frontend behavior instantly

Rule fields

• method: HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
• match: Request path to match
• enabled: Whether the rule is active
• active_scenario: Scenario key to use
• scenarios: Map of scenario definitions

Scenario fields

• status: HTTP status code (optional, default 200)
• json: Inline JSON response body
• file: Fixture file path (relative to project base path)
• contentType: Override the Content-Type header (optional, auto-detected when omitted)
• headers: Map of additional response headers to set (optional)
• delay: Delay in seconds before response

Each scenario must include at least one of json or file.

Dynamic path parameters

The match field supports named path parameters using :paramName syntax and wildcard captures using *splatName. Patterns are matched with path-to-regexp.

Named parameters

A :paramName segment matches exactly one path segment, regardless of its value:

{ "match": "/v1/users/:id" }
{ "match": "/v1/orgs/:orgId/repos/:repoId" }

Wildcard captures

A *splatName segment matches one or more path segments:

{ "match": "/v1/files/*path" }

This matches /v1/files/report.pdf as well as /v1/files/2024/january/report.pdf.

Case sensitivity

Path matching is case-sensitive. /api/users and /API/Users are treated as different paths.

Rule precedence

Rules are evaluated in order. Place more specific (literal) rules before param rules to give them priority:

{ "match": "/v1/users/me" },
{ "match": "/v1/users/:id" }

Param logging

Matched parameters are printed in the proxy log:

[MOCKED] GET /api/v1/users/42         -> success {"id":"42"}
[MOCKED] GET /api/v1/users/42/posts/7 -> success {"id":"42","postId":"7"}

Non-JSON responses

file scenarios support any content type — binary files, PDFs, CSVs, images, and plain text are all handled correctly.

Use contentType to set the Content-Type header and headers for anything else such as Content-Disposition:

{
  "status": 200,
  "file": "fixtures/report.pdf",
  "contentType": "application/pdf",
  "headers": {
    "Content-Disposition": "attachment; filename=report.pdf"
  }
}

{
  "status": 200,
  "file": "fixtures/export.csv",
  "contentType": "text/csv",
  "headers": {
    "Content-Disposition": "attachment; filename=export.csv"
  }
}

{
  "status": 200,
  "file": "fixtures/photo.png",
  "contentType": "image/png"
}

When contentType is omitted, the proxy detects the type from the file extension. Binary files are read as raw buffers so the content is never corrupted.

Best practices

Name scenarios by intent

Use labels like success, validation_error, server_error, timeout.

Use fixture files for large payloads

Keep mock data in fixtures/ and reference with file for cleaner config. Supports JSON, CSV, PDF, images, and any binary format.

Model user pain early

Add delayed and failing scenarios so UI states are polished before release.