Mocking REST API

You are viewing the legacy documentation. It contains outdated information and is no longer maintained.

Please refer to https://mswjs.io/docs for the actual documentation of Mock Service Worker.

Introduction

This tutorial is going to take you through the process of mocking REST API.

Please make sure you have completed the Getting started process before continuing with this tutorial.

Imports

Let's start by including two essential functions from the library's package:

  • setupWorker, which describes which endpoints to mock;

  • rest, a namespace that contains a bunch of utilities for mocking REST API.

import { setupWorker, rest } from 'msw'

You can read more about those functions in more detail, but we are not going to focus on them as a part of this tutorial.

Declaration

As the next step, let's tell MSW which endpoints we would like to mock. To do that, call the setupWorker function and provide the relevant REST API methods calls from the rest namespace to it.

setupWorker(
rest.get('/users', null),
rest.put('/posts/:postid'), null)
)

In the example above we have specified two request handlers:

  • /users. As this stars with the slash ("/"), only those requests fired from the same origin will match this route. For example, if your application was running at http://localhost:8080, then the request to http://localhost:8080/users would match, while https://github.com/users would not.

  • /posts/:postId. Similar to the previous path, this one is tight to the current origin. In this one, however, we define the postId parameter that would be taken upon the URL match.

Response resolvers

When we defined our request handlers (rest.get and rest.post()) we left the second argument as null intentionally. Now we are going to provide it.

The second argument to a request handler function is a response resolver—a function that determines how to resolve a response. That response resolver function accepts three arguments:

  • req, an information about the request that happened;

  • res, a functional utility to compose the next response;

  • context, a group of utilities to help you get the response you need.

Declare two response resolvers for our previously defined mocking routes:

setupWorker(
rest.get('/users', (req, res, ctx) => {
return res(
ctx.status(403),
ctx.json(
[
{ firstName: 'John', lastName: 'Maverick' },
{ firstName: 'Cathaline', lastName: 'McCoy' },
]
)
)
}),
rest.put('/posts/:postId', (req, res, ctx) => {
const { postId } = req.params
return res(
ctx.delay(2000),
ctx.status(200),
ctx.json({
error: 'Unauthorized user'
})
)
})
)

Let's analyze what's happening in this code example step by step.

First, let's start with the rest.get request handler. Its response resolver returns the call to the resfunction, which describes how to mock the response. In our case we pass two calls to context utilities as the arguments to that res function call:

  • ctx.status(403), to return a response with the status code 403;

  • ctx.json([...]), to return an application/json type body containing two mocked objects that represent users.

Now let's focus on the rest.put handler. Similar to the previous one, we return the call to the res function, but this time we delay the response by 2s (ctx.delay(2000)), return the 200 OK status code (ctx.status(200)), and a JSON body with a mocked error property. Effectively, we are mocking a server error when attempting to create a new post while being unauthorized.

Running Service Worker

Once we call the setupWorker function with the request handlers we need, it returns an object with the start function. We need to call that function in order for MSW to start the Service Worker responsible for response mocking.

import { setupWorker, rest } from 'msw'
const worker = setupWorker(
// Our request handlers declared previously
rest.get('/users', ...),
rest.put('/posts/:postId', ...)
)
// Calling the "start" function launches the Service Worker
worker.start()

Upon refreshing the page, you should see the confirmation message in the browser's console of your application. Any requests matching the defined request handlers are now mocked.

Verify & Inspect

With the Mock Service Worker running, dispatch a request that would match any of the defined paths to see the mocking in action. For example, if your application performs the following request:

fetch('http://localhost:3000/posts/abc-123', { method: 'PUT' })

Open your DevTools and go to the "Network" tab. You should see the status code of such response as 200 OK (from ServiceWorker), which states that the request was handled by Mock Service Worker.

Chrome DevTools "Network" tab screenshot with the PUT request being mocked by Mock Service Worker.

Congratulations! You've now configured a client-side mocking using MSW. Continue reading about the library's concepts and API in this documentation to enhance your developer experience.