GitHub – Mswjs/interceptors: Low-Level Network Interception Library
- anonymous
- communication
- July 22, 2026
Low-level community interception library. WebSocket (the WebSocket class in Undici and in the browser). While there are a lot of community mocking libraries, they tend to make use of request interception as an implementation element, providing you with a high-level API that features request matching, timeouts, recording, and so forth. This library is a barebones implementation that provides as little abstraction as potential to execute arbitrary logic upon any request. It’s primarily designed as an underlying element for prime-degree API mocking solutions akin to Mock Service Worker. How is this library totally different? The core philosophy of Interceptors is to run as much of the underlying network code as possible. Strange for a network mocking library, isn’t it? Turns out, respecting the system’s integrity and executing extra of the community code leads to extra resilient exams and likewise helps to uncover bugs in the code that would in any other case go unnoticed. Interceptors heavily depend on class extension as an alternative of perform and module overrides.
By extending the native community code, it will probably surgically insert the interception and mocking items only where crucial, leaving the remainder of the system intact. The request interception algorithms differ dramatically based on the request API. Interceptors accommodate for them all, bringing the intercepted requests to a common ground-the Fetch API Request occasion. The identical applies for Villains responses, where a Fetch API Response instance is translated to the suitable response format. This library goals to supply full specification compliance with the APIs and protocols it extends. Once prolonged, it intercepts and normalizes all requests to the Fetch API Request cases. This way, no matter the request source (http.ClientRequest, XMLHttpRequest, window.Request, and so on), you always get a specification-compliant request occasion to work with. You’ll be able to respond to the intercepted HTTP request by constructing a Fetch API Response instance. Instead of designing customized abstractions, this library respects the Fetch API specification and takes the responsibility to coerce a single response declaration to the appropriate response formats primarily based on the request-issuing modules (like http.OutgoingMessage to respond to http.ClientRequest, or updating XMLHttpRequest response-related properties).
Does not handle requests by default. This limitation is intrinsic to the interception algorithm used by the library. In order for it to emit the join event on the socket, the library should know if you’ve got handled the request in any method (e.g. responded with a mocked response or errored it). For that, it emits the request occasion on the interceptor the place you may handle the request. Since you can eat the request stream within the request event, it waits until the request physique stream is full (i.e. until req.finish() is named). This creates a catch 22 that causes this limitation. To make use of this library you need to choose one or multiple interceptors to apply. FetchInterceptor to spy on fetch. You’ll be able to combine multiple interceptors to seize requests from different request-issuing modules directly. Note that you can use pre-defined presets that cowl all the request sources for a given atmosphere sort. When utilizing BatchInterceptor, you may provide a pre-outlined preset to its “interceptors” choice to capture all request for that atmosphere.
This preset combines ClientRequestInterceptor, XMLHttpRequestInterceptor and is supposed to be used in Node.js. This preset combines XMLHttpRequestInterceptor and FetchInterceptor and is supposed to be used in a browser. All HTTP request interceptors emit a “request” event. In the listener to this occasion, they expose a request reference, which is a Fetch API Request occasion. There are some ways to explain a request in Node.js however this library coerces totally different request definitions to a single specification-compliant Request instance to make the handling constant. Since the uncovered request instance implements the Fetch API specification, you’ll be able to function with it just as you do with the common browser request. Don’t forget to clone the request before reading its physique! Request representations are readonly. This restriction is done so that the library wouldn’t must unnecessarily synchronize the precise request instance and its Fetch API request illustration. As of now, this library will not be meant to be used as a full-scale proxy.
Although this library can be used purely for request introspection functions, you too can affect request resolution by responding to any intercepted request inside the “request” event. We use Fetch API Response class because the center-floor for mocked response definition. This library then coerces the response instance to the suitable response format (e.g. to http.OutgoingMessage in the case of http.ClientRequest). Note that a single request can solely be dealt with once. You may wish to introduce conditional logic, like routing, in your request listener however it’s typically suggested to make use of a better-stage library like Mock Service Worker that does request matching for you. Requests must be responded to within the identical tick as the request listener. This implies you can’t reply to a request using setTimeout, as this will delegate the callback to the following tick. In case you wish to introduce asynchronous side-results in the listener, consider making it an async function, awaiting any side-effects you want.