Request matching

To determine which outgoing requests should be mocked, Mock Service Worker performs request matching—a process of executing a request handler predicate against the actual request.

Request matching substantially differs based on the request handler (rest/graphql) that's being used. See the summary of that difference between the standard request handlers of the library below.

REST API

Working with rest.* request handlers allows you to match requests by the following criteria:

• Request method;
• Request URL.

Request method

To match REST API requests by their method call the respective method on the rest request handler object. Here's a few examples:

• rest.get() matches GET requests;
• rest.delete() matches DELETE requests.

Request URL

There are multiple ways to match a REST API request by its URL:

• Provide an exact request URL;
• Use a path;
• Use a RegExp.

Exact request URL

Provided an exact request URL string, only those request that strictly match that string are mocked.

1// Only "POST https://api.backend.dev/users" requests match this handler
2rest.post('https://api.backend.dev/users', responseResolver)
3
4// Given your application runs on "http://localhost:8080",
5// this request handler URL gets resolved to "http://localhost:8080/invoices"
6rest.get('/invoices', invoicesResolver)

Note that relative URL are resolved against the current location (location.origin).

Path

Mock Service Worker uses an Express-like path syntax to match requests.

Path is an abstraction over regular expression for shorthand wildcard and path parameters definition. See the examples of using paths below.

Path with wildcard

1// Matches:
2// - /users/admin
3// - /users/octocat
4rest.get('/users/*', responseResolver),

Note that prepending a wildcard to a path would capture requests regardless of origin. You rarely want to do something like */users, as it may easily produce ambiguous matches.

Path with parameters

To add a parameter to your request path use the :paramName format. Parsed parameters values is available in the req.params object of the response resolver.

1import { setupWorker, rest } from 'msw'
2
3setupWorker(
4  // Given "POST https://api.backend.dev/user/abc-123" request,
5  rest.post('https://api.backend.dev/user/:userId', (req, res, ctx) => {
6    // `userId` value becomes "abc-123"
7    const { userId } = req.params
8  }),
9)

RegExp

When provided a regular expression, all request URL that match that expression will be captured, regardless of the their origin.

1// This request handler would match all these requests:
2// - DELETE http://localhost:8080/posts/
3// - DELETE https://backend.dev/user/posts/
4rest.delete(/\/posts\//, responseResolver)

Unlike paths, regular expressions use weak comparison, supporting partial matches.

GraphQL API

Working with graphql.* request handlers allows you to match GraphQL requests (operations) by the following criteria:

• Operation kind (query/mutation);
• Operation name.

Both GET and POST requests are supported according to the GraphQL specification.

Operation kind

Execute a method of the graphql request handler object that corresponds to a GraphQL operation kind to target operations of that kind. For example:

• graphql.query() to match GraphQL queries;
• graphql.mutation() to match GraphQL mutations.

Operation name

By default, all GraphQL operation names are matched regardless of origin.

1// This will match a "GetUser" operation against any host
2// (i.e. both "https://api.github.com/v4" and "http://localhost:8080")
3graphql.query('GetUser', resolveUser)

Use graphql.link to target GraphQL operations against a specific endpoint.

RegExp

You can use a regular expression to match multiple GraphQL operation names.

1// Matches all GraphQL queries that end with "User".
2graphql.query(/User$/, resolveAnyUserQuery)