Mock Service Worker

Common errors

• SyntaxError: Named export 'setupWorker' not found. The requested module 'msw' does not provide an export named 'setupWorker'

  cause Attempting to use CommonJS `require` or incorrect ESM import syntax for MSW v2, which is ESM-only, or importing `setupWorker` from the wrong entry point (`msw` instead of `msw/browser`).
  fix Ensure you are using `import { setupWorker } from 'msw/browser'` and that your project is configured for ESM. For Node.js, use `import { setupServer } from 'msw/node'`.

• Failed to register a Service Worker: A bad HTTP response code (404) was received when fetching the script.

  cause The `mockServiceWorker.js` file is not found at the expected path (usually the public root) by the browser when `worker.start()` is called.
  fix Verify that `mockServiceWorker.js` is present in your public directory and accessible. Run `npx msw init <PUBLIC_DIR_PATH>` to re-initialize it. Check your web server configuration to ensure it serves static files correctly from the root path. If using a custom path, specify it in `setupWorker({ serviceWorker: { url: '/custom/path/mockServiceWorker.js' } })`.

• TypeError: Cannot read properties of undefined (reading 'listen') at server.listen

  cause The `server` object returned by `setupServer` is either undefined or not properly instantiated, often due to incorrect import or setup in a Node.js environment.
  fix Ensure `setupServer` is correctly imported as `import { setupServer } from 'msw/node'` and that the `server` variable is assigned the result of `setupServer(...)`.

• Error: [MSW] The 'rest' handler is deprecated and will be removed in the next major version. Please use 'http' instead.

  cause Using the deprecated `rest` object from MSW v1 instead of the `http` object for defining request handlers in an MSW v2 environment.
  fix Replace `rest.get`, `rest.post`, `rest.put`, `rest.patch`, `rest.delete` with their `http` equivalents (e.g., `http.get`, `http.post`).

Warnings

• breaking MSW v2 is an ESM-only package and no longer supports CommonJS (`require`). All imports must use ESM syntax (`import`).
  Fix: Migrate your project to use ECMAScript Modules (ESM) syntax (`import ... from '...'`) and ensure your `package.json` has `"type": "module"` or uses `.mjs` file extensions. Update your bundler/build configuration if necessary.
• breaking The `rest` object for defining HTTP handlers was renamed to `http` in MSW v2. Similarly, the `graphql` object also underwent changes in its API.
  Fix: Replace `rest.get`, `rest.post`, etc., with `http.get`, `http.post`, and similar for other HTTP methods. Review the official migration guide for other API changes in v2, particularly for GraphQL handlers.
• breaking The package entry points for browser and Node.js setups changed in MSW v2. Browser setup now imports from `msw/browser` and Node.js from `msw/node`.
  Fix: Update your import statements: `import { setupWorker } from 'msw'` becomes `import { setupWorker } from 'msw/browser'` for browser usage, and `import { setupServer } from 'msw'` becomes `import { setupServer } from 'msw/node'` for Node.js usage.
• gotcha Ensuring the Service Worker script (`mockServiceWorker.js`) is correctly served at the root of your application's public directory is crucial for browser environments. Incorrect paths or server configurations can prevent the worker from registering.
  Fix: Run `npx msw init <PUBLIC_DIR_PATH>` to automatically generate/update the worker script. Verify that the `mockServiceWorker.js` file is accessible at the root of your application (e.g., `http://localhost:3000/mockServiceWorker.js`). If using a custom path, ensure `setupWorker` is configured with `serviceWorker.url`.
• gotcha When using MSW in Node.js test environments (e.g., Jest, Vitest), it's important to properly set up the lifecycle hooks (`beforeAll`, `afterAll`, `afterEach`) to start and stop the server and reset handlers.
  Fix: Wrap your `setupServer` calls in test framework lifecycle hooks: `beforeAll(() => server.listen());` `afterEach(() => server.resetHandlers());` `afterAll(() => server.close());` Refer to MSW documentation for specific test runner integrations.

Install

• npm install msw npm
• yarn add msw yarn
• pnpm add msw pnpm

Imports

• setupWorker
  wrong:

  const { setupWorker } = require('msw')

  correct:

  import { setupWorker } from 'msw/browser'

  Used for browser environments. MSW v2+ is an ESM-only package, so `require` syntax for `setupWorker` will fail. The entry point also changed from `msw` to `msw/browser` in v2.
• setupServer
  wrong:

  import { setupServer } from 'msw'

  correct:

  import { setupServer } from 'msw/node'

  Used for Node.js environments (e.g., testing). MSW v2+ requires importing from `msw/node`. `require` syntax will also fail.
• http
  wrong:

  import { rest } from 'msw'

  correct:

  import { http } from 'msw'

  The `http` object is used for defining REST API request handlers. In MSW v2, the `rest` object from v1 was renamed to `http` for clarity and consistency.
• HttpResponse

  import { HttpResponse } from 'msw'

  Provides utilities for constructing mock HTTP responses, including status, headers, and body. Commonly used within handler resolvers.

Quickstart

This quickstart demonstrates setting up a browser-based Mock Service Worker to intercept and respond to HTTP GET and POST requests, followed by actual `fetch` calls that are intercepted by the mock server.

import { setupWorker, http, HttpResponse } from 'msw';

// Define handlers for your API requests
const handlers = [
  http.get('https://example.com/api/user/:userId', ({ params }) => {
    const { userId } = params;
    if (userId === '123') {
      return HttpResponse.json(
        { id: '123', name: 'John Doe', email: 'john.doe@example.com' },
        { status: 200 }
      );
    }
    return HttpResponse.json({ message: 'User not found' }, { status: 404 });
  }),
  http.post('https://example.com/api/users', async ({ request }) => {
    const newUser = await request.json();
    console.log('New user creation request:', newUser);
    return HttpResponse.json({ id: 'new-id', ...newUser }, { status: 201 });
  })
];

// Create a service worker instance
const worker = setupWorker(...handlers);

// Register the Service Worker in the browser
worker.start({
  onUnhandledRequest: 'warn' // Configure behavior for unhandled requests
});

console.log('MSW service worker started.');

// Example usage: Make a fetch request that will be intercepted by MSW
async function demonstrateMocking() {
  try {
    console.log('Fetching user 123...');
    const userResponse = await fetch('https://example.com/api/user/123');
    const userData = await userResponse.json();
    console.log('Fetched user (mocked):', userData);

    console.log('Creating a new user...');
    const createUserResponse = await fetch('https://example.com/api/users', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ name: 'Jane Smith', email: 'jane.smith@example.com' })
    });
    const newUserData = await createUserResponse.json();
    console.log('Created user (mocked):', newUserData);
  } catch (error) {
    console.error('Fetch error:', error);
  }
}

demonstrateMocking();