Skip to main content
skill CX Codex

api-mock-server — Claude Code skill: what it does, how to install

api-mock-server configures mock API servers for testing and frontend development using MSW, json-server, or custom handlers.

MIT 300 installs ★ 64 updated 2026-01-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add patricio0312rev/skills --skill api-mock-server -a claude-code
Open on GitHub

What api-mock-server does

This skill provides structured patterns to mock network traffic. It covers Mock Service Worker setups for both browser environments using setupWorker and Node test suites via setupServer. Handlers include TypeScript CRUD logic, user fixtures, artificial delays, and simulated error responses such as 404 or 500.

It also includes templates for GraphQL queries and mutations. When a standalone mock backend fits better, the skill guides you through json-server configuration with a db.json fixture file, custom delay rules, and route rewrites.

MSW browser interception requires generating worker assets beforehand via npx msw init ./public --save.

What it helps with

  • set up MSW handlers for unit and integration tests in Vitest or Jest
  • spin up a quick json-server mock API from a db.json file
  • test UI empty states and HTTP error handling without a running backend
  • mock GraphQL queries and mutations alongside REST endpoints

Example prompts for the agent

  • Set up MSW handlers for our /api/users endpoints with Vitest
  • Create a json-server configuration with custom routes and delay
  • Add mock GraphQL handlers for GetUsers and CreateUser operations

How to install api-mock-server

1Skills CLI (Vercel)

npx skills add patricio0312rev/skills --skill api-mock-server -a claude-code

2Manually: put the files in place

~/.claude/skills/api-mock-server/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/api-mock-server/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about api-mock-server

How to install api-mock-server in Claude Code?

Run npx skills add patricio0312rev/skills --skill api-mock-server -a claude-code. The definition will be saved to ~/.claude/skills/api-mock-server/SKILL.md.

What tools does api-mock-server use?

It targets Mock Service Worker (MSW) across browser and Node runtimes, alongside standalone json-server setups.

Can I test server errors without changing global handlers?

Yes. You can override specific routes inside individual tests using server.use() with an error response status.

Source text

SKILL.md · MIT
---
name: api-mock-server
description: Creates mock API servers for testing and development with MSW, json-server, or custom handlers. Use when users request "API mocking", "mock server", "MSW setup", "test fixtures", or "mock API responses".
---

# API Mock Server

Create realistic mock APIs for testing and development.

## Core Workflow

1. **Choose approach**: MSW, json-server, custom
2. **Define handlers**: Mock endpoints
3. **Setup fixtures**: Test data
4. **Configure scenarios**: Success/error states
5. **Integrate tests**: Use in test suites
6. **Document mocks**: API contract

## MSW (Mock Service Worker)

### Installation

```bash
npm install -D msw
npx msw init ./public --save
```

### Handler Definition

```typescript
// mocks/handlers.ts
import { http, HttpResponse, delay } from 'msw';

// Types
interface User {
  id: string;
  name: string;
  email: string;
  role: 'admin' | 'user';
}

interface CreateUserInput {
  name: string;
  email: string;
}

// Fixtures
const users: User[] = [
  { id: '1', name: 'John Doe', email: '[email protected]', role: 'admin' },
  { id: '2', name: 'Jane Smith', email: '[email protected]', role: 'user' },
];

// Handlers
export const handlers = [
  // GET /api/users
  http.get('/api/users', async () => {
    await delay(100);
    return HttpResponse.json(users);
  }),

  // GET /api/users/:id
  http.get('/api/users/:id', async ({ params }) => {
    await delay(50);
    const user = users.find((u) => u.id === params.id);

    if (!user) {
      return new HttpResponse(null, { status: 404 });
    }

    return HttpResponse.json(user);
  }),

  // POST /api/users
  http.post('/api/users', async ({ request }) => {
    await delay(100);
    const body = (await request.json()) as CreateUserInput;

    const newUser: User = {
      id: String(users.length + 1),
      name: body.name,
      email: body.email,
      role: 'user',
    };

    users.push(newUser);

    return HttpResponse.json(newUser, { status: 201 });
  }),

  // PUT /api/users/:id
  http.put('/api/users/:id', async ({ params, request }) => {
    await delay(50);
    const body = (await request.json()) as Partial<User>;
    const index = users.findIndex((u) => u.id === params.id);

    if (index === -1) {
      return new HttpResponse(null, { status: 404 });
    }

    users[index] = { ...users[index], ...body };

    return HttpResponse.json(users[index]);
  }),

  // DELETE /api/users/:id
  http.delete('/api/users/:id', async ({ params }) => {
    await delay(50);
    const index = users.findIndex((u) => u.id === params.id);

    if (index === -1) {
      return new HttpResponse(null, { status: 404 });
    }

    users.splice(index, 1);

    return new HttpResponse(null, { status: 204 });
  }),
];
```

### Setup for Browser

```typescript
// mocks/browser.ts
import { setupWorker } from 'msw/browser';
import { handlers } from './handlers';

export const worker = setupWorker(...handlers);
```

```typescript
// main.tsx or app entry
async function enableMocking() {
  if (process.env.NODE_ENV === 'development') {
    const { worker } = await import('./mocks/browser');
    return worker.start({
      onUnhandledRequest: 'bypass',
    });
  }
}

enableMocking().then(() => {
  // Render app
});
```

### Setup for Node (Tests)

```typescript
// mocks/server.ts
import { setupServer } from 'msw/node';
import { handlers } from './handlers';

export const server = setupServer(...handlers);
```

```typescript
// tests/setup.ts (Jest or Vitest)
import { beforeAll, afterEach, afterAll } from 'vitest';
import { server } from '../mocks/server';

beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());
```

### Test-Specific Handlers

```typescript
// tests/users.test.ts
import { http, HttpResponse } from 'msw';
import { server } from '../mocks/server';
import { render, screen, waitFor } from '@testing-library/react';
import { UserList } from '../components/UserList';

describe('UserList', () => {
  it('displays users', async () => {
    render(<UserList />);

    await waitFor(() => {
      expect(screen.getByText('John Doe')).toBeInTheDocument();
    });
  });

  it('handles empty state', async () => {
    server.use(
      http.get('/api/users', () => {
        return HttpResponse.json([]);
      })
    );

    render(<UserList />);

    await waitFor(() => {
      expect(screen.getByText('No users found')).toBeInTheDocument();
    });
  });

  it('handles server error', async () => {
    server.use(
      http.get('/api/users', () => {
        return new HttpResponse(null, { status: 500 });
      })
    );

    render(<UserList />);

    await waitFor(() => {
      expect(screen.getByText('Error loading users')).toBeInTheDocument();
    });
  });

  it('handles network error', async () => {
    server.use(
      http.get('/api/users', () => {
        return HttpResponse.error();
      })
    );

    render(<UserList />);

    await waitFor(() => {
      expect(screen.getByText('Network error')).toBeInTheDocument();
    });
  });
});
```

### GraphQL Mocking

```typescript
// mocks/graphql-handlers.ts
import { graphql, HttpResponse } from 'msw';

export const graphqlHandlers = [
  graphql.query('GetUsers', () => {
    return HttpResponse.json({
      data: {
        users: [
          { id: '1', name: 'John', email: '[email protected]' },
          { id: '2', name: 'Jane', email: '[email protected]' },
        ],
      },
    });
  }),

  graphql.mutation('CreateUser', ({ variables }) => {
    return HttpResponse.json({
      data: {
        createUser: {
          id: '3',
          name: variables.input.name,
          email: variables.input.email,
        },
      },
    });
  }),

  graphql.query('GetUser', ({ variables }) => {
    if (variables.id === 'not-found') {
      return HttpResponse.json({
        data: { user: null },
        errors: [{ message: 'User not found' }],
      });
    }

    return HttpResponse.json({
      data: {
        user: { id: variables.id, name: 'John', email: '[email protected]' },
      },
    });
  }),
];
```

## Json-Server

### Configuration

```json
// db.json
{
  "users": [
    { "id": "1", "name": "John Doe", "email": "[email protected]" },
    { "id": "2", "name": "Jane Smith", "email": "[email protected]" }
  ],
  "posts": [
    { "id": "1", "title": "Hello World", "authorId": "1" },
    { "id": "2", "title": "Another Post", "authorId": "2" }
  ],
  "comments": [
    { "id": "1", "text": "Great post!", "postId": "1" }
  ]
}
```

```javascript
// json-server.config.js
module.exports = {
  port: 3001,
  watch: true,
  delay: 100,
  routes: 'routes.json',
};
```

```json
// routes.json
{
  "/api/*": "/$1",
  "/users/:id/posts": "/posts?authorId=:id"
}
```

### Custom Routes

```javascript
// server.js
const jsonServer = require('json-server');
const server = jsonServer.create();
const router = jsonServer.router('db.json');
const middlewares = jsonServer.defaults();

// Custom middleware for auth
server.use((req, res, next) => {
  if (req.headers.authorization !== 'Bearer valid-token') {
    if (req.method !== 'GET') {
      return res.status(401).json({ error: 'Unauthorized' });
    }
  }
  next();
});

server.use(middlewares);

// Custom routes
server.get('/api/me', (req, res) => {
  res.json({ id: '1', name: 'Current User', email: '[email protected]' });
});

server.post('/api/login', (req, res) => {
  const { email, password } = req.body;
  if (email === '[email protected]' && password === 'password') {
    res.json({ token: 'valid-token', user: { id: '1', email } });
  } else {
    res.status(401).json({ error: 'Invalid credentials' });
  }
});

server.use('/api', router);

server.listen(3001, () => {
  console.log('Mock API running on http://localhost:3001');
});
```

## Fixture Factories

```typescript
// mocks/factories/user.ts
import { faker } from '@faker-js/faker';

interface User {
  id: string;
  name: string;
  email: string;
  role: 'admin' | 'user';
  createdAt: string;
}

export function createUser(overrides: Partial<User> = {}): User {
  return {
    id: faker.string.uuid(),
    name: faker.person.fullName(),
    email: faker.internet.email(),
    role: 'user',
    createdAt: faker.date.past().toISOString(),
    ...overrides,
  };
}

export function createUsers(count: number, overrides: Partial<User> = {}): User[] {
  return Array.from({ length: count }, () => createUser(overrides));
}

// mocks/factories/index.ts
export * from './user';
export * from './post';
export * from './comment';
```

### Using Factories in Tests

```typescript
// tests/components/UserProfile.test.tsx
import { createUser } from '../mocks/factories';
import { server } from '../mocks/server';
import { http, HttpResponse } from 'msw';

describe('UserProfile', () => {
  it('displays admin badge for admin users', async () => {
    const adminUser = createUser({ role: 'admin', name: 'Admin User' });

    server.use(
      http.get('/api/users/:id', () => {
        return HttpResponse.json(adminUser);
      })
    );

    render(<UserProfile userId={adminUser.id} />);

    await waitFor(() => {
      expect(screen.getByText('Admin User')).toBeInTheDocument();
      expect(screen.getByTestId('admin-badge')).toBeInTheDocument();
    });
  });
});
```

## Scenario-Based Mocking

```typescript
// mocks/scenarios.ts
import { http, HttpResponse, delay } from 'msw';
import { createUser, createUsers } from './factories';

export const scenarios = {
  default: [],

  emptyState: [
    http.get('/api/users', () => HttpResponse.json([])),
    http.get('/api/posts', () => HttpResponse.json([])),
  ],

  loadingState: [
    http.get('/api/users', async () => {
      await delay('infinite');
      return HttpResponse.json([]);
    }),
  ],

  errorState: [
    http.get('/api/users', () => {
      return new HttpResponse(null, { status: 500 });
    }),
  ],

  largeDataset: [
    http.get('/api/users', () => {
      return HttpResponse.json(createUsers(1000));
    }),
  ],

  slowNetwork: [
    http.get('/api/*', async ({ request }) => {
      await delay(2000);
      // Continue to default handler
      return undefined;
    }),
  ],
};

// Usage in tests
describe('UserList scenarios', () => {
  it('empty state', async () => {
    server.use(...scenarios.emptyState);
    // Test empty state
  });

  it('error state', async () => {
    server.use(...scenarios.errorState);
    // Test error handling
  });
});

// Usage in Storybook
export const EmptyState: Story = {
  parameters: {
    msw: {
      handlers: scenarios.emptyState,
    },
  },
};
```

## Playwright Integration

```typescript
// tests/e2e/api-mocking.spec.ts
import { test, expect } from '@playwright/test';

test.describe('API Mocking', () => {
  test('mock successful response', async ({ page }) => {
    await page.route('/api/users', async (route) => {
      await route.fulfill({
        status: 200,
        contentType: 'application/json',
        body: JSON.stringify([
          { id: '1', name: 'Mocked User', email: '[email protected]' },
        ]),
      });
    });

    await page.goto('/users');
    await expect(page.getByText('Mocked User')).toBeVisible();
  });

  test('mock error response', async ({ page }) => {
    await page.route('/api/users', async (route) => {
      await route.fulfill({
        status: 500,
        contentType: 'application/json',
        body: JSON.stringify({ error: 'Server Error' }),
      });
    });

    await page.goto('/users');
    await expect(page.getByText('Error loading users')).toBeVisible();
  });

  test('delay response', async ({ page }) => {
    await page.route('/api/users', async (route) => {
      await new Promise((resolve) => setTimeout(resolve, 3000));
      await route.fulfill({
        status: 200,
        body: JSON.stringify([]),
      });
    });

    await page.goto('/users');
    await expect(page.getByTestId('loading-spinner')).toBeVisible();
  });
});
```

## Best Practices

1. **Use factories**: Generate realistic data
2. **Define scenarios**: Reusable mock configurations
3. **Test edge cases**: Errors, empty states, loading
4. **Keep handlers simple**: One responsibility each
5. **Match production API**: Same contracts
6. **Delay appropriately**: Realistic timing
7. **Document mocks**: API contracts
8. **Reset between tests**: Clean state

## Output Checklist

Every API mock setup should include:

- [ ] MSW/json-server configuration
- [ ] Handler definitions
- [ ] Test setup integration
- [ ] Fixture factories
- [ ] Error scenarios
- [ ] Loading states
- [ ] GraphQL support (if needed)
- [ ] Browser integration
- [ ] E2E test mocking
- [ ] Documentation

© patricio0312rev · MIT · patricio0312rev/skills

Similar skills

All skills for Testing and QA →

From the same set148

The whole set →
page-layout-builder page-layout-builder builds page shells for dashboards, auth, settings, and CRUD flows. Use it when a new screen needs routes, navigation, and state placeholders. CX Codex +1 312installs curl-command-generator curl-command-generator turns Express, Next.js or Fastify route definitions into cURL commands you can paste into a terminal, auth headers and JSON bodies included. CX Codex +1 311installs data-integrity-auditor data-integrity-auditor is a Claude Code skill that finds database integrity problems and suggests fixes. It responds to requests about orphaned rows, broken relationships, and data quality. CX Codex +1 306installs queue-job-processor queue-job-processor sets up background job processing with BullMQ and Redis, covering typed queues, worker concurrency, and retry strategies. CX Codex +1 300installs guardrails-safety-filter-builder guardrails-safety-filter-builder builds a safety layer for an LLM app: masks personal data, catches prompt injection attempts and returns a refusal when a topic is off-policy. CX Codex +1 299installs sql-query-optimizer The sql-query-optimizer skill inspects SQL execution plans, suggests indexes, and rewrites queries. Use it when slow database queries need a concrete diagnosis. CX Codex +1 297installs dependency-vulnerability-triage dependency-vulnerability-triage is a Claude Code skill that turns npm audit and Snyk results into a prioritized patch plan with severity ratings, safe upgrade paths, and breaking-change analysis. CX Codex +1 296installs rfc-generator rfc-generator turns a technical proposal into a structured RFC: problem, solution, alternatives, risks and a rollout plan, instead of a blank page. CX Codex +1 294installs

Project sponsors

Companies that keep this analytics open