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.

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.