@mswjs/interceptors
Low-level HTTP/HTTPS/XHR/fetch request interception library.
Intercepts any requests issued by:
http.get
/http.request
https.get
/https.request
XMLHttpRequest
window.fetch
- Any third-party libraries that use the modules above (i.e.
axios
, request
, node-fetch
, supertest
, etc.)
Motivation
While there are a lot of network communication mocking libraries, they tend to use request interception as an implementation detail, giving you a high-level API that includes request matching, timeouts, retries, and so forth.
This library is a strip-to-bone implementation that provides as little abstraction as possible to execute arbitrary logic upon any request. It's primarily designed as an underlying component for high-level API mocking solutions such as Mock Service Worker.
How is this library different?
A traditional API mocking implementation in Node.js looks roughly like this:
import http from 'http'
function applyMock() {
const originalHttpRequest = http.request
http.request = function (...args) {
if (shouldMock(args)) {
return coerceToResponse.bind(this, mock)
}
return originalHttpRequest(...args)
}
}
This library deviates from such implementation and uses class extensions instead of module rewrites. Such deviation is necessary because, unlike other solutions that include request matching and can determine whether to mock requests before they actually happen, this library is not opinionated about the mocked/bypassed nature of the requests. Instead, it intercepts all requests and delegates the decision of mocking to the end consumer.
class NodeClientRequest extends ClientRequest {
async end(...args) {
const mockedResponse = await resolver(isomorphicRequest)
if (mockedResponse) {
this.respondWith(mockedResponse)
this.finish()
return
}
return super.end(...args)
}
}
By extending the native modules, this library actually constructs requests as soon as they are constructed by the consumer. This enables all the request input validation and transformations done natively by Node.js—something that traditional solutions simply cannot do (they replace http.ClientRequest
entirely). The class extension allows to fully utilize Node.js internals instead of polyfilling them, which results in more resilient mocks.
What this library does
This library extends (or patches, where applicable) the following native modules:
http.get
/http.request
https.get
/https.request
XMLHttpRequest
fetch
Once extended, it intercepts and normalizes all requests to the isomorphic request instances. The isomorphic request is an abstract representation of the request coming from different sources (ClientRequest
, XMLHttpRequest
, window.Request
, etc.) that allows us to handle such requests in the same, unified manner.
You can respond to an isomorphic request using an isomorphic response. In a similar way, the isomorphic response is a representation of the response to use for different requests. Responding to requests differs substantially when using modules like http
or XMLHttpRequest
. This library takes the responsibility for coercing isomorphic responses into appropriate responses depending on the request module automatically.
What this library doesn't do
- Does not provide any request matching logic;
- Does not decide how to handle requests.
Getting started
npm install @mswjs/interceptors
Interceptors
To use this library you need to choose one or multiple interceptors to apply. There are different interceptors exported by this library to spy on respective request-issuing modules:
ClientRequestInterceptor
to spy on http.ClientRequest
(http.get
/http.request
);XMLHttpRequestInterceptor
to spy on XMLHttpRequest
;FetchInterceptor
to spy on fetch
.
Use an interceptor by constructing it and attaching request/response listeners:
import { ClientRequestInterceptor } from '@mswjs/interceptors/lib/interceptors/ClientRequest'
const interceptor = new ClientRequestInterceptor()
interceptor.apply()
interceptor.on('request', (request) => {
console.log(request.method, request.url.href)
})
interceptor.on('response', (response, request) => {
console.log(
'response to %s %s was:',
request.method,
request.url.href,
response
)
})
All HTTP request interceptors implement the same events:
request
, emitted whenever a request has been dispatched;response
, emitted whenever any request receives a response.
Using multiple interceptors
You can combine multiple interceptors to capture requests from different request-issuing modules at once.
import { BatchInterceptor } from '@mswjs/interceptors'
import { ClientRequestInterceptor } from '@mswjs/interceptors/lib/interceptors/ClientRequest'
import { XMLHttpRequestInterceptor } from '@mswjs/interceptors/lib/interceptors/XMLHttpRequest'
const interceptor = new BatchInterceptor({
name: 'my-interceptor',
interceptors: [
new ClientRequestInterceptor(),
new XMLHttpRequestInterceptor(),
],
})
interceptor.apply()
interceptor.on('request', listener)
Note that you can use pre-defined presets that cover all the request sources for a given environment type.
Presets
When using BatchInterceptor
, you can provide a pre-defined preset to its "interceptors" option to capture all request for that environment.
Node.js preset
This preset combines ClientRequestInterceptor
, XMLHttpRequestInterceptor
and is meant to be used in Node.js.
import { BatchInterceptor } from '@mswjs/interceptors'
import nodeInterceptors from '@mswjs/interceptors/lib/presets/node'
const interceptor = new BatchInterceptor({
name: 'my-interceptor',
interceptors: nodeInterceptors,
})
interceptor.apply()
interceptor.on('request', listener)
Browser preset
This preset combines XMLHttpRequestInterceptor
and FetchInterceptor
and is meant to be used in a browser.
import { BatchInterceptor } from '@mswjs/interceptors'
import browserInterceptors from '@mswjs/interceptors/lib/presets/browser'
const interceptor = new BatchInterceptor({
name: 'my-interceptor',
interceptors: browserInterceptors,
})
interceptor.on('request', listener)
Introspecting requests
All HTTP request interceptors emit a "request" event. In the listener to this event, they expose an isomorphic request
instance—a normalized representation of the captured request.
There are many ways to describe a request in Node.js, that's why this library exposes you a custom request instance that abstracts those details away from you, making request listeners uniform.
interceptor.on('reqest', (request) => {})
The exposed request
partially implements Fetch API Request specification, containing the following properties and methods:
interface IsomorphicRequest {
id: string
url: URL
method: string
headers: Headers
credentials: 'omit' | 'same-origin' | 'include'
bodyUsed: boolean
clone(): IsomorphicRequest
arrayBuffer(): Promise<ArrayBuffer>
text(): Promise<string>
json(): Promise<Record<string, unknown>>
}
For example, this is how you would read a JSON request body:
interceptor.on('request', async (request) => {
const json = await request.json()
})
Mocking responses
Although this library can be used purely for request introspection purposes, you can also affect request resolution by responding to any intercepted request within the "request" event.
Use the request.respondWith()
method to respond to a request with a mocked response:
interceptor.on('request', (request) => {
request.respondWith({
status: 200,
statusText: 'OK',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
firstName: 'John',
lastName: 'Maverick',
}),
})
})
Note that a single request can only be handled once. You may want to introduce conditional logic, like routing, in your request listener but it's generally advised to use a higher-level library like Mock Service Worker that does request matching for you.
Requests must be responded to within the same tick as the request listener. This means you cannot respond to a request using setTimeout
, as this will delegate the callback to the next tick. If you wish to introduce asynchronous side-effects in the listener, consider making it an async
function, awaiting any side-effects you need.
interceptor.on('request', async (request) => {
await sleep(500)
request.respondWith({ status: 500 })
})
API
Interceptor
A generic class implemented by all interceptors. You do not interact with this class directly.
class Interceptor {
apply(): void
on(event, listener): void
dispose(): void
}
For public consumption, use interceptors instead.
BatchInterceptor
Applies multiple request interceptors at the same time.
import { BatchInterceptor } from '@mswjs/interceptors'
import nodeInterceptors from '@mswjs/interceptors/lib/presets/node'
const interceptor = new BatchInterceptor({
name: 'my-interceptor',
interceptors: nodeInterceptors,
})
interceptor.apply()
interceptor.on('request', (request) => {
})
Using the /presets/node
interceptors preset is the recommended way to ensure all requests get intercepted, regardless of their origin.
RemoteHttpInterceptor
Enables request interception in the current process while delegating the response resolution logic to the parent process. Requires the current process to be a child process. Requires the parent process to establish a resolver by calling the createRemoteResolver
function.
import { RemoteHttpInterceptor } from '@mswjs/interceptors/lib/RemoteHttpInterceptor'
import { ClientRequestInterceptor } from '@mswjs/interceptors/lib/interceptors/ClientRequest'
const interceptor = new RemoteHttpInterceptor({
interceptors: [new ClientRequestInterceptor()],
})
interceptor.apply()
process.on('disconnect', () => {
interceptor.dispose()
})
You can still listen to and handle any requests in the child process via the request
event listener. Keep in mind that a single request can only be responded to once.
RemoteHttpResolver
Resolves an intercepted request in the given child process
. Requires for that child process to enable request interception by calling the createRemoteInterceptor
function.
import { spawn } from 'child_process'
import { RemoteHttpResolver } from '@mswjs/interceptors/lib/RemoteHttpInterceptor'
const appProcess = spawn('node', ['app.js'], {
stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
})
const resolver = new RemoteHttpResolver({
process: appProcess,
})
resolver.on('request', (request) => {
})
Special mention
The following libraries were used as an inspiration to write this low-level API: