Mocks

Intercept outbound HTTP requests from your services and return controlled responses.

When a service makes an outbound HTTP request, the interceptor sidecar checks it against all MOCK items. If a mock matches, the mock response is returned. If no mock matches, the request passes through to its real destination.

Required fields

Optional fields

Example — mocking Stripe

{
  "type": "MOCK",
  "name": "mock-stripe-charges",
  "mockMethod": "POST",
  "mockOrigin": "payment-service",
  "mockTarget": "api.stripe.com",
  "mockPath": "/v1/charges",
  "mockDelayMs": 100,
  "mockResponseStatus": 200,
  "mockResponseHeaders": { "Content-Type": "application/json" },
  "mockResponseBody": {
    "id": "ch_test_123",
    "object": "charge",
    "amount": 2000,
    "currency": "usd",
    "status": "succeeded"
  }
}

Example — mocking a failure

{
  "type": "MOCK",
  "name": "mock-stripe-failure",
  "mockMethod": "POST",
  "mockTarget": "api.stripe.com",
  "mockPath": "/v1/charges",
  "mockResponseStatus": 402,
  "mockResponseBody": {
    "error": { "type": "card_error", "message": "Your card was declined." }
  }
}

Path matching

The mockPath field supports several matching patterns:

Query strings are ignored during path matching. Wildcards in the middle of a path (e.g., /api/*/posts) are not supported — only trailing wildcards work.

Mock precedence

When multiple mocks match the same request, the most specific mock wins. Specificity is scored by how many fields are narrowed beyond the default wildcard:

• Specific mockOrigin (not *): +1
• Specific mockTarget (not *): +1
• Specific mockMethod (not *): +1
• Exact path or path variable: +2, trailing wildcard: +1

On a tie, exact paths beat path variables, and the mock defined first wins.

Alternative: top-level mocks array

Mocks can also be defined in a top-level mocks array on the definition, with shorter field names:

{
  "name": "my-definition",
  "items": [ ... ],
  "mocks": [
    {
      "name": "Stripe Create Charge",
      "method": "POST",
      "origin": "payment-service",
      "target": "api.stripe.com",
      "path": "/v1/charges",
      "responseStatus": 200,
      "responseHeaders": { "Content-Type": "application/json" },
      "responseBody": { "id": "ch_test", "status": "succeeded" }
    }
  ]
}

Field name mapping