Conditional Mock API Responses

Why You Need Conditional Mocks

• Test "missing auth header returns 401" without breaking the rest of the suite
• Paginate: ?page=1 returns items 1–10, ?page=2 returns 11–20
• Tenant isolation: X-Tenant: acme returns Acme's data, different tenant returns its own
• Feature flags: X-Beta: 1 returns new response shape
• Validation: POST with missing required field returns 422 with error body
• Rate limit simulation: every request with X-Simulate: rate-limit returns 429

How Requex Evaluates Conditions

A Requex mock route can have multiple responses, each with an optional condition set. When a request arrives:

1. Requex fetches all responses for the matched route + method, ordered by priority
2. It walks the list in order. For each response: if no conditions, it wins. If conditions exist, evaluate them.
3. If all (mode=all) or any (mode=any) conditions pass, the response wins
4. If conditions fail and a fallback is set, the fallback returns immediately (short-circuits)
5. If conditions fail and no fallback, Requex continues to the next response
6. If nothing matches, method=ANY responses are tried as final fallback
7. If still nothing, 404 returned

Condition Sources and Operators

Operators: eq, neq, contains, startsWith, endsWith, regex, exists, notExists, gt, lt.

Worked Example 1: Pagination

Three responses on GET /items:

Response 1 (priority 1)
  condition: query.page eq "1"
  body: { "items": [1..10], "nextPage": 2 }

Response 2 (priority 2)
  condition: query.page eq "2"
  body: { "items": [11..20], "nextPage": null }

Response 3 (priority 3, no condition, default)
  body: { "items": [1..10], "nextPage": 2 }

Request with ?page=2 gets Response 2. Any other request gets Response 3.

Worked Example 2: Auth + Fallback

Return 200 with data when a valid Bearer token is present; 401 otherwise. Use a condition with a fallback:

Response 1
  conditions:
    mode: all
    rules:
      - source: header, key: Authorization, operator: startsWith, value: "Bearer "
    fallback:
      statusCode: 401
      body: '{"error":"Missing or invalid token"}'
      headers:
        - { key: "WWW-Authenticate", value: "Bearer" }
  status: 200
  body: { "user": { "id": 1, "name": "Alice" } }

Valid token → 200 + user data. No/invalid token → 401 short-circuits via the fallback. One response, two outcomes.

Worked Example 3: Request Body Validation

POST /users , return 422 when body.email is missing:

Response 1 (priority 1, validation fail)
  condition: body.email notExists
  status: 422
  body: { "error": "email required" }

Response 2 (priority 2, default success)
  status: 201
  body: { "id": "{{body.email}}", "created": true }

Best Practices

• Order responses by specificity. Narrow conditions first, generic last.
• Always include a default response. Without one, unexpected requests get 404, confusing during debugging.
• Use exists instead of eq "". Empty-string equality behaves differently than absent fields.
• Test your conditions. Hit the mock with curl first to verify the right response fires for each scenario.
• Name your responses. "Auth fail 401", "Page 1", "Default success", future you will thank present you.

FAQ