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:

typescript
1// renderer/src/common/mocks/fixtures/groups/get.ts
2import type {
3  GetApiV1BetaGroupsResponse,
4  GetApiV1BetaGroupsData,
5} from '@common/api/generated/types.gen'
6import { AutoAPIMock } from '@mocks'
7
8export const mockedGetApiV1BetaGroups = AutoAPIMock<
9  GetApiV1BetaGroupsResponse,
10  GetApiV1BetaGroupsData
11>({
12  groups: [
13    { name: 'default', registered_clients: ['client-a'] },
14    { name: 'research', registered_clients: ['client-b'] },
15  ],
16})

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:

typescript
1import { render, screen, waitFor } from '@testing-library/react'
2
3it('displays groups from the API', async () => {
4  render(<GroupsList />)
5
6  await waitFor(() => {
7    expect(screen.getByText('default')).toBeVisible()
8  })
9})

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:

typescript
1// renderer/src/common/mocks/fixtures/groups/get.ts
2export const mockedGetApiV1BetaGroups = AutoAPIMock<
3  GetApiV1BetaGroupsResponse,
4  GetApiV1BetaGroupsData
5>({
6  groups: [
7    { name: 'production', registered_clients: ['claude-code'] }, // Custom data
8    { name: 'staging', registered_clients: [] },
9  ],
10})

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

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

Key Imports

typescript
1// Types for API responses and request parameters
2import type {
3  GetApiV1BetaGroupsResponse,
4  GetApiV1BetaGroupsData,
5} from '@common/api/generated/types.gen'
6
7// AutoAPIMock wrapper
8import { AutoAPIMock } from '@mocks'
9
10// Fixture mocks (for test-scoped overrides, see: testing-api-overrides skill)
11import { 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:

typescript
1// renderer/src/common/mocks/fixtures/health/get.ts
2import type {
3  GetHealthResponse,
4  GetHealthData,
5} from '@common/api/generated/types.gen'
6import { AutoAPIMock } from '@mocks'
7
8export const mockedGetHealth = AutoAPIMock<GetHealthResponse, GetHealthData>(
9  '' as unknown as GetHealthResponse
10)

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

typescript
1import { mockedGetHealth } from '@mocks/fixtures/health/get'
2import { HttpResponse } from 'msw'
3
4it('navigates on health check success', async () => {
5  mockedGetHealth.overrideHandler(() => new HttpResponse(null, { status: 204 }))
6  // ...
7})
8
9it('handles health check failure', async () => {
10  mockedGetHealth.overrideHandler(() => HttpResponse.error())
11  // ...
12})

Custom Mocks (Text/Plain Endpoints)

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

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

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

typescript
1import { getMockLogs } from '@/common/mocks/customHandlers'
2
3getMockLogs.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)