mswjs / msw

Mock Service Worker (MSW) is an API mocking library for browser and Node that intercepts outgoing requests using Service Workers.

Features

• Server-less. Mocking that doesn't establish any servers, operating entirely in a browser;
• Seamless. Forget about stubs and hacks that make your code smell. Leverage a dedicated layer of interception to keep your code clean and shiny.
• Deviation-free. Request the same resources you would in production, and mock their responses. No more conditional URLs, no more mock-specific parts of code in your app.
• Mocking as a tool. Enable, change, disable mocking on runtime instantly without any compilations or rebuilds. Control the MSW lifecycle from your browser's DevTools;
• Essentials. Use Express-like syntax to define which requests to mock. Respond with custom status codes, headers, delays, or create custom response resolvers.

"This is awesome."

– Kent C. Dodds

Documentation

• Documentation
• Getting started
• Recipes

Quick start

Install the library in your project:

$ npm install msw

Copy the Service Worker file that's responsible for requests interception. Use a designated CLI to do that (from your project's root directory):

$ npx msw init <PUBLIC_DIR>

Provide the path to your public directory instead of the <PUBLIC_DIR> placeholder above. Your public directory is usually a directory being served by a server (i.e. ./public or ./dist). Running this command will place the mockServiceWorker.js file into given directory.

For example, in Create React App you would run: npx msw init ./public

Once the Service Worker has been copied, we can continue with creating a mocking definition file. For the purpose of this short tutorial we are going to keep all our mocking logic in the mocks.js file, but the end file structure is up to you.

$ touch mocks.js

Open that file and follow the example below to create your first mocking definition:

// mocks.js
// 1. Import mocking utils
import { setupWorker, rest } from 'msw'

// 2. Define request handlers and response resolvers
const worker = setupWorker(
  rest.get('https://github.com/octocat', (req, res, ctx) => {
    return res(
      ctx.delay(1500),
      ctx.status(202, 'Mocked status'),
      ctx.json({
        message: 'This is a mocked error',
      }),
    )
  }),
)

// 3. Start the Service Worker
worker.start()

Import the mocks.js module into your application to enable the mocking. You can import the mocking definition file conditionally, so it's never loaded on production:

// src/index.js
if (process.env.NODE_ENV === 'development') {
  require('./mocks')
}

Verify the MSW is running by seeing a successful Service Worker activation message in the browser's console. Now any outgoing request of your application are intercepted by the Service Worker, signaled to the client-side library, and matched against the mocking definition. If a request matches any definition, its response is being mocked and returned to the browser.

Notice the 202 Mocked status (from ServiceWorker) status in the response.

We have prepared a set of step-by-step tutorials to get you started with mocking the API type you need. For example, did you know you can mock a GraphQL API using MSW? Find detailed instructions in the respective tutorials below.

Tutorials

• Mocking REST API
• Mocking GraphQL API

Examples

• Usage examples