@mswjs/interceptors 0.12.6 → 0.13.2

package/src/interceptors/XMLHttpRequest/utils/bufferFrom.test.ts

@@ -0,0 +1,11 @@
+/**
+ * @jest-environment node
+ */
+import { bufferFrom } from './bufferFrom'
+
+test('returns the same Uint8Array instance as Buffer.from', () => {
+  const init = 'hello world'
+  const buffer = bufferFrom(init)
+  const rawBuffer = Buffer.from(init)
+  expect(Buffer.compare(buffer, rawBuffer)).toBe(0)
+})

package/src/interceptors/XMLHttpRequest/utils/bufferFrom.ts

@@ -0,0 +1,16 @@
+/**
+ * Convert a given string into a `Uint8Array`.
+ * We don't use `TextEncoder` because it's unavailable in some environments.
+ */
+export function bufferFrom(init: string): Uint8Array {
+  const encodedString = encodeURIComponent(init)
+  const binaryString = encodedString.replace(/%([0-9A-F]{2})/g, (_, char) => {
+    return String.fromCharCode(('0x' + char) as any)
+  })
+  const buffer = new Uint8Array(binaryString.length)
+  Array.prototype.forEach.call(binaryString, (char, index) => {
+    buffer[index] = char.charCodeAt(0)
+  })
+
+  return buffer
+}

package/src/interceptors/XMLHttpRequest/utils/createEvent.test.ts

@@ -0,0 +1,27 @@
+/**
+ * @jest-environment jsdom
+ */
+import { createEvent } from './createEvent'
+import { EventPolyfill } from '../polyfills/EventPolyfill'
+
+const request = new XMLHttpRequest()
+request.open('POST', '/user')
+
+test('returns an EventPolyfill instance with the given target set', () => {
+  const event = createEvent(request, 'my-event')
+  const target = event.target as XMLHttpRequest
+
+  expect(event).toBeInstanceOf(EventPolyfill)
+  expect(target).toBeInstanceOf(XMLHttpRequest)
+})
+
+test('returns the ProgressEvent instance', () => {
+  const event = createEvent(request, 'load', {
+    loaded: 100,
+    total: 500,
+  })
+
+  expect(event).toBeInstanceOf(ProgressEvent)
+  expect(event.loaded).toBe(100)
+  expect(event.total).toBe(500)
+})

package/src/interceptors/XMLHttpRequest/utils/createEvent.ts

@@ -0,0 +1,41 @@
+import { EventPolyfill } from '../polyfills/EventPolyfill'
+import { ProgressEventPolyfill } from '../polyfills/ProgressEventPolyfill'
+
+const SUPPORTS_PROGRESS_EVENT = typeof ProgressEvent !== 'undefined'
+
+export function createEvent(
+  target: XMLHttpRequest,
+  type: string,
+  init?: ProgressEventInit
+): EventPolyfill {
+  const progressEvents = [
+    'error',
+    'progress',
+    'loadstart',
+    'loadend',
+    'load',
+    'timeout',
+    'abort',
+  ]
+
+  /**
+   * `ProgressEvent` is not supported in React Native.
+   * @see https://github.com/mswjs/interceptors/issues/40
+   */
+  const ProgressEventClass = SUPPORTS_PROGRESS_EVENT
+    ? ProgressEvent
+    : ProgressEventPolyfill
+
+  const event = progressEvents.includes(type)
+    ? new ProgressEventClass(type, {
+        lengthComputable: true,
+        loaded: init?.loaded || 0,
+        total: init?.total || 0,
+      })
+    : new EventPolyfill(type, {
+        target,
+        currentTarget: target,
+      })
+
+  return event
+}

package/src/interceptors/fetch/index.ts

@@ -0,0 +1,89 @@
+import {
+  Headers,
+  headersToObject,
+  objectToHeaders,
+  flattenHeadersObject,
+} from 'headers-utils'
+import {
+  Interceptor,
+  IsomorphicRequest,
+  IsomorphicResponse,
+} from '../../createInterceptor'
+import { toIsoResponse } from '../../utils/toIsoResponse'
+import { uuidv4 } from '../../utils/uuid'
+
+const debug = require('debug')('fetch')
+
+export const interceptFetch: Interceptor = (observer, resolver) => {
+  const pureFetch = window.fetch
+
+  debug('replacing "window.fetch"...')
+
+  window.fetch = async (input, init) => {
+    const ref = new Request(input, init)
+    const url = typeof input === 'string' ? input : input.url
+    const method = init?.method || 'GET'
+
+    debug('[%s] %s', method, url)
+
+    const isoRequest: IsomorphicRequest = {
+      id: uuidv4(),
+      url: new URL(url, location.origin),
+      method: method,
+      headers: new Headers(init?.headers || {}),
+      credentials: init?.credentials || 'same-origin',
+      body: await ref.text(),
+    }
+    debug('isomorphic request', isoRequest)
+    observer.emit('request', isoRequest)
+
+    debug('awaiting for the mocked response...')
+    const response = await resolver(isoRequest, ref)
+    debug('mocked response', response)
+
+    if (response) {
+      const isomorphicResponse = toIsoResponse(response)
+      debug('derived isomorphic response', isomorphicResponse)
+
+      observer.emit('response', isoRequest, isomorphicResponse)
+
+      return new Response(response.body, {
+        ...isomorphicResponse,
+        // `Response.headers` cannot be instantiated with the `Headers` polyfill.
+        // Apparently, it halts if the `Headers` class contains unknown properties
+        // (i.e. the internal `Headers.map`).
+        headers: flattenHeadersObject(response.headers || {}),
+      })
+    }
+
+    debug('no mocked response found, bypassing...')
+
+    return pureFetch(input, init).then(async (response) => {
+      const cloneResponse = response.clone()
+      debug('original fetch performed', cloneResponse)
+
+      observer.emit(
+        'response',
+        isoRequest,
+        await normalizeFetchResponse(cloneResponse)
+      )
+      return response
+    })
+  }
+
+  return () => {
+    debug('restoring modules...')
+    window.fetch = pureFetch
+  }
+}
+
+async function normalizeFetchResponse(
+  response: Response
+): Promise<IsomorphicResponse> {
+  return {
+    status: response.status,
+    statusText: response.statusText,
+    headers: objectToHeaders(headersToObject(response.headers)),
+    body: await response.text(),
+  }
+}

package/src/presets/browser.ts

@@ -0,0 +1,8 @@
+import { interceptXMLHttpRequest } from '../interceptors/XMLHttpRequest'
+import { interceptFetch } from '../interceptors/fetch'
+
+/**
+ * The default preset provisions the interception of requests
+ * regardless of their type (fetch/XMLHttpRequest).
+ */
+export default [interceptXMLHttpRequest, interceptFetch]

package/src/presets/node.ts

@@ -0,0 +1,8 @@
+import { interceptClientRequest } from '../interceptors/ClientRequest'
+import { interceptXMLHttpRequest } from '../interceptors/XMLHttpRequest'
+
+/**
+ * The default preset provisions the interception of requests
+ * regardless of their type (http/https/XMLHttpRequest).
+ */
+export default [interceptClientRequest, interceptXMLHttpRequest]

package/src/remote.ts

@@ -0,0 +1,176 @@
+import { ChildProcess, Serializable } from 'child_process'
+import { Headers } from 'headers-utils'
+import { invariant } from 'outvariant'
+import { StrictEventEmitter } from 'strict-event-emitter'
+import {
+  createInterceptor,
+  InterceptorApi,
+  InterceptorEventsMap,
+  InterceptorOptions,
+  IsomorphicRequest,
+  Resolver,
+} from './createInterceptor'
+import { toIsoResponse } from './utils/toIsoResponse'
+
+type ProcessEventListener = (message: Serializable, ...args: any[]) => void
+
+export type CreateRemoteInterceptorOptions = Omit<
+  InterceptorOptions,
+  'resolver'
+>
+
+export type RemoteResolverApi = Pick<InterceptorApi, 'on'>
+
+export interface CreateRemoteResolverOptions {
+  process: ChildProcess
+  resolver: Resolver
+}
+
+function requestReviver(key: string, value: any) {
+  switch (key) {
+    case 'url':
+      return new URL(value)
+
+    case 'headers':
+      return new Headers(value)
+
+    default:
+      return value
+  }
+}
+
+/**
+ * Creates a remote request interceptor that delegates
+ * the mocked response resolution to the parent process.
+ * The parent process must establish a remote resolver
+ * by calling `createRemoteResolver` function.
+ */
+export function createRemoteInterceptor(
+  options: CreateRemoteInterceptorOptions
+): InterceptorApi {
+  invariant(
+    process.connected,
+    `Failed to create a remote interceptor: the current process (%s) does not have a parent. Please make sure you're spawning this process as a child process in order to use remote request interception.`,
+    process.pid
+  )
+
+  if (typeof process.send === 'undefined') {
+    throw new Error(
+      `\
+Failed to create a remote interceptor: the current process (${process.pid}) does not have the IPC enabled. Please make sure you're spawning this process with the "ipc" stdio value set:
+
+spawn('node', ['module.js'], { stdio: ['ipc'] })\
+`
+    )
+  }
+
+  let handleParentMessage: ProcessEventListener
+
+  const interceptor = createInterceptor({
+    ...options,
+    resolver(request) {
+      const serializedRequest = JSON.stringify(request)
+      process.send?.(`request:${serializedRequest}`)
+
+      return new Promise((resolve) => {
+        handleParentMessage = (message: Serializable) => {
+          if (typeof message !== 'string') {
+            return
+          }
+
+          if (message.startsWith(`response:${request.id}`)) {
+            const [, responseString] =
+              message.match(/^response:.+?:(.+)$/) || []
+
+            if (!responseString) {
+              return resolve()
+            }
+
+            const mockedResponse = JSON.parse(responseString)
+
+            return resolve(mockedResponse)
+          }
+        }
+
+        process.addListener('message', handleParentMessage)
+      })
+    },
+  })
+
+  return {
+    ...interceptor,
+    restore() {
+      interceptor.restore()
+      process.removeListener('message', handleParentMessage)
+    },
+  }
+}
+
+/**
+ * Creates a response resolver function attached to the given `ChildProcess`.
+ * The child process must establish a remote interceptor by calling `createRemoteInterceptor` function.
+ */
+export function createRemoteResolver(
+  options: CreateRemoteResolverOptions
+): RemoteResolverApi {
+  const observer = new StrictEventEmitter<InterceptorEventsMap>()
+
+  const handleChildMessage: ProcessEventListener = async (message) => {
+    if (typeof message !== 'string') {
+      return
+    }
+
+    if (message.startsWith('request:')) {
+      const [, requestString] = message.match(/^request:(.+)$/) || []
+
+      if (!requestString) {
+        return
+      }
+
+      const isoRequest: IsomorphicRequest = JSON.parse(
+        requestString,
+        requestReviver
+      )
+
+      observer.emit('request', isoRequest)
+
+      // Retrieve the mocked response.
+      const mockedResponse = await options.resolver(
+        isoRequest,
+        undefined as any
+      )
+
+      // Send the mocked response to the child process.
+      const serializedResponse = JSON.stringify(mockedResponse)
+      options.process.send(
+        `response:${isoRequest.id}:${serializedResponse}`,
+        (error) => {
+          if (error) {
+            return
+          }
+
+          if (mockedResponse) {
+            // Emit an optimisting "response" event at this point,
+            // not to rely on the back-and-forth signaling for the sake of the event.
+            observer.emit('response', isoRequest, toIsoResponse(mockedResponse))
+          }
+        }
+      )
+    }
+  }
+
+  const cleanup = () => {
+    options.process.removeListener('message', handleChildMessage)
+  }
+
+  options.process.addListener('message', handleChildMessage)
+  options.process.addListener('disconnect', cleanup)
+  options.process.addListener('error', cleanup)
+  options.process.addListener('exit', cleanup)
+
+  return {
+    on(event, listener) {
+      observer.addListener(event, listener)
+    },
+  }
+}

package/src/utils/cloneObject.test.ts

@@ -0,0 +1,93 @@
+import { cloneObject } from './cloneObject'
+
+test('clones a shallow object', () => {
+  const original = { a: 1, b: 2, c: [1, 2, 3] }
+  const clone = cloneObject(original)
+
+  expect(clone).toEqual(original)
+
+  clone.a = 5
+  clone.b = 6
+  clone.c = [5, 6, 7]
+
+  expect(clone).toHaveProperty('a', 5)
+  expect(clone).toHaveProperty('b', 6)
+  expect(clone).toHaveProperty('c', [5, 6, 7])
+  expect(original).toHaveProperty('a', 1)
+  expect(original).toHaveProperty('b', 2)
+  expect(original).toHaveProperty('c', [1, 2, 3])
+})
+
+test('clones a nested object', () => {
+  const original = { a: { b: 1 }, c: { d: { e: 2 } } }
+  const clone = cloneObject(original)
+
+  expect(clone).toEqual(original)
+
+  clone.a.b = 10
+  clone.c.d.e = 20
+
+  expect(clone).toHaveProperty(['a', 'b'], 10)
+  expect(clone).toHaveProperty(['c', 'd', 'e'], 20)
+  expect(original).toHaveProperty(['a', 'b'], 1)
+  expect(original).toHaveProperty(['c', 'd', 'e'], 2)
+})
+
+test('clones a class instance', () => {
+  class Car {
+    public manufacturer: string
+    constructor() {
+      this.manufacturer = 'Audi'
+    }
+    getManufacturer() {
+      return this.manufacturer
+    }
+  }
+
+  const car = new Car()
+  const clone = cloneObject(car)
+
+  expect(clone).toHaveProperty('manufacturer', 'Audi')
+  expect(clone).toHaveProperty('getManufacturer')
+  expect(clone.getManufacturer).toBeInstanceOf(Function)
+  expect(clone.getManufacturer()).toEqual('Audi')
+})
+
+test('ignores nested class instances', () => {
+  class Car {
+    name: string
+    constructor(name: string) {
+      this.name = name
+    }
+    getName() {
+      return this.name
+    }
+  }
+  const original = {
+    a: 1,
+    car: new Car('Audi'),
+  }
+  const clone = cloneObject(original)
+
+  expect(clone).toEqual(original)
+  expect(clone.car).toBeInstanceOf(Car)
+  expect(clone.car.getName()).toEqual('Audi')
+
+  clone.car = new Car('BMW')
+
+  expect(clone.car).toBeInstanceOf(Car)
+  expect(clone.car.getName()).toEqual('BMW')
+  expect(original.car).toBeInstanceOf(Car)
+  expect(original.car.getName()).toEqual('Audi')
+})
+
+test('clones an object with null prototype', () => {
+  const original = {
+    key: Object.create(null),
+  }
+  const clone = cloneObject(original)
+
+  expect(clone).toEqual({
+    key: {},
+  })
+})

package/src/utils/cloneObject.ts

@@ -0,0 +1,34 @@
+const debug = require('debug')('cloneObject')
+
+function isPlainObject(obj?: Record<string, any>): boolean {
+  debug('is plain object?', obj)
+
+  if (obj == null || !obj.constructor?.name) {
+    debug('given object is undefined, not a plain object...')
+    return false
+  }
+
+  debug('checking the object constructor:', obj.constructor.name)
+  return obj.constructor.name === 'Object'
+}
+
+export function cloneObject<ObjectType extends Record<string, any>>(
+  obj: ObjectType
+): ObjectType {
+  debug('cloning object:', obj)
+
+  const enumerableProperties = Object.entries(obj).reduce<Record<string, any>>(
+    (acc, [key, value]) => {
+      debug('analyzing key-value pair:', key, value)
+
+      // Recursively clone only plain objects, omitting class instances.
+      acc[key] = isPlainObject(value) ? cloneObject(value) : value
+      return acc
+    },
+    {}
+  )
+
+  return isPlainObject(obj)
+    ? enumerableProperties
+    : Object.assign(Object.getPrototypeOf(obj), enumerableProperties)
+}

package/src/utils/getCleanUrl.test.ts

@@ -0,0 +1,31 @@
+import { getCleanUrl } from './getCleanUrl'
+
+describe('getCleanUrl', () => {
+  describe('given a URL without query parameters', () => {
+    test('should return url href as-is', () => {
+      const url = new URL('https://github.com')
+      expect(getCleanUrl(url)).toEqual('https://github.com/')
+    })
+  })
+
+  describe('given a URL with query parameters', () => {
+    test('should return url without parameters', () => {
+      const url = new URL('https://github.com/mswjs/?userId=abc-123')
+      expect(getCleanUrl(url)).toEqual('https://github.com/mswjs/')
+    })
+  })
+
+  describe('given a URL with a hash', () => {
+    test('should return a url without hash', () => {
+      const url = new URL('https://github.com/mswjs/#hello-world')
+      expect(getCleanUrl(url)).toEqual('https://github.com/mswjs/')
+    })
+  })
+
+  describe('given an absolute URL ', () => {
+    test('should return a clean relative URL', () => {
+      const url = new URL('/login?query=value', 'https://github.com')
+      expect(getCleanUrl(url, false)).toEqual('/login')
+    })
+  })
+})

package/src/utils/getCleanUrl.ts

@@ -0,0 +1,6 @@
+/**
+ * Removes query parameters and hashes from a given URL.
+ */
+export function getCleanUrl(url: URL, isAbsolute: boolean = true): string {
+  return [isAbsolute && url.origin, url.pathname].filter(Boolean).join('')
+}

package/src/utils/getRequestOptionsByUrl.ts

@@ -0,0 +1,29 @@
+import { RequestOptions } from 'http'
+
+/**
+ * Converts a URL instance into the RequestOptions object expected by
+ * the `ClientRequest` class.
+ * @see https://github.com/nodejs/node/blob/908292cf1f551c614a733d858528ffb13fb3a524/lib/internal/url.js#L1257
+ */
+export function getRequestOptionsByUrl(url: URL): RequestOptions {
+  const options: RequestOptions = {
+    method: 'GET',
+    protocol: url.protocol,
+    hostname:
+      typeof url.hostname === 'string' && url.hostname.startsWith('[')
+        ? url.hostname.slice(1, -1)
+        : url.hostname,
+    host: url.host,
+    path: `${url.pathname}${url.search || ''}`,
+  }
+
+  if (!!url.port) {
+    options.port = Number(url.port)
+  }
+
+  if (url.username || url.password) {
+    options.auth = `${url.username}:${url.password}`
+  }
+
+  return options
+}