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 '@api/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 '@api/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'

Custom Mocks (Rare)

For endpoints defined in the OpenAPI schema, always use AutoAPIMock fixtures. The related skills below cover all the ways to customize mock behavior for different test scenarios.

Custom mocks are only needed for endpoints with no schema at all - for example, third-party APIs or non-standard endpoints not defined in api/openapi.json. In these rare cases, add handlers to renderer/src/common/mocks/customHandlers/index.ts.

Note: Some existing handlers in customHandlers predate the AutoAPIMock system. These are legacy patterns - new code should use fixtures with the techniques described in the related skills.

Migrating from Custom Handlers to AutoAPIMock

When refactoring tests that use server.use() overrides, you may find that the endpoint has a legacy custom handler in customHandlers/index.ts instead of an AutoAPIMock fixture.

To migrate:

1. Remove the custom handler from renderer/src/common/mocks/customHandlers/index.ts
2. Run the tests - this triggers auto-generation of the fixture
3. Verify the fixture was created in renderer/src/common/mocks/fixtures/<endpoint>/<method>.ts
4. Refactor tests to use .override() or .conditionalOverride() instead of server.use()

This workflow ensures fixtures are generated from the OpenAPI schema rather than manually copied from legacy code.

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)