mswMock Service Worker
  1. Basics
  2. Request matching

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.

Requests with no corresponding request handlers are performed as-is (bypassed).

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.
Query parameters and hashes are removed from the URL during matching.

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.
Learn more about REST request handlers/docs/api/rest

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.com/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', invocesResolver)

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)

REPL

You can test how Mock Service Worker resolves paths against the actual request URL using the Path matching REPL.

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.

Learn more about the GraphQL request handlers/docs/api/graphql

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)