Life-cycle events

Life-cycle events allow you to subscribe to the internal library events occurring during the request/response handling. You are unlikely to use this API directly while developing or testing with MSW. There are, however, a number of use-cases when this API can be beneficial:

When you’re building a third-party library encapsulating MSW;
When you wish to transparently monitor requests/responses in your application;
When you wish to explicitly wait for a certain request/response.

Precautions

Read-only

The life-cycle events API is read-only. This means that you can observe requests and responses but cannot affect them. If you wish to affect the request handling, consider using setupWorker and/or setupServer instead.

Clone before reading

The request and response references exposed through this API are exact Fetch API representations of the occurred requests and received responses. If you wish to read their bodies, don’t forget to clone them.

server.events.on('request:start', async ({ request }) => {
  // Read the request body as text for every request
  // that occurs in your application.
  const payload = await request.clone().text()
})

Usage

The life-cycle events API is exposed under the events property on the worker/server instance:

// In the browser.
const worker = setupWorker(...handlers)
worker.events
 
// In Node.js.
const server = setupServer(...handlers)
server.events

The overall shape of the API is identical between the environments.

The events property contains a custom event emitter intentionally restricted to only listen to the events without the ability to emit them (emitting events is performed by the library). You can use methods like addListener(), once() and removeListener() on the events object.

// Observe any outgoing requests in your application.
server.events.on('request:start', ({ request, requestId }) => {
  console.log('Outgoing request:', request.method, request.url)
})

Request events

`request:start`

The request:start event is emitted whenever a request occurs in your application. You can access the request reference in the argument of the listener.

worker.events.on('request:start', ({ request, requestId }) => {
  console.log('Outgoing request:', request.method, request.url)
})

`request:match`

The request:match event is emitted whenever an intercepted request has a corresponding request handler defined.

`request:unhandled`

The request:unhandled event is emitted whenever an intercepted request has no corresponding request handler defined and will be performed as-is.

`request:end`

The request:end event is emitted whenever a request has ended. This event is emitted for all requests, regardless if they were handled or not.

Response events

`response:mocked`

The response:mocked event is emitted whenever a mocked response is sent. You can access both the response reference and the respective request reference in the listener to this event.

server.events.on('response:mocked', ({ request, requestId, response }) => {
  console.log(
    '%s %s received %s %s',
    request.method,
    request.url,
    response.status,
    response.statusText
  )
})

server.events.on('unhandledException', ({ request, requestId, error }) => {
  console.log('%s %s errored! See details below.', request.method, request.url)
  console.error(error)
})

Removing listeners

`removeListener()`

name, String, the event name to remove.
listener, Function, the event listener to remove.

server.events.removeListener('request:start', requestStartListener)

`removeAllListeners()`

name, String (Optional), the event name to remove.

When called without any arguments, .removeAllListeners() removes all events attached to the current worker/server instance:

server.events.removeAllListeners()

You can provide a name argument to only remove the listeners for the respective event:

server.events.removeAllListeners('request:start')