toolhive-studio: Skill for Claude Code

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