Testing API Overrides

Test that your code sends correct API parameters by using conditional overrides that respond differently based on the request. This approach tests actual user-facing behavior rather than inspecting internal request details.

Philosophy

Good tests verify what users see, not implementation details.

Instead of:

1. ❌ Recording the request and checking query params
2. ❌ Asserting on internal function calls

Do this:

1. ✅ Set up conditional mocks that respond based on params
2. ✅ Verify the component renders the expected data

If the code sends wrong parameters, the mock returns wrong data, the UI shows wrong content, and the test fails. This catches real bugs.

When to Use Conditional Overrides

• Testing list filtering (e.g., filter by group, status, search term)
• Testing pagination parameters
• Testing sort order
• Any read operation where request parameters affect what data is returned

Note: For mutations (create/update/delete), use recordRequests() instead. See the testing-api-assertions skill.

conditionalOverride()

Returns different data based on request properties:

typescript
1import { mockedGetApiV1BetaWorkloads } from '@mocks/fixtures/workloads/get'
2
3mockedGetApiV1BetaWorkloads.conditionalOverride(
4  // Predicate: when should this override apply?
5  ({ query }) => query.group === 'archive',
6  // Transform: what data to return?
7  (data) => ({
8    ...data,
9    workloads: [], // Archive group is empty
10  })
11)

Predicate Function

The predicate receives parsed request info with easy access to query params, path params, body, and headers:

typescript
1;({ query, path, body, headers }) => {
2  // Query parameters (pre-parsed)
3  query.group // '?group=archive' -> 'archive'
4  query.status // '?status=running' -> 'running'
5
6  // Path parameters (from route like /workloads/:name)
7  path.name // for /workloads/:name
8
9  // Request body (for POST/PUT/DELETE)
10  body?.name // parsed JSON body
11
12  // Headers
13  headers.get('Authorization')
14
15  return true // or false
16}

Transform Function

The transform receives default data and returns modified data:

typescript
1;(data) => ({
2  ...data, // Spread defaults
3  workloads: data.workloads?.filter(
4    // Modify as needed
5    (w) => w.status === 'running'
6  ),
7})

Example: Testing Group Filter

typescript
1import { mockedGetApiV1BetaWorkloads } from '@mocks/fixtures/workloads/get'
2
3it('shows only workloads from the selected group', async () => {
4  // Default mock returns workloads from multiple groups
5  // Add conditional override for 'production' group
6  mockedGetApiV1BetaWorkloads.conditionalOverride(
7    ({ query }) => query.group === 'production',
8    (data) => ({
9      ...data,
10      workloads: [
11        { name: 'prod-server-1', group: 'production', status: 'running' },
12        { name: 'prod-server-2', group: 'production', status: 'running' },
13      ],
14    })
15  )
16
17  render(<WorkloadsList group="production" />)
18
19  // If component sends ?group=production, it gets the filtered data
20  // If component forgets the param, it gets default data with mixed groups
21  await waitFor(() => {
22    expect(screen.getByText('prod-server-1')).toBeVisible()
23    expect(screen.getByText('prod-server-2')).toBeVisible()
24  })
25
26  // These would appear if the filter param wasn't sent correctly
27  expect(screen.queryByText('dev-server')).not.toBeInTheDocument()
28})

Example: Testing Empty State

typescript
1it('shows empty message when group has no workloads', async () => {
2  mockedGetApiV1BetaWorkloads.conditionalOverride(
3    ({ query }) => query.group === 'empty-group',
4    () => ({ workloads: [] })
5  )
6
7  render(<WorkloadsList group="empty-group" />)
8
9  await waitFor(() => {
10    expect(screen.getByText(/no workloads found/i)).toBeVisible()
11  })
12})

Multiple Conditional Overrides

Chain multiple overrides for different conditions:

typescript
1mockedGetApiV1BetaWorkloads
2  .conditionalOverride(
3    ({ query }) => query.group === 'production',
4    () => ({ workloads: productionWorkloads })
5  )
6  .conditionalOverride(
7    ({ query }) => query.group === 'staging',
8    () => ({ workloads: stagingWorkloads })
9  )

Later overrides wrap earlier ones. If no predicate matches, the default fixture data is returned.

Simple Overrides (No Condition)

For test-scoped data changes without conditions, use .override():

typescript
1// Override for entire test - no condition
2mockedGetApiV1BetaGroups.override(() => ({
3  groups: [{ name: 'only-group', registered_clients: [] }],
4}))
5
6// Modify default data
7mockedGetApiV1BetaGroups.override((data) => ({
8  ...data,
9  groups: data.groups?.slice(0, 1),
10}))

Error Responses

Use .overrideHandler() for full control over the response:

typescript
1import { HttpResponse } from 'msw'
2
3// Return error
4mockedGetApiV1BetaGroups.overrideHandler(() =>
5  HttpResponse.json({ error: 'Server error' }, { status: 500 })
6)
7
8// Network failure
9mockedGetApiV1BetaGroups.overrideHandler(() => HttpResponse.error())

Automatic Reset

All overrides are automatically reset before each test via resetAllAutoAPIMocks() in vitest.setup.ts. No cleanup needed.

Reusable Scenarios

When the same response override is needed across many tests, define it as a scenario in the fixture instead of duplicating .override() calls.

Defining Scenarios (in fixtures)

typescript
1// In fixtures/workloads/get.ts
2export const mockedGetApiV1BetaWorkloads = AutoAPIMock<...>({
3  workloads: [/* default data */],
4}).scenario('empty', (mock) => mock.override(() => ({ workloads: [] })))

Using Scenarios (in tests)

typescript
1mockedGetApiV1BetaWorkloads.activateScenario('empty')

Scenario names are defined in renderer/src/common/mocks/scenarioNames.ts. Use existing names when possible to keep scenarios consolidated.

Related Skills

• testing-with-api-mocks - Auto-generated mocks and fixture basics
• testing-api-assertions - Verifying mutations with recordRequests() (create/update/delete only)