Mocking & Sandbox Usage

The testing-api serves as a predictable interface for simulating the Supervised AI platform's behavior. By utilizing the response.json file as a blueprint, developers can create high-fidelity mocks and sandboxes that mirror production responses without hitting live endpoints.

The `response.json` Blueprint

The response.json file is the source of truth for all mocked interactions. It defines the structure, data types, and status codes expected from the Supervised AI platform. When creating local stubs, refer to this file to ensure your mock data remains schema-compliant.

Local Sandbox Setup

To utilize the API in a sandbox environment, configure your client to point to the local testing utility. This allows you to intercept network requests and return predefined payloads based on the blueprints.

import { TestingSandbox } from '@supervised-ai/testing-api';

// Initialize the sandbox using the standard blueprint
const sandbox = new TestingSandbox({
  blueprint: 'path/to/response.json',
  port: 8080
});

sandbox.start();

Stubbing Responses

You can override the default behavior defined in the blueprint by stubbing specific endpoints. This is useful for testing edge cases, such as 400-level errors or delayed responses.

`sandbox.stub(endpoint, options)`

Configures a specific response for a given route.

Example: Stubbing a Success Response

sandbox.stub('/v1/inference', {
  status: 200,
  body: {
    id: "inf_123",
    status: "completed",
    output: "Sample AI response"
  }
});

Example: Stubbing an Error State

sandbox.stub('/v1/inference', {
  status: 429,
  body: {
    error: "Rate limit exceeded",
    code: "rate_limit_error"
  }
});

Integrating with Test Suites

For automated testing, it is recommended to reset stubs between test cases to prevent state leakage.

describe('Inference Service', () => {
  beforeEach(() => {
    sandbox.reset(); // Clears all custom stubs and reverts to response.json defaults
  });

  it('should handle successful inference', async () => {
    sandbox.stub('/v1/inference', { status: 200, body: { success: true } });
    
    const response = await myApp.callInference();
    expect(response.success).toBe(true);
  });
});

Response Validation

The testing-api includes an internal validation layer that checks your stubs against the response.json schema. If a stubbed body deviates from the platform's required structure, the sandbox will log a warning to help you maintain contract fidelity during local development.

Mocking & Sandbox Usage