Mocking Responses

The testing-api allows you to simulate complex AI platform behaviors by defining mock data within a response.json configuration. This approach enables you to test how your application handles various AI model states, latency, and error conditions without making actual calls to an LLM provider.

The `response.json` Structure

To mock an endpoint, place a response.json file in the corresponding route directory of your testing environment. The API uses this file to determine the status code, headers, and payload returned to the client.

Basic Usage

A standard mock response includes the status code and the JSON body representing the AI's output.

{
  "status": 200,
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "model": "gpt-4",
    "choices": [
      {
        "message": {
          "role": "assistant",
          "content": "This is a mocked AI response from the Supervised AI platform."
        },
        "finish_reason": "stop",
        "index": 0
      }
    ],
    "usage": {
      "prompt_tokens": 9,
      "completion_tokens": 12,
      "total_tokens": 21
    }
  }
}

Simulating AI Platform Behaviors

To accurately test your integration, you can simulate specific AI-related scenarios such as rate limiting, high latency, or malformed model outputs.

1. Simulating Network Latency

AI models often have significant time-to-first-token (TTFT). You can simulate this delay by adding a latency field (in milliseconds).

{
  "status": 200,
  "latency": 3000,
  "body": {
    "message": "This response was delayed by 3 seconds to simulate model processing."
  }
}

2. Simulating Rate Limits (429)

Test your application's retry logic or backoff strategies by mocking a Rate Limit error.

{
  "status": 429,
  "body": {
    "error": {
      "message": "Rate limit reached for gpt-4",
      "type": "requests",
      "param": null,
      "code": "rate_limit_exceeded"
    }
  }
}

3. Simulating Guardrail/Content Filter Triggers

You can mock the specific payload returned when an AI platform's safety filters block a response.

{
  "status": 200,
  "body": {
    "choices": [
      {
        "message": { "role": "assistant", "content": null },
        "finish_reason": "content_filter"
      }
    ]
  }
}

Dynamic Mocking (Advanced)

If you need to return different responses based on the input request, the testing-api supports a programmatic approach. While response.json is the default for static mocks, you can use a response.js or response.ts file to evaluate incoming headers or body parameters:

// response.js
module.exports = (req) => {
  if (req.body.model === "unsupported-model") {
    return {
      status: 400,
      body: { error: "Model not found" }
    };
  }

  return {
    status: 200,
    body: { message: "Dynamic mock success" }
  };
};

Validation

When the testing-api is running, any request made to the path mapped to your response.json will automatically receive the defined payload. Use this to verify:

UI Rendering: How the frontend displays long AI responses.
Error Handling: How the system reacts to 5xx or 4xx errors.
Token Tracking: Ensuring your application correctly parses usage metadata.

Mocking Responses