node-request-interceptor
    TypeScript icon, indicating that this package has built-in type declarations

    0.6.3 • Public • Published

    Latest version Build status

    node-request-interceptor

    Low-level HTTP/HTTPS/XHR request interception library for NodeJS.

    Intercepts any requests issued by:

    • http.get/http.request
    • https.get/https.request
    • fetch
    • XMLHttpRequest
    • Any third-party libraries that utilize the modules above (i.e. request, node-fetch, etc.)

    Motivation

    While there are a lot of network communication mocking libraries, they tend to use request interception as an implementation detail, exposing 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 in NodeJS. It's primarily designed as an underlying component for a high-level API mocking solutions.

    How is this library different?

    As interception is often combined with request route matching, some libraries can determine whether a request should be mocked before it actually happens. This approach is not suitable for this library, as it rather intercepts all requests and then let's you decide which ones should be mocked. This affects the level at which interception happens, and also the way mocked/original response is constructed, in comparison to other solutions.

    Why XMLHttpRequest?

    Although NodeJS has no XMLHttpRequest implementation, this library covers it for the sake of processes that still run in NodeJS, but emulate a browser-like environment (i.e. jsdom when running tests in Jest).

    What this library does

    This library monkey-patches the following native modules:

    • http.get/http.request
    • https.get/https.request
    • XMLHttpRequest

    Once patched, it provides an interface to execute an arbitrary logic upon any outgoing request using a request middleware function.

    • Bypasses all requests by default, so your network channel is not affected.
    • Handles an abstract response object returned from the request middleware as an actual response for the occurred request (taking into account the difference in constructing a response for different clients).

    What this library doesn't do

    • Does not provide any request matching logic.
    • Does not decide how to handle requests.
    • Does not run in a browser (although supports jsdom).

    Getting started

    npm install node-request-interceptor

    API

    RequestInterceptor(interceptors: Interceptor[])

    import { RequestInterceptor } from 'node-request-interceptor'
    import withDefaultInterceptors from 'node-request-interceptor/presets/default'
    
    const interceptor = new RequestInterceptor(withDefaultInterceptors)

    Using the /presets/default interceptors preset is the recommended way to ensure all requests get intercepted, regardless of their origin.

    Interceptors

    This library utilizes a concept of an interceptor–a module that performs necessary patching, handles a mocked response, and restores patched instances.

    The list of interceptors:

    • /interceptors/ClientRequest
    • /interceptors/XMLHttpRequest

    To use one, or multiple interceptors, import and provide them to the RequestInterceptor constructor.

    import { RequestInterceptors } from 'node-request-interceptor'
    import { interceptXMLHttpRequest } from 'node-request-interceptor/interceptors/XMLHttpRequest'
    
    // This `interceptor` instance would handle only XMLHttpRequest,
    // ignoring requests issued via `http`/`https` modules.
    const interceptor = new RequestInterceptors([interceptXMLHttpRequest])

    Interceptors are crucial in leveraging environment-specific module overrides. Certain environments (i.e. React Native) do not have access to native NodeJS modules (like http). Importing such modules raises an exception, and must be avoided.

    Methods

    .use(middleware: (req: InterceptedRequest, ref: IncomingMessage | XMLHttpRequest) => MockedResponse): void

    Applies a given middleware function to an intercepted request. May return a MockedResponse object that is going to be used to respond to an intercepted request.

    Requests monitoring
    interceptor.use((req) => {
      // Will print to stdout any outgoing requests
      // without affecting their responses
      console.log('%s %s', req.method, req.url.href)
    })
    Response mocking

    When a request middleware returns a MockedResponse object, it will be returned as the response to the intercepted request. This library automatically creates a proper response instance according to the request issuing module (http/XMLHttpRequest).

    interceptor.use((req) => {
      if (['https://google.com'].includes(req.url.origin)) {
        // Will return a mocked response for any request
        // that is issued from the "https://google.com" origin.
        return {
          status: 301,
          headers: {
            'x-powered-by': 'node-request-interceptor',
          },
          body: JSON.stringify({
            message: 'Hey, I am a mocked response',
          }),
        }
      }
    })

    .restore(): void

    Restores all patched modules and stops the interception of any future requests.

    interceptor.restore()

    InterceptedRequest

    interface InterceptedRequest {
      url: URL
      method: string
      headers?: http.OutgoingHttpHeaders
      body?: string
    }

    MockedResponse

    Whenever a MockedResponse object is returned from the request middleware function, it's being used to constructs a relevant response for the intercepted request.

    interface MockedResponse {
      status?: number
      statusText?: string
      headers?: Record<string, string | string[]>
      body?: string
    }

    Special mention

    The following libraries were used as an inspiration to write this low-level API:

    Install

    npm i node-request-interceptor

    DownloadsWeekly Downloads

    212,304

    Version

    0.6.3

    License

    MIT

    Unpacked Size

    137 kB

    Total Files

    82

    Last publish

    Collaborators

    • kettanaito