stacklok/testing-with-api-mocks

Testing with API Mocks

This is the starting point for all API mocking in tests. Read this skill first before working on any test that involves API calls.

This project uses MSW (Mock Service Worker) with auto-generated schema-based mocks. When writing tests for code that calls API endpoints, mocks are created automatically.

How It Works

1. Run a test that triggers an API call (e.g., a component that fetches data)
2. Mock auto-generates if no fixture exists for that endpoint
3. Fixture saved to renderer/src/common/mocks/fixtures/<endpoint>/<method>.ts
4. Subsequent runs use the saved fixture

No manual mock setup is required for basic tests.

Fixture Location

Fixtures are organized by endpoint path and HTTP method:

renderer/src/common/mocks/fixtures/
├── groups/
│   ├── get.ts          # GET /api/v1beta/groups
│   └── post.ts         # POST /api/v1beta/groups
├── workloads/
│   └── get.ts          # GET /api/v1beta/workloads
├── workloads_name/
│   └── get.ts          # GET /api/v1beta/workloads/:name
└── ...

Path parameters like :name become _name in the directory name.

Fixture Structure

Generated fixtures use the AutoAPIMock wrapper with types from the OpenAPI schema:

// renderer/src/common/mocks/fixtures/groups/get.ts
import type {
  GetApiV1BetaGroupsResponse,
  GetApiV1BetaGroupsData,
} from '@common/api/generated/types.gen'
import { AutoAPIMock } from '@mocks'

export const mockedGetApiV1BetaGroups = AutoAPIMock<
  GetApiV1BetaGroupsResponse,
  GetApiV1BetaGroupsData
>({
  groups: [
    { name: 'default', registered_clients: ['client-a'] },
    { name: 'research', registered_clients: ['client-b'] },
  ],
})

The second type parameter (*Data) provides typed access to request parameters (query, path, body) for conditional overrides.

Naming Convention

Export names follow the pattern: mocked + HTTP method + endpoint path in PascalCase.

• GET /api/v1beta/groups → mockedGetApiV1BetaGroups
• POST /api/v1beta/workloads → mockedPostApiV1BetaWorkloads
• GET /api/v1beta/workloads/:name → mockedGetApiV1BetaWorkloadsByName

Writing a Basic Test

For most tests, just render the component and the mock handles the rest:

import { render, screen, waitFor } from '@testing-library/react'

it('displays groups from the API', async () => {
  render(<GroupsList />)

  await waitFor(() => {
    expect(screen.getByText('default')).toBeVisible()
  })
})

The auto-generated mock provides realistic fake data based on the OpenAPI schema.

Customizing Fixture Data

If the auto-generated data doesn't suit your test, edit the fixture file directly:

// renderer/src/common/mocks/fixtures/groups/get.ts
export const mockedGetApiV1BetaGroups = AutoAPIMock<
  GetApiV1BetaGroupsResponse,
  GetApiV1BetaGroupsData
>({
  groups: [
    { name: 'production', registered_clients: ['claude-code'] }, // Custom data
    { name: 'staging', registered_clients: [] },
  ],
})

This becomes the new default for all tests using this endpoint.

Regenerating a Fixture

To regenerate a fixture with fresh schema-based data:

1. Delete the fixture file
2. Run a test that calls that endpoint
3. New fixture auto-generates

rm renderer/src/common/mocks/fixtures/groups/get.ts
pnpm test -- --run <test-file>

Key Imports

// Types for API responses and request parameters
import type {
  GetApiV1BetaGroupsResponse,
  GetApiV1BetaGroupsData,
} from '@common/api/generated/types.gen'

// AutoAPIMock wrapper
import { AutoAPIMock } from '@mocks'

// Fixture mocks (for test-scoped overrides, see: testing-api-overrides skill)
import { mockedGetApiV1BetaGroups } from '@mocks/fixtures/groups/get'

204 No Content Endpoints

For endpoints that return 204, create a minimal AutoAPIMock fixture and override the handler in each test:

// renderer/src/common/mocks/fixtures/health/get.ts
import type {
  GetHealthResponse,
  GetHealthData,
} from '@common/api/generated/types.gen'
import { AutoAPIMock } from '@mocks'

export const mockedGetHealth = AutoAPIMock<GetHealthResponse, GetHealthData>(
  '' as unknown as GetHealthResponse
)

Then in tests, use .overrideHandler() to return the appropriate response:

import { mockedGetHealth } from '@mocks/fixtures/health/get'
import { HttpResponse } from 'msw'

it('navigates on health check success', async () => {
  mockedGetHealth.overrideHandler(() => new HttpResponse(null, { status: 204 }))
  // ...
})

it('handles health check failure', async () => {
  mockedGetHealth.overrideHandler(() => HttpResponse.error())
  // ...
})

Custom Mocks (Text/Plain Endpoints)

Custom mocks are only needed for text/plain endpoints. The only current example is the logs endpoint:

// renderer/src/common/mocks/customHandlers/index.ts
export const customHandlers = [
  http.get(mswEndpoint('/api/v1beta/workloads/:name/logs'), ({ params }) => {
    const { name } = params
    const logs = getMockLogs(name as string)
    return new HttpResponse(logs, { status: 200 })
  }),
]

To override the logs response in tests, use the exported getMockLogs mock:

import { getMockLogs } from '@/common/mocks/customHandlers'

getMockLogs.mockReturnValueOnce('Custom log content for this test')

Related Skills

• testing-api-overrides - Test-scoped overrides and conditional responses for testing filters/params
• testing-api-assertions - Verifying API calls for mutations (create/update/delete)