msw 2.12.13 → 2.13.0

package/src/core/experimental/handlers-controller.ts

@@ -0,0 +1,145 @@
+import { invariant } from 'outvariant'
+import { type RequestHandler } from '../handlers/RequestHandler'
+import { type WebSocketHandler } from '../handlers/WebSocketHandler'
+import { devUtils } from '../utils/internal/devUtils'
+
+export type AnyHandler = RequestHandler | WebSocketHandler
+export type HandlersMap = Partial<Record<AnyHandler['kind'], Array<AnyHandler>>>
+
+export function groupHandlersByKind(handlers: Array<AnyHandler>): HandlersMap {
+  const groups: HandlersMap = {}
+
+  /**
+   * @note `Object.groupBy` is not implemented in Node.js v20.
+   */
+  for (const handler of handlers) {
+    ;(groups[handler.kind] ||= []).push(handler)
+  }
+
+  return groups
+}
+
+export interface HandlersControllerState {
+  initialHandlers: HandlersMap
+  handlers: HandlersMap
+}
+
+export abstract class HandlersController {
+  protected getInitialState(
+    initialHandlers: Array<AnyHandler>,
+  ): HandlersControllerState {
+    invariant(
+      this.#validateHandlers(initialHandlers),
+      devUtils.formatMessage(
+        '[MSW] Failed to apply given request handlers: invalid input. Did you forget to spread the request handlers Array?',
+      ),
+    )
+
+    const normalizedInitialHandlers = groupHandlersByKind(initialHandlers)
+
+    return {
+      initialHandlers: normalizedInitialHandlers,
+      handlers: { ...normalizedInitialHandlers },
+    }
+  }
+
+  protected abstract getState(): HandlersControllerState
+  protected abstract setState(nextState: Partial<HandlersControllerState>): void
+
+  public currentHandlers(): Array<AnyHandler> {
+    return Object.values(this.getState().handlers)
+      .flat()
+      .filter((handler) => handler != null)
+  }
+
+  public getHandlersByKind(kind: AnyHandler['kind']): Array<AnyHandler> {
+    return this.getState().handlers[kind] || []
+  }
+
+  public use(nextHandlers: Array<AnyHandler>): void {
+    invariant(
+      this.#validateHandlers(nextHandlers),
+      devUtils.formatMessage(
+        '[MSW] Failed to call "use()" with the given request handlers: invalid input. Did you forget to spread the array of request handlers?',
+      ),
+    )
+
+    if (nextHandlers.length === 0) {
+      return
+    }
+
+    const { handlers } = this.getState()
+
+    // Iterate over next handlers and prepend them to their respective lists.
+    // Iterate in a reverse order to the keep the order of the runtime handlers as provided.
+    for (let i = nextHandlers.length - 1; i >= 0; i--) {
+      const handler = nextHandlers[i]
+      handlers[handler.kind] = handlers[handler.kind]
+        ? [handler, ...handlers[handler.kind]!]
+        : [handler]
+    }
+
+    this.setState({ handlers })
+  }
+
+  public reset(nextHandlers: Array<AnyHandler>): void {
+    invariant(
+      nextHandlers.length > 0 ? this.#validateHandlers(nextHandlers) : true,
+      devUtils.formatMessage(
+        'Failed to replace initial handlers during reset: invalid handlers. Did you forget to spread the handlers array?',
+      ),
+    )
+
+    const { initialHandlers } = this.getState()
+
+    if (nextHandlers.length === 0) {
+      this.setState({
+        handlers: { ...initialHandlers },
+      })
+
+      return
+    }
+
+    const normalizedNextHandlers = groupHandlersByKind(nextHandlers)
+
+    this.setState({
+      initialHandlers: normalizedNextHandlers,
+      handlers: { ...normalizedNextHandlers },
+    })
+  }
+
+  #validateHandlers(handlers: Array<AnyHandler>): boolean {
+    return handlers.every((handler) => !Array.isArray(handler))
+  }
+}
+
+export class InMemoryHandlersController extends HandlersController {
+  #handlers: HandlersMap
+  #initialHandlers: HandlersMap
+
+  constructor(initialHandlers: Array<AnyHandler>) {
+    super()
+
+    const initialState = this.getInitialState(initialHandlers)
+
+    this.#initialHandlers = initialState.initialHandlers
+    this.#handlers = initialState.handlers
+  }
+
+  protected getState(): HandlersControllerState {
+    return {
+      initialHandlers: this.#initialHandlers,
+      handlers: this.#handlers,
+    }
+  }
+
+  protected setState(nextState: Partial<HandlersControllerState>): void {
+    if (nextState.initialHandlers) {
+      this.#initialHandlers = nextState.initialHandlers
+    }
+
+    if (nextState.handlers) {
+      this.#handlers = nextState.handlers
+    }
+  }
+}

package/src/core/experimental/index.ts

@@ -0,0 +1,16 @@
+export { defineNetwork, DefineNetworkOptions } from './define-network'
+
+/* Network sources */
+export { NetworkSource } from './sources/network-source'
+export { InterceptorSource } from './sources/interceptor-source'
+
+/* Frames */
+export { NetworkFrame } from './frames/network-frame'
+export {
+  HttpNetworkFrame,
+  type HttpNetworkFrameEventMap,
+} from './frames/http-frame'
+export {
+  WebSocketNetworkFrame,
+  type WebSocketNetworkFrameEventMap,
+} from './frames/websocket-frame'

package/src/core/experimental/on-unhandled-frame.test.ts

@@ -0,0 +1,360 @@
+// @vitest-environment node
+import type {
+  WebSocketClientConnection,
+  WebSocketServerConnection,
+} from '@mswjs/interceptors/WebSocket'
+import { HttpNetworkFrame } from './frames/http-frame'
+import { WebSocketNetworkFrame } from './frames/websocket-frame'
+import {
+  executeUnhandledFrameHandle,
+  UnhandledFrameCallback,
+} from './on-unhandled-frame'
+
+beforeAll(() => {
+  vi.spyOn(console, 'warn').mockImplementation(() => void 0)
+  vi.spyOn(console, 'error').mockImplementation(() => void 0)
+})
+
+afterEach(() => {
+  vi.clearAllMocks()
+})
+
+afterAll(() => {
+  vi.restoreAllMocks()
+})
+
+class TestHttpFrame extends HttpNetworkFrame {
+  constructor(request: Request) {
+    super({ request })
+  }
+
+  respondWith = () => {}
+  errorWith = () => {}
+  passthrough = () => {}
+}
+
+class TestWebSocketFrame extends WebSocketNetworkFrame {
+  constructor() {
+    super({
+      connection: {
+        client: {
+          url: new URL('wss://localhost/test'),
+        } as WebSocketClientConnection,
+        server: {} as WebSocketServerConnection,
+        info: { protocols: [] },
+      },
+    })
+  }
+
+  passthrough = () => {}
+  errorWith = () => {}
+}
+
+it('does not print any warnings or errors using the "bypass" strategy', async () => {
+  await expect(
+    executeUnhandledFrameHandle(
+      new TestHttpFrame(new Request('http://localhost/test')),
+      'bypass',
+    ),
+  ).resolves.toBeUndefined()
+  expect(console.warn).not.toHaveBeenCalled()
+  expect(console.error).not.toHaveBeenCalled()
+})
+
+it('prints a warning for the HTTP frame using the "warn" strategy', async () => {
+  await expect(
+    executeUnhandledFrameHandle(
+      new TestHttpFrame(new Request('http://localhost/test')),
+      'warn',
+    ),
+  ).resolves.toBeUndefined()
+
+  expect.soft(console.warn).toHaveBeenCalledOnce()
+  expect(console.warn).toHaveBeenCalledWith(
+    `[MSW] Warning: intercepted a request without a matching request handler:
+
+  • GET http://localhost/test
+
+If you still wish to intercept this unhandled request, please create a request handler for it.
+Read more: https://mswjs.io/docs/http/intercepting-requests`,
+  )
+  expect(console.error).not.toHaveBeenCalled()
+})
+
+it('rejects and prints an error for the HTTP frame using the "error" strategy', async () => {
+  await expect(
+    executeUnhandledFrameHandle(
+      new TestHttpFrame(new Request('http://localhost/test')),
+      'error',
+    ),
+  ).rejects.toThrow(
+    `[MSW] Cannot bypass a request when using the "error" strategy for the "onUnhandledRequest" option.`,
+  )
+
+  expect.soft(console.error).toHaveBeenCalledOnce()
+  expect(console.error).toHaveBeenCalledWith(
+    `[MSW] Error: intercepted a request without a matching request handler:
+
+  • GET http://localhost/test
+
+If you still wish to intercept this unhandled request, please create a request handler for it.
+Read more: https://mswjs.io/docs/http/intercepting-requests`,
+  )
+  expect(console.warn).not.toHaveBeenCalled()
+})
+
+it('invokes the custom callback for the HTTP frame', async () => {
+  const callback = vi.fn()
+  const frame = new TestHttpFrame(new Request('http://localhost/test'))
+
+  await expect(
+    executeUnhandledFrameHandle(frame, callback),
+  ).resolves.toBeUndefined()
+
+  expect(callback).toHaveBeenCalledOnce()
+  expect(callback).toHaveBeenCalledWith({
+    defaults: {
+      warn: expect.any(Function),
+      error: expect.any(Function),
+    },
+    frame,
+  })
+})
+
+it('does not print anything for common asset HTTP requests', async () => {
+  await expect(
+    executeUnhandledFrameHandle(
+      new TestHttpFrame(new Request('http://localhost/image.png')),
+      'warn',
+    ),
+  ).resolves.toBeUndefined()
+
+  expect(console.warn).not.toHaveBeenCalled()
+  expect(console.error).not.toHaveBeenCalled()
+
+  await expect(
+    executeUnhandledFrameHandle(
+      new TestHttpFrame(new Request('http://localhost/image.png')),
+      'error',
+    ),
+  ).resolves.toBeUndefined()
+
+  expect(console.warn).not.toHaveBeenCalled()
+  expect(console.error).not.toHaveBeenCalled()
+})
+
+it('delegates common asset HTTP requests handling to the custom callback', async () => {
+  const callback = vi.fn()
+  const frame = new TestHttpFrame(new Request('http://localhost/image.png'))
+
+  await expect(
+    executeUnhandledFrameHandle(frame, callback),
+  ).resolves.toBeUndefined()
+
+  expect(callback).toHaveBeenCalledOnce()
+  expect(callback).toHaveBeenCalledWith({
+    defaults: {
+      warn: expect.any(Function),
+      error: expect.any(Function),
+    },
+    frame,
+  })
+})
+
+it('supports printing the default warning in the custom callback for the HTTP frame', async () => {
+  const callback = vi.fn<UnhandledFrameCallback>(({ defaults }) => {
+    defaults.warn()
+  })
+  const frame = new TestHttpFrame(new Request('http://localhost/test'))
+
+  await expect(
+    executeUnhandledFrameHandle(frame, callback),
+  ).resolves.toBeUndefined()
+
+  expect(callback).toHaveBeenCalledOnce()
+  expect(callback).toHaveBeenCalledWith({
+    defaults: {
+      warn: expect.any(Function),
+      error: expect.any(Function),
+    },
+    frame,
+  })
+  expect.soft(console.warn).toHaveBeenCalledOnce()
+  expect(console.warn).toHaveBeenCalledWith(
+    `[MSW] Warning: intercepted a request without a matching request handler:
+
+  • GET http://localhost/test
+
+If you still wish to intercept this unhandled request, please create a request handler for it.
+Read more: https://mswjs.io/docs/http/intercepting-requests`,
+  )
+  expect(console.error).not.toHaveBeenCalled()
+})
+
+it('supports printing the default error in the custom callback for the HTTP frame', async () => {
+  const callback = vi.fn<UnhandledFrameCallback>(({ defaults }) => {
+    defaults.error()
+  })
+  const frame = new TestHttpFrame(new Request('http://localhost/test'))
+
+  await expect(
+    executeUnhandledFrameHandle(frame, callback),
+  ).resolves.toBeUndefined()
+
+  expect(callback).toHaveBeenCalledOnce()
+  expect(callback).toHaveBeenCalledWith({
+    defaults: {
+      warn: expect.any(Function),
+      error: expect.any(Function),
+    },
+    frame,
+  })
+  expect.soft(console.error).toHaveBeenCalledOnce()
+  expect(console.error).toHaveBeenCalledWith(
+    `[MSW] Error: intercepted a request without a matching request handler:
+
+  • GET http://localhost/test
+
+If you still wish to intercept this unhandled request, please create a request handler for it.
+Read more: https://mswjs.io/docs/http/intercepting-requests`,
+  )
+  expect(console.warn).not.toHaveBeenCalled()
+})
+
+it('throws if given an unknown strategy for the HTTP frame', async () => {
+  await expect(
+    executeUnhandledFrameHandle(
+      new TestHttpFrame(new Request('http://localhost/test')),
+      // @ts-expect-error Intentionally invalid value.
+      'intentionally-invalid',
+    ),
+  ).rejects.toThrow(
+    `[MSW] Failed to react to an unhandled network frame: unknown strategy "intentionally-invalid". Please provide one of the supported strategies ("bypass", "warn", "error") or a custom callback function as the value of the "onUnhandledRequest" option.`,
+  )
+})
+
+it('prints a warning for the WebSocket frame using the "warn" strategy', async () => {
+  await expect(
+    executeUnhandledFrameHandle(new TestWebSocketFrame(), 'warn'),
+  ).resolves.toBeUndefined()
+
+  expect.soft(console.warn).toHaveBeenCalledOnce()
+  expect(console.warn).toHaveBeenCalledWith(
+    `[MSW] Warning: intercepted a WebSocket connection without a matching event handler:
+
+  • wss://localhost/test
+
+If you still wish to intercept this unhandled connection, please create an event handler for it.
+Read more: https://mswjs.io/docs/websocket`,
+  )
+  expect(console.error).not.toHaveBeenCalled()
+})
+
+it('rejects and prints an error for the WebSocket frame using the "error" strategy', async () => {
+  await expect(
+    executeUnhandledFrameHandle(new TestWebSocketFrame(), 'error'),
+  ).rejects.toThrow(
+    `[MSW] Cannot bypass a request when using the "error" strategy for the "onUnhandledRequest" option.`,
+  )
+
+  expect.soft(console.error).toHaveBeenCalledOnce()
+  expect(console.error).toHaveBeenCalledWith(
+    `[MSW] Error: intercepted a WebSocket connection without a matching event handler:
+
+  • wss://localhost/test
+
+If you still wish to intercept this unhandled connection, please create an event handler for it.
+Read more: https://mswjs.io/docs/websocket`,
+  )
+  expect(console.warn).not.toHaveBeenCalled()
+})
+
+it('invokes the custom callback for the WebSocket frame', async () => {
+  const callback = vi.fn()
+  const frame = new TestWebSocketFrame()
+
+  await expect(
+    executeUnhandledFrameHandle(frame, callback),
+  ).resolves.toBeUndefined()
+
+  expect(callback).toHaveBeenCalledOnce()
+  expect(callback).toHaveBeenCalledWith({
+    defaults: {
+      warn: expect.any(Function),
+      error: expect.any(Function),
+    },
+    frame,
+  })
+})
+
+it('throws if given an unknown strategy for the WebSocket frame', async () => {
+  await expect(
+    executeUnhandledFrameHandle(
+      new TestWebSocketFrame(),
+      // @ts-expect-error Intentionally invalid value.
+      'intentionally-invalid',
+    ),
+  ).rejects.toThrow(
+    `[MSW] Failed to react to an unhandled network frame: unknown strategy "intentionally-invalid". Please provide one of the supported strategies ("bypass", "warn", "error") or a custom callback function as the value of the "onUnhandledRequest" option.`,
+  )
+})
+
+it('supports printing the default warning in the custom callback for the HTTP frame', async () => {
+  const callback = vi.fn<UnhandledFrameCallback>(({ defaults }) => {
+    defaults.warn()
+  })
+  const frame = new TestWebSocketFrame()
+
+  await expect(
+    executeUnhandledFrameHandle(frame, callback),
+  ).resolves.toBeUndefined()
+
+  expect(callback).toHaveBeenCalledOnce()
+  expect(callback).toHaveBeenCalledWith({
+    defaults: {
+      warn: expect.any(Function),
+      error: expect.any(Function),
+    },
+    frame,
+  })
+  expect.soft(console.warn).toHaveBeenCalledOnce()
+  expect(console.warn).toHaveBeenCalledWith(
+    `[MSW] Warning: intercepted a WebSocket connection without a matching event handler:
+
+  • wss://localhost/test
+
+If you still wish to intercept this unhandled connection, please create an event handler for it.
+Read more: https://mswjs.io/docs/websocket`,
+  )
+  expect(console.error).not.toHaveBeenCalled()
+})
+
+it('supports printing the default error in the custom callback for the HTTP frame', async () => {
+  const callback = vi.fn<UnhandledFrameCallback>(({ defaults }) => {
+    defaults.error()
+  })
+  const frame = new TestWebSocketFrame()
+
+  await expect(
+    executeUnhandledFrameHandle(frame, callback),
+  ).resolves.toBeUndefined()
+
+  expect(callback).toHaveBeenCalledOnce()
+  expect(callback).toHaveBeenCalledWith({
+    defaults: {
+      warn: expect.any(Function),
+      error: expect.any(Function),
+    },
+    frame,
+  })
+  expect.soft(console.error).toHaveBeenCalledOnce()
+  expect(console.error).toHaveBeenCalledWith(
+    `[MSW] Error: intercepted a WebSocket connection without a matching event handler:
+
+  • wss://localhost/test
+
+If you still wish to intercept this unhandled connection, please create an event handler for it.
+Read more: https://mswjs.io/docs/websocket`,
+  )
+  expect(console.warn).not.toHaveBeenCalled()
+})

package/src/core/experimental/on-unhandled-frame.ts

@@ -0,0 +1,110 @@
+import { invariant } from 'outvariant'
+import { isCommonAssetRequest } from '../isCommonAssetRequest'
+import { devUtils, InternalError } from '../utils/internal/devUtils'
+import { HttpNetworkFrame } from './frames/http-frame'
+import { type AnyNetworkFrame } from './frames/network-frame'
+
+export type UnhandledFrameHandle =
+  | UnhandledFrameStrategy
+  | UnhandledFrameCallback
+
+export type UnhandledFrameStrategy = 'bypass' | 'warn' | 'error'
+
+export type UnhandledFrameCallback = (args: {
+  frame: AnyNetworkFrame
+  defaults: UnhandledFrameDefaults
+}) => Promise<void> | void
+
+export type UnhandledFrameDefaults = {
+  warn: () => void
+  error: () => void
+}
+
+export async function executeUnhandledFrameHandle(
+  frame: AnyNetworkFrame,
+  handle: UnhandledFrameHandle,
+): Promise<void> {
+  const printStrategyMessage = async (
+    strategy: UnhandledFrameStrategy,
+  ): Promise<void> => {
+    if (strategy === 'bypass') {
+      return
+    }
+
+    const message = await frame.getUnhandledMessage()
+
+    switch (strategy) {
+      case 'warn': {
+        return devUtils.warn('Warning: %s', message)
+      }
+
+      case 'error': {
+        return devUtils.error('Error: %s', message)
+      }
+    }
+  }
+
+  const applyStrategy = async (
+    strategy: UnhandledFrameStrategy,
+  ): Promise<void> => {
+    invariant.as(
+      InternalError,
+      strategy === 'bypass' || strategy === 'warn' || strategy === 'error',
+      /**
+       * @fixme Rename "onUnhandledRequest" to "onUnhandledFrame" in the error message
+       * with the next major release.
+       */
+      devUtils.formatMessage(
+        'Failed to react to an unhandled network frame: unknown strategy "%s". Please provide one of the supported strategies ("bypass", "warn", "error") or a custom callback function as the value of the "onUnhandledRequest" option.',
+        strategy,
+      ),
+    )
+
+    if (strategy === 'bypass') {
+      return
+    }
+
+    await printStrategyMessage(strategy)
+
+    if (strategy === 'error') {
+      return Promise.reject(
+        new InternalError(
+          devUtils.formatMessage(
+            'Cannot bypass a request when using the "error" strategy for the "onUnhandledRequest" option.',
+          ),
+        ),
+      )
+    }
+  }
+
+  if (typeof handle === 'function') {
+    return handle({
+      frame,
+      defaults: {
+        warn: printStrategyMessage.bind(null, 'warn'),
+        /**
+         * @note The defaults only print the corresponding messages now.
+         * They do not affect the frame resolution (e.g. do not error the frame).
+         * That is only for backward compatibility reasons. In the future, these should
+         * be an alias to `applyStrategy.bind(null, 'error')` instead.
+         */
+        error: printStrategyMessage.bind(null, 'error'),
+      },
+    })
+  }
+
+  /**
+   * Ignore unhandled common HTTP assets.
+   * @note Calling this here applies the common assets check
+   * only to the scenarios when `onUnhandledFrame` was set to a predefined strategy.
+   * When using a custom function, you need to check for common assets manually.
+   */
+  if (
+    frame instanceof HttpNetworkFrame &&
+    isCommonAssetRequest(frame.data.request)
+  ) {
+    return
+  }
+
+  return applyStrategy(handle)
+}

package/src/core/experimental/request-utils.test.ts

@@ -0,0 +1,70 @@
+import {
+  deleteRequestPassthroughHeader,
+  isPassthroughResponse,
+  REQUEST_INTENTION_HEADER_NAME,
+  RequestIntention,
+  shouldBypassRequest,
+} from './request-utils'
+
+describe(shouldBypassRequest, () => {
+  it('returns true for a request with bypass header', () => {
+    expect(
+      shouldBypassRequest(
+        new Request('http://example.com', {
+          headers: {
+            accept: 'msw/passthrough',
+          },
+        }),
+      ),
+    ).toBe(true)
+  })
+
+  it('returns false for a regular request', () => {
+    expect(shouldBypassRequest(new Request('http://example.com'))).toBe(false)
+  })
+})
+
+describe(isPassthroughResponse, () => {
+  it('returns true for a passthrough response', () => {
+    expect(
+      isPassthroughResponse(
+        new Response(null, {
+          status: 302,
+          headers: {
+            [REQUEST_INTENTION_HEADER_NAME]: RequestIntention.passthrough,
+          },
+        }),
+      ),
+    ).toBe(true)
+  })
+
+  it('returns false for a regular response', () => {
+    expect(isPassthroughResponse(new Response(null))).toBe(false)
+    expect(isPassthroughResponse(new Response(null, { status: 302 }))).toBe(
+      false,
+    )
+  })
+})
+
+describe(deleteRequestPassthroughHeader, () => {
+  it('removes the bypass header from the request', () => {
+    const request = new Request('http://example.com', {
+      headers: {
+        accept: 'msw/passthrough',
+      },
+    })
+    deleteRequestPassthroughHeader(request)
+    expect(request.headers.get('accept')).toBeNull()
+  })
+
+  it('does not remove other headers', () => {
+    const request = new Request('http://example.com', {
+      headers: {
+        accept: 'msw/passthrough',
+        'content-type': 'application/json',
+      },
+    })
+    deleteRequestPassthroughHeader(request)
+    expect(request.headers.get('content-type')).toBe('application/json')
+  })
+})