Intercepting requests

Learn how to intercept outgoing requests.

To inspect and handle outgoing requests you have to intercept them first. In MSW, you do that by defining functions called request handlers. Here’s an example of one:

http.get('/resource', ({ request }) => {
  console.log(request.method, request.url)
})

This is a request handler that will intercept all GET /resource requests and print their information to the console.

This page will get you familiar with the structure of request handlers and the supported ways of intercepting HTTP requests. Please refer to additional resources in this section on particular use cases and best practices.

Anatomy of a request handler

Every request handler consists of two parts: a predicate and a response resolver.

//       👇 This is a predicate.
http.get('/resource', () => {})
//                    👆 This is a resolver.

A predicate decides which requests to intercept, and a resolver decides what to do with those requests. On this page, we will take a look at the different ways to define a predicate for your request handlers. You can learn more about handling requests in the “Mocked responses” section:

Handling requests

Different ways to handle an intercepted request.

Predicate

Request URL

You can provide a string as a request handler predicate that represents an entire request URL or its portion. MSW will use path-to-regexp@6 to match your predicate against outgoing requests to determine if they match. We highly recommend you familiarize yourself with the feature set of that library.

Relative URL

When you provide a relative request URL as a predicate, it will be resolved against the current document (document.baseUri). This is handy for in-browser mocking, but bear in mind that you need to configure the base URL in your Node.js tests because that’s not a thing in Node.js.

http.get('/users/:id', () => {})

This request handler will match the GET http://localhost:3000/users/abc-123 request, given your application is running at http://localhost:3000.

Query/search parameters

Query parameters do not describe resource paths but rather additional data sent with the request. As such, they must not be present in the request predicate. Any query parameters accidentally included in the request predicate will automatically be removed and have no effect on the URL matching.

You intercepted requests can still have query parameters, and you can access them in the response resolver. Learn more about how on this page:

Query parameters

Read and write request query parameters.

Absolute URL

When you provide an absolute request URL as a predicate, the outgoing request must match its scheme, host, and pathname to trigger the request handler.

http.post('https://api.github.com/repos/:owner/:repo', () => {})

Special tokens

When using a string request predicate, you can include special tokens in it to represent different matching behaviors:

  • * (wildcard), to match any URL or a portion of the URL in its place;
  • :foo (parameter), to match a named parameter in the URL (see Path parameters).

Regular expression

You can provide a regular expression as a request handler predicate. MSW will test it against the outgoing request URLs to determine if they match.

http.get(/\/settings\/(profile|settings)/, () => {})

It’s generally recommended to use request paths/URLs predicates, but you can rely on regular expressions for the most complex matching scenarios.

Response resolver

The following properties are available on the response resolver object argument for http.* handlers:

PropertyTypeDescription
requestRequestFetch API Request representation of the intercepted request.
requestIdstringUUID representing the intercepted request.
paramsRecord<string, string | string[]>Request path parameters (e.g. :userId).
cookiesRecord<string, string>Parsed request cookies.
http.get('/resource', ({ request, params, cookies }) => {})

Next steps

Now that you know how to intercept HTTP requests, proceed by learning how to handle their responses:

Mocking responses

Different ways to handle an intercepted HTTP request.