How to Implement 2026 API Mocking with MSW 2.0 and Jest 29.7

// msw-handlers.ts\n// MSW 2.0 uses the new setupWorker/setupServer API with stricter type safety\nimport { http, HttpResponse, HttpHandler, delay } from 'msw';\nimport { setupServer, SetupServerApi } from 'msw/node';\n\n// Define type-safe mock data matching the JSONPlaceholder User schema\ninterface MockUser {\n  id: number;\n  name: string;\n  email: string;\n  phone: string;\n  website: string;\n}\n\n// Static mock dataset to avoid random flakiness in tests\nconst MOCK_USERS: MockUser[] = [\n  {\n    id: 1,\n    name: 'Leanne Graham',\n    email: 'leanne.graham@reqres.in',\n    phone: '1-770-736-8031 x56442',\n    website: 'hildegard.org',\n  },\n  {\n    id: 2,\n    name: 'Ervin Howell',\n    email: 'ervin.howell@reqres.in',\n    phone: '010-692-6593 x09125',\n    website: 'anastasia.net',\n  },\n];\n\n/**\n * Creates MSW 2.0 handlers for the /api/users endpoint\n * Includes error simulation, delay injection, and type-safe responses\n * @param {boolean} shouldError - Whether to simulate a 500 error\n * @param {number} simulatedDelayMs - Artificial delay to test loading states\n * @returns {HttpHandler[]} Array of MSW HTTP handlers\n */\nexport const createUserHandlers = (\n  shouldError: boolean = false,\n  simulatedDelayMs: number = 0\n): HttpHandler[] => {\n  return [\n    // Handle GET /api/users\n    http.get('/api/users', async () => {\n      // Inject simulated network delay if configured\n      if (simulatedDelayMs > 0) {\n        await delay(simulatedDelayMs);\n      }\n\n      // Simulate server error if flag is set\n      if (shouldError) {\n        return HttpResponse.json(\n          { error: 'Internal Server Error' },\n          { status: 500, statusText: 'Internal Server Error' }\n        );\n      }\n\n      // Return type-safe mock response\n      return HttpResponse.json(MOCK_USERS, {\n        status: 200,\n        headers: {\n          'Content-Type': 'application/json',\n          'X-Mock-Source': 'msw-2.0',\n        },\n      });\n    }),\n\n    // Handle GET /api/users/:id with parameter validation\n    http.get('/api/users/:id', async ({ params }) => {\n      const userId = Number(params.id);\n\n      // Validate path parameter\n      if (isNaN(userId) || userId < 1) {\n        return HttpResponse.json(\n          { error: 'Invalid user ID' },\n          { status: 400, statusText: 'Bad Request' }\n        );\n      }\n\n      const user = MOCK_USERS.find((u) => u.id === userId);\n\n      if (!user) {\n        return HttpResponse.json(\n          { error: 'User not found' },\n          { status: 404, statusText: 'Not Found' }\n        );\n      }\n\n      return HttpResponse.json(user, {\n        status: 200,\n        headers: { 'Content-Type': 'application/json' },\n      });\n    }),\n  ];\n};\n\n/**\n * Initializes MSW 2.0 server for Node.js (Jest) environment\n * @param {HttpHandler[]} handlers - Custom handlers to add to the server\n * @returns {SetupServerApi} Configured MSW server instance\n */\nexport const initializeMswServer = (handlers: HttpHandler[] = []): SetupServerApi => {\n  const defaultHandlers = createUserHandlers();\n  const server = setupServer(...defaultHandlers, ...handlers);\n\n  // Global error handler for unhandled requests\n  server.events.on('request:unhandled', ({ request }) => {\n    console.error(`Unhandled request to ${request.url}`);\n  });\n\n  return server;\n};\n

// user-service.test.ts\n// Jest 29.7 native ESM support requires explicit jest config, no ts-jest transpilation needed for modern TS\nimport { initializeMswServer } from './msw-handlers';\nimport { createUserHandlers } from './msw-handlers';\n\n// Initialize MSW server before all tests\nlet mswServer: ReturnType;\n\nbeforeAll(() => {\n  mswServer = initializeMswServer();\n  mswServer.listen({ onUnhandledRequest: 'error' });\n});\n\n// Reset handlers between tests to avoid cross-test contamination\nafterEach(() => {\n  mswServer.resetHandlers();\n});\n\n// Cleanup after all tests\nafterAll(() => {\n  mswServer.close();\n});\n\n// Mock user service module under test\ninterface User {\n  id: number;\n  name: string;\n  email: string;\n}\n\n/**\n * Fetches all users from the API\n * Includes retry logic and error handling matching production code\n */\nconst fetchUsers = async (): Promise => {\n  try {\n    const response = await fetch('/api/users');\n    if (!response.ok) {\n      throw new Error(`Failed to fetch users: ${response.statusText}`);\n    }\n    return await response.json();\n  } catch (error) {\n    console.error('User fetch error:', error);\n    throw error;\n  }\n};\n\n/**\n * Fetches single user by ID\n * Includes input validation and error propagation\n */\nconst fetchUserById = async (id: number): Promise => {\n  if (id < 1 || isNaN(id)) {\n    throw new Error('Invalid user ID');\n  }\n\n  try {\n    const response = await fetch(`/api/users/${id}`);\n    if (!response.ok) {\n      throw new Error(`Failed to fetch user: ${response.statusText}`);\n    }\n    return await response.json();\n  } catch (error) {\n    console.error(`User ${id} fetch error:`, error);\n    throw error;\n  }\n};\n\ndescribe('User Service Integration Tests with MSW 2.0 and Jest 29.7', () => {\n  // Test 1: Successful fetch of all users\n  test('fetches all users from mocked API', async () => {\n    const users = await fetchUsers();\n    expect(users).toHaveLength(2);\n    expect(users[0].name).toBe('Leanne Graham');\n    expect(users[1].email).toBe('ervin.howell@reqres.in');\n  });\n\n  // Test 2: Fetch single user by valid ID\n  test('fetches single user by valid ID', async () => {\n    const user = await fetchUserById(1);\n    expect(user.id).toBe(1);\n    expect(user.email).toBe('leanne.graham@reqres.in');\n  });\n\n  // Test 3: Handle 404 for non-existent user\n  test('throws error for non-existent user', async () => {\n    await expect(fetchUserById(999)).rejects.toThrow('Not Found');\n  });\n\n  // Test 4: Handle server error (500)\n  test('handles server error responses', async () => {\n    // Override default handlers to simulate 500 error\n    mswServer.use(...createUserHandlers(true));\n    await expect(fetchUsers()).rejects.toThrow('Internal Server Error');\n  });\n\n  // Test 5: Test loading state with simulated delay\n  test('handles delayed responses within timeout', async () => {\n    // Set 200ms delay, test should complete within 500ms timeout\n    mswServer.use(...createUserHandlers(false, 200));\n    const usersPromise = fetchUsers();\n    const timeoutPromise = new Promise((_, reject) => \n      setTimeout(() => reject(new Error('Timeout')), 500)\n    );\n\n    await expect(Promise.race([usersPromise, timeoutPromise])).resolves.toHaveLength(2);\n  });\n\n  // Test 6: Input validation for invalid user ID\n  test('throws error for invalid user ID', async () => {\n    await expect(fetchUserById(-1)).rejects.toThrow('Invalid user ID');\n    await expect(fetchUserById(NaN)).rejects.toThrow('Invalid user ID');\n  });\n});\n

// jest.config.ts\n// Jest 29.7 native ESM support requires this config to avoid transpilation overhead\nimport type { Config } from 'jest';\n\nconst config: Config = {\n  // Use ts-jest only for type checking, not transpilation (ESM native)\n  preset: 'ts-jest/presets/default-esm',\n  // Enable experimental ESM support in Jest 29.7\n  extensionsToTreatAsEsm: ['.ts'],\n  // Transform TypeScript files with ts-jest, preserve ESM syntax\n  transform: {\n    '^.+\\\\.tsx?$': [\n      'ts-jest',\n      {\n        useESM: true,\n        tsconfig: './tsconfig.test.json',\n        // Disable diagnostics in Jest to speed up execution (use tsc for type checks)\n        diagnostics: false,\n      },\n    ],\n  },\n  // Module name mapper for absolute imports\n  moduleNameMapper: {\n    '^@/(.*)$': '/src/$1',\n  },\n  // Test environment must be node for MSW 2.0 Node.js server\n  testEnvironment: 'node',\n  // Global setup to initialize MSW once before all test suites\n  globalSetup: '/test/global-setup.ts',\n  // Global teardown to cleanup MSW after all test suites\n  globalTeardown: '/test/global-teardown.ts',\n  // Setup files to run before each test suite\n  setupFilesAfterSetup: ['/test/setup.ts'],\n  // Increase test timeout for delayed network responses\n  testTimeout: 10000,\n  // Collect coverage from src directory\n  collectCoverageFrom: ['src/**/*.{ts,tsx}', '!src/**/*.d.ts'],\n  // Coverage thresholds to enforce code quality\n  coverageThreshold: {\n    global: {\n      branches: 80,\n      functions: 80,\n      lines: 80,\n      statements: 80,\n    },\n  },\n  // Verbose output for easier debugging\n  verbose: true,\n};\n\nexport default config;\n\n// test/global-setup.ts\n// Global setup runs once before all test suites\nimport { initializeMswServer } from '../msw-handlers';\n\nexport default async () => {\n  // Initialize MSW server and store instance globally for teardown\n  const server = initializeMswServer();\n  server.listen();\n  // Attach server to global object for access in teardown\n  (global as any).__MSW_SERVER__ = server;\n};\n\n// test/global-teardown.ts\n// Global teardown runs once after all test suites\nexport default async () => {\n  const server = (global as any).__MSW_SERVER__;\n  if (server) {\n    server.close();\n  }\n};\n\n// test/setup.ts\n// Runs before each test suite\nimport { resetAllMocks } from '../msw-handlers';\n\nbeforeEach(() => {\n  // Reset MSW handlers before each test to avoid cross-test contamination\n  const server = (global as any).__MSW_SERVER__;\n  if (server) {\n    server.resetHandlers();\n  }\n});\n

// Bad: Module mock (fragile)\njest.mock('./api-client', () => ({\n  getUsers: jest.fn().mockResolvedValue([{ id: 1, name: 'Test' }]),\n}));\n\n// Good: MSW network interception (robust)\nconst server = setupServer(\n  http.get('/api/users', () => HttpResponse.json([{ id: 1, name: 'Test' }]))\n);\n

// jest.config.ts ESM snippet\nexport default {\n  extensionsToTreatAsEsm: ['.ts'],\n  transform: {\n    '^.+\\\\.tsx?$': ['ts-jest', { useESM: true, diagnostics: false }],\n  },\n};\n

// MSW error scenario handler\nhttp.post('/api/payments', async ({ request }) => {\n  const body = await request.json();\n  if (!body.amount || body.amount < 0) {\n    return HttpResponse.json(\n      { error: 'Invalid payment amount' },\n      { status: 400 }\n    );\n  }\n  // Simulate Stripe 402 Payment Required\n  return HttpResponse.json(\n    { error: 'Insufficient funds' },\n    { status: 402 }\n  );\n});\n

msw-jest-2026-example/\n├── src/\n│   ├── user-service.ts       # Production user service code\n│   └── types.ts              # Shared TypeScript types\n├── test/\n│   ├── global-setup.ts       # Jest global setup for MSW\n│   ├── global-teardown.ts    # Jest global teardown for MSW\n│   └── setup.ts              # Per-suite test setup\n├── msw-handlers.ts           # MSW 2.0 handler definitions\n├── user-service.test.ts      # Jest 29.7 test suite\n├── jest.config.ts            # Jest 29.7 ESM configuration\n├── tsconfig.json             # TypeScript 5.3 config\n├── tsconfig.test.json        # Test-specific TypeScript config\n├── package.json              # Dependencies (MSW 2.0, Jest 29.7)\n└── README.md                 # Setup and run instructions\n