msw 2.12.13 → 2.13.0

package/src/core/experimental/frames/websocket-frame.test.ts

@@ -0,0 +1,280 @@
+import { http } from '../../http'
+import { graphql } from '../../graphql'
+import { ws } from '../../ws'
+import {
+  WebSocketNetworkFrame,
+  WebSocketNetworkFrameEventMap,
+} from './websocket-frame'
+import { createTestWebSocketConnection } from '../../../../test/support/ws-test-utils'
+import { InMemoryHandlersController } from '#core/experimental/handlers-controller'
+
+beforeAll(() => {
+  vi.spyOn(console, 'error').mockImplementation(() => {})
+})
+
+afterEach(() => {
+  vi.clearAllMocks()
+})
+
+afterAll(() => {
+  vi.restoreAllMocks()
+})
+
+function spyOnWebSocketFrame(frame: WebSocketNetworkFrame) {
+  const events: Array<
+    WebSocketNetworkFrameEventMap[keyof WebSocketNetworkFrameEventMap]
+  > = []
+
+  frame.events.on('*', (event) => events.push(event))
+
+  return {
+    events,
+  }
+}
+
+it('filters only websocket type handlers', async () => {
+  class WebSocketFrame extends WebSocketNetworkFrame {
+    passthrough = vi.fn()
+    errorWith = vi.fn()
+  }
+
+  const connection = createTestWebSocketConnection('ws://localhost/api')
+  const frame = new WebSocketFrame({ connection })
+
+  const httpHandlers = [http.post('http://localhost/api/user', () => {})]
+  const graphqlHandlers = [graphql.query('GetUser', () => {})]
+  const webSocketHandlers = [
+    ws.link('ws://localhost').addEventListener('connection', () => {}),
+  ]
+
+  const controller = new InMemoryHandlersController([
+    ...httpHandlers,
+    ...webSocketHandlers,
+    ...graphqlHandlers,
+  ])
+
+  expect(frame.getHandlers(controller)).toEqual(webSocketHandlers)
+  expect(frame.getHandlers(new InMemoryHandlersController([]))).toEqual([])
+})
+
+it('resolves a matching connection', async () => {
+  class WebSocketFrame extends WebSocketNetworkFrame {
+    passthrough = vi.fn()
+    errorWith = vi.fn()
+  }
+
+  const connection = createTestWebSocketConnection('ws://localhost/api')
+  const frame = new WebSocketFrame({ connection })
+  const { events } = spyOnWebSocketFrame(frame)
+
+  const connectionListener = vi.fn()
+  const unhandledFrameCallback = vi.fn()
+
+  const api = ws.link('ws://localhost/api')
+  const matches = await frame.resolve(
+    [api.addEventListener('connection', connectionListener)],
+    unhandledFrameCallback,
+    { quiet: true },
+  )
+
+  expect.soft(matches).toBe(true)
+  expect
+    .soft(connectionListener)
+    .toHaveBeenCalledExactlyOnceWith(expect.objectContaining(connection))
+  expect.soft(frame.passthrough).not.toHaveBeenCalled()
+  expect.soft(frame.errorWith).not.toHaveBeenCalled()
+  expect.soft(unhandledFrameCallback).not.toHaveBeenCalled()
+  expect.soft(events).toEqual([
+    expect.objectContaining({
+      type: 'connection',
+      url: connection.client.url,
+      protocols: connection.info.protocols,
+    }),
+  ])
+})
+
+it('resolves a connection when there are no handlers', async () => {
+  class WebSocketFrame extends WebSocketNetworkFrame {
+    passthrough = vi.fn()
+    errorWith = vi.fn()
+  }
+
+  const connection = createTestWebSocketConnection('ws://localhost/api')
+  const frame = new WebSocketFrame({ connection })
+  const { events } = spyOnWebSocketFrame(frame)
+
+  const connectionListener = vi.fn()
+  const unhandledFrameCallback = vi.fn()
+
+  const matches = await frame.resolve([], unhandledFrameCallback, {
+    quiet: true,
+  })
+
+  expect.soft(matches).toBe(false)
+  expect.soft(frame.passthrough).toHaveBeenCalledOnce()
+  expect.soft(connectionListener).not.toHaveBeenCalled()
+  expect.soft(frame.errorWith).not.toHaveBeenCalled()
+  expect.soft(unhandledFrameCallback).toHaveBeenCalledExactlyOnceWith(
+    expect.objectContaining({
+      frame,
+    }),
+  )
+  expect.soft(events).toEqual([
+    expect.objectContaining({
+      type: 'connection',
+      url: connection.client.url,
+      protocols: connection.info.protocols,
+    }),
+  ])
+})
+
+it('resolves a non-matching connection', async () => {
+  class WebSocketFrame extends WebSocketNetworkFrame {
+    passthrough = vi.fn()
+    errorWith = vi.fn()
+  }
+
+  const connection = createTestWebSocketConnection('ws://localhost/api')
+  const frame = new WebSocketFrame({ connection })
+  const { events } = spyOnWebSocketFrame(frame)
+
+  const connectionListener = vi.fn()
+  const unhandledFrameCallback = vi.fn()
+
+  const api = ws.link('ws://example.com/api')
+  const matches = await frame.resolve(
+    [api.addEventListener('connection', connectionListener)],
+    unhandledFrameCallback,
+    { quiet: true },
+  )
+
+  expect.soft(matches).toBe(false)
+  expect.soft(frame.passthrough).toHaveBeenCalledOnce()
+  expect.soft(connectionListener).not.toHaveBeenCalled()
+  expect.soft(frame.errorWith).not.toHaveBeenCalled()
+  expect.soft(unhandledFrameCallback).toHaveBeenCalledExactlyOnceWith(
+    expect.objectContaining({
+      frame,
+    }),
+  )
+  expect.soft(events).toEqual([
+    expect.objectContaining({
+      type: 'connection',
+      url: connection.client.url,
+      protocols: connection.info.protocols,
+    }),
+  ])
+})
+
+it('returns null and prints the error on unhandled exception', async () => {
+  class WebSocketFrame extends WebSocketNetworkFrame {
+    passthrough = vi.fn()
+    errorWith = vi.fn()
+  }
+
+  const connection = createTestWebSocketConnection('ws://localhost/api')
+  const frame = new WebSocketFrame({ connection })
+  const { events } = spyOnWebSocketFrame(frame)
+
+  const unhandledFrameCallback = vi.fn()
+
+  const api = ws.link('ws://localhost/api')
+  const exception = new Error('Unhandled exceptin')
+
+  await expect
+    .soft(
+      frame.resolve(
+        [
+          api.addEventListener('connection', () => {
+            throw exception
+          }),
+        ],
+        unhandledFrameCallback,
+        { quiet: true },
+      ),
+    )
+    .rejects.toThrow(exception)
+  expect.soft(frame.errorWith).not.toHaveBeenCalled()
+  expect.soft(frame.passthrough).not.toHaveBeenCalled()
+  expect.soft(unhandledFrameCallback).not.toHaveBeenCalled()
+  expect.soft(events).toEqual([
+    expect.objectContaining({
+      type: 'connection',
+      url: connection.client.url,
+      protocols: connection.info.protocols,
+    }),
+    expect.objectContaining({
+      type: 'unhandledException',
+      error: exception,
+      url: connection.client.url,
+      protocols: connection.info.protocols,
+    }),
+  ])
+
+  expect.soft(console.error).toHaveBeenCalledTimes(2)
+  expect.soft(console.error).toHaveBeenNthCalledWith(1, exception)
+  expect
+    .soft(console.error)
+    .toHaveBeenNthCalledWith(
+      2,
+      '[MSW] Encountered an unhandled exception during the handler lookup for "ws://localhost/api". Please see the original error above.',
+    )
+})
+
+it('does not print an unhandled exception if the "unhandledException" listener is present', async () => {
+  class WebSocketFrame extends WebSocketNetworkFrame {
+    passthrough = vi.fn()
+    errorWith = vi.fn()
+  }
+
+  const connection = createTestWebSocketConnection('ws://localhost/api')
+  const frame = new WebSocketFrame({ connection })
+  const { events } = spyOnWebSocketFrame(frame)
+
+  const unhandledExceptionListener = vi.fn()
+  frame.events.on('unhandledException', unhandledExceptionListener)
+
+  const unhandledFrameCallback = vi.fn()
+
+  const api = ws.link('ws://localhost/api')
+  const exception = new Error('Unhandled exception')
+
+  await expect
+    .soft(
+      frame.resolve(
+        [
+          api.addEventListener('connection', () => {
+            throw exception
+          }),
+        ],
+        unhandledFrameCallback,
+        { quiet: true },
+      ),
+    )
+    .rejects.toThrow(exception)
+  expect.soft(frame.errorWith).not.toHaveBeenCalled()
+  expect.soft(frame.passthrough).not.toHaveBeenCalled()
+  expect.soft(unhandledFrameCallback).not.toHaveBeenCalled()
+  expect.soft(events).toEqual([
+    expect.objectContaining({
+      type: 'connection',
+      url: connection.client.url,
+      protocols: connection.info.protocols,
+    }),
+    expect.objectContaining({
+      type: 'unhandledException',
+      error: exception,
+      url: connection.client.url,
+      protocols: connection.info.protocols,
+    }),
+  ])
+
+  expect.soft(unhandledExceptionListener).toHaveBeenCalledExactlyOnceWith(
+    expect.objectContaining({
+      error: exception,
+      url: connection.client.url,
+      protocols: connection.info.protocols,
+    }),
+  )
+  expect.soft(console.error).not.toHaveBeenCalled()
+})

package/src/core/experimental/frames/websocket-frame.ts

@@ -0,0 +1,188 @@
+import { TypedEvent } from 'rettime'
+import { type WebSocketConnectionData } from '@mswjs/interceptors/WebSocket'
+import {
+  kConnect,
+  kAutoConnect,
+  type WebSocketHandler,
+} from '../../handlers/WebSocketHandler'
+import {
+  NetworkFrame,
+  type NetworkFrameResolutionContext,
+} from './network-frame'
+import {
+  executeUnhandledFrameHandle,
+  UnhandledFrameHandle,
+} from '../on-unhandled-frame'
+import { devUtils } from '../../utils/internal/devUtils'
+import { HandlersController, AnyHandler } from '../handlers-controller'
+
+export interface WebSocketNetworkFrameOptions {
+  connection: WebSocketConnectionData
+}
+
+export type WebSocketNetworkFrameEventMap = {
+  connection: WebSocketConnectionEvent
+  unhandledException: UnhandledWebSocketExceptionEvent
+}
+
+class WebSocketConnectionEvent<
+  DataType extends {
+    url: URL
+    protocols: string | Array<string> | undefined
+  } = { url: URL; protocols: string | Array<string> | undefined },
+  ReturnType = void,
+  EventType extends string = string,
+> extends TypedEvent<DataType, ReturnType, EventType> {
+  public readonly url: URL
+  public readonly protocols: string | Array<string> | undefined
+
+  constructor(type: EventType, data: DataType) {
+    super(...([type, {}] as any))
+    this.url = data.url
+    this.protocols = data.protocols
+  }
+}
+
+class UnhandledWebSocketExceptionEvent<
+  DataType extends {
+    url: URL
+    protocols: string | Array<string> | undefined
+    error: unknown
+  } = {
+    url: URL
+    protocols: string | Array<string> | undefined
+    error: unknown
+  },
+  ReturnType = void,
+  EventType extends string = string,
+> extends TypedEvent<DataType, ReturnType, EventType> {
+  public readonly url: URL
+  public readonly protocols: string | Array<string> | undefined
+  public readonly error: unknown
+
+  constructor(type: EventType, data: DataType) {
+    super(...([type, {}] as any))
+    this.url = data.url
+    this.protocols = data.protocols
+    this.error = data.error
+  }
+}
+
+export abstract class WebSocketNetworkFrame extends NetworkFrame<
+  'ws',
+  {
+    connection: WebSocketConnectionData
+  },
+  WebSocketNetworkFrameEventMap
+> {
+  constructor(options: WebSocketNetworkFrameOptions) {
+    super('ws', {
+      connection: options.connection,
+    })
+  }
+
+  public getHandlers(controller: HandlersController): Array<AnyHandler> {
+    return controller.getHandlersByKind('websocket')
+  }
+
+  public async resolve(
+    handlers: Array<WebSocketHandler>,
+    onUnhandledFrame: UnhandledFrameHandle,
+    resolutionContext?: NetworkFrameResolutionContext,
+  ): Promise<boolean | null> {
+    const { connection } = this.data
+
+    this.events.emit(
+      new WebSocketConnectionEvent('connection', {
+        url: connection.client.url,
+        protocols: connection.info.protocols,
+      }),
+    )
+
+    // No WebSocket handlers defined.
+    if (handlers.length === 0) {
+      await executeUnhandledFrameHandle(this, onUnhandledFrame).then(
+        () => this.passthrough(),
+        (error) => this.errorWith(error),
+      )
+
+      return false
+    }
+
+    let hasMatchingHandlers = false
+
+    for (const handler of handlers) {
+      const handlerConnection = await handler.run(connection, {
+        baseUrl: resolutionContext?.baseUrl?.toString(),
+        /**
+         * @note Do not emit the "connection" event when running the handler.
+         * Use the run only to get the resolved connection object.
+         */
+        [kAutoConnect]: false,
+      })
+
+      if (!handlerConnection) {
+        continue
+      }
+
+      hasMatchingHandlers = true
+
+      /**
+       * @note Attach the WebSocket logger *before* emitting the "connection" event.
+       * Connection event listeners may perform actions that should be reflected in the logs
+       * (e.g. closing the connection immediately). If the logger is attached after the connection,
+       * those actions cannot be properly logged.
+       */
+      const removeLogger = !resolutionContext?.quiet
+        ? handler.log(connection)
+        : undefined
+
+      try {
+        if (!handler[kConnect](handlerConnection)) {
+          removeLogger?.()
+        }
+      } catch (error) {
+        if (
+          !this.events.emit(
+            new UnhandledWebSocketExceptionEvent('unhandledException', {
+              error,
+              url: connection.client.url,
+              protocols: connection.info.protocols,
+            }),
+          )
+        ) {
+          console.error(error)
+          devUtils.error(
+            'Encountered an unhandled exception during the handler lookup for "%s". Please see the original error above.',
+            connection.client.url,
+          )
+        }
+
+        /**
+         * @note Throw the caught error so it gets picked up by WebSocketInterceptor.
+         * It's the interceptor who translates handler errors to WebSocket closures.
+         */
+        throw error
+      }
+    }
+
+    // No matching WebSocket handlers found.
+    if (!hasMatchingHandlers) {
+      await executeUnhandledFrameHandle(this, onUnhandledFrame).then(
+        () => this.passthrough(),
+        (error) => this.errorWith(error),
+      )
+
+      return false
+    }
+
+    return true
+  }
+
+  public async getUnhandledMessage(): Promise<string> {
+    const { connection } = this.data
+    const details = `\n\n  \u2022 ${connection.client.url}\n\n`
+
+    return `intercepted a WebSocket connection without a matching event handler:${details}If you still wish to intercept this unhandled connection, please create an event handler for it.\nRead more: https://mswjs.io/docs/websocket`
+  }
+}

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

@@ -0,0 +1,198 @@
+import { http } from '../http'
+import { graphql } from '../graphql'
+import { ws } from '../ws'
+import { InMemoryHandlersController } from './handlers-controller'
+
+describe(InMemoryHandlersController.prototype.use, () => {
+  it('prepends a handler to an empty controller', () => {
+    const controller = new InMemoryHandlersController([])
+    const httpHandler = http.get('/', () => {})
+    controller.use([httpHandler])
+
+    expect(controller.currentHandlers()).toEqual([httpHandler])
+    expect(controller.getHandlersByKind('request')).toEqual([httpHandler])
+  })
+
+  it('prepends a single handler', () => {
+    const httpOne = http.get('/', () => {})
+    const httpTwo = http.get('/', () => {})
+
+    const controller = new InMemoryHandlersController([httpOne])
+    controller.use([httpTwo])
+
+    expect(controller.currentHandlers()).toEqual([httpTwo, httpOne])
+    expect(controller.getHandlersByKind('request')).toEqual([httpTwo, httpOne])
+  })
+
+  it('prepends multiple handlers', () => {
+    const httpOne = http.get('/', () => {})
+    const httpTwo = http.get('/', () => {})
+    const httpThree = http.get('/', () => {})
+
+    const controller = new InMemoryHandlersController([httpOne])
+
+    controller.use([httpTwo, httpThree])
+
+    expect(controller.currentHandlers()).toEqual([httpTwo, httpThree, httpOne])
+    expect(controller.getHandlersByKind('request')).toEqual([
+      httpTwo,
+      httpThree,
+      httpOne,
+    ])
+  })
+
+  it('preserves order of handlers', () => {
+    const httpOne = http.get('/', () => {})
+    const graphqlOne = graphql.query('', () => {})
+    const httpTwo = http.get('/', () => {})
+
+    const controller = new InMemoryHandlersController([httpOne])
+    controller.use([graphqlOne, httpTwo])
+
+    expect(controller.currentHandlers()).toEqual([graphqlOne, httpTwo, httpOne])
+  })
+})
+
+describe(InMemoryHandlersController.prototype.reset, () => {
+  it('resets to the initial handlers if called with an empty list', () => {
+    {
+      const controller = new InMemoryHandlersController([])
+      controller.reset([])
+      expect(controller.currentHandlers()).toEqual([])
+    }
+
+    {
+      const httpHandler = http.get('/', () => {})
+      const controller = new InMemoryHandlersController([httpHandler])
+
+      controller.reset([])
+      expect(controller.currentHandlers()).toEqual([httpHandler])
+    }
+  })
+
+  it('replaces the initial handlers if called with a list of handlers', () => {
+    const httpOne = http.get('/', () => {})
+    const httpTwo = http.get('/', () => {})
+    const controller = new InMemoryHandlersController([httpOne])
+
+    controller.reset([httpTwo])
+    expect(controller.currentHandlers()).toEqual([httpTwo])
+  })
+
+  it('resets the initial handlers after runtime handlers are applied', () => {
+    const httpOne = http.get('/', () => {})
+    const httpTwo = http.get('/', () => {})
+    const controller = new InMemoryHandlersController([])
+    controller.use([httpOne])
+
+    controller.reset([httpTwo])
+    expect(controller.currentHandlers()).toEqual([httpTwo])
+
+    controller.reset([])
+    /**
+     * @note There's no way to "clear" the initial state via ".reset()".
+     * You can only provide the next initial state. The public-facing ".resetHandlers()"
+     * spread the arguments so there's no distinction between () and ([]).
+     */
+    expect(controller.currentHandlers()).toEqual([httpTwo])
+  })
+})
+
+describe(InMemoryHandlersController.prototype.getHandlersByKind, () => {
+  it('returns an empty array given an empty controller', () => {
+    const controller = new InMemoryHandlersController([])
+    expect(controller.getHandlersByKind('request')).toEqual([])
+  })
+
+  it('returns an empty array given no handlers by the given kind', () => {
+    expect(
+      new InMemoryHandlersController([
+        http.get('/', () => {}),
+        graphql.query('', () => {}),
+      ]).getHandlersByKind('websocket'),
+    ).toEqual([])
+
+    expect(
+      new InMemoryHandlersController([
+        ws.link('*').addEventListener('connection', () => {}),
+      ]).getHandlersByKind('request'),
+    ).toEqual([])
+  })
+
+  it('returns all handlers if they all match', () => {
+    const httpHandler = http.get('/', () => {})
+    const graphqlHandler = graphql.query('', () => {})
+    const wsHandler = ws.link('*').addEventListener('connection', () => {})
+
+    expect(
+      new InMemoryHandlersController([
+        httpHandler,
+        graphqlHandler,
+      ]).getHandlersByKind('request'),
+    ).toEqual([httpHandler, graphqlHandler])
+
+    expect(
+      new InMemoryHandlersController([wsHandler]).getHandlersByKind(
+        'websocket',
+      ),
+    ).toEqual([wsHandler])
+  })
+
+  it('returns only the matching handlers', () => {
+    const httpHandler = http.get('/', () => {})
+    const graphqlHandler = graphql.query('', () => {})
+    const wsHandler = ws.link('*').addEventListener('connection', () => {})
+
+    expect(
+      new InMemoryHandlersController([
+        httpHandler,
+        graphqlHandler,
+        wsHandler,
+      ]).getHandlersByKind('request'),
+    ).toEqual([httpHandler, graphqlHandler])
+
+    expect(
+      new InMemoryHandlersController([
+        httpHandler,
+        graphqlHandler,
+        wsHandler,
+      ]).getHandlersByKind('websocket'),
+    ).toEqual([wsHandler])
+  })
+
+  it('preserves the order of returned handlers', () => {
+    const httpOne = http.get('/', () => {})
+    const httpTwo = http.get('/', () => {})
+    const httpThree = http.get('/', () => {})
+
+    expect(
+      new InMemoryHandlersController([
+        httpOne,
+        httpTwo,
+        httpThree,
+      ]).getHandlersByKind('request'),
+    ).toEqual([httpOne, httpTwo, httpThree])
+
+    const graphqlOne = graphql.query('', () => {})
+    const graphqlTwo = graphql.query('', () => {})
+    const graphqlThree = graphql.query('', () => {})
+
+    expect(
+      new InMemoryHandlersController([
+        graphqlOne,
+        graphqlTwo,
+        graphqlThree,
+      ]).getHandlersByKind('request'),
+    ).toEqual([graphqlOne, graphqlTwo, graphqlThree])
+
+    const wsOne = ws.link('*').addEventListener('connection', () => {})
+    const wsTwo = ws.link('*').addEventListener('connection', () => {})
+    const wsThree = ws.link('*').addEventListener('connection', () => {})
+
+    expect(
+      new InMemoryHandlersController([wsOne, wsTwo, wsThree]).getHandlersByKind(
+        'websocket',
+      ),
+    ).toEqual([wsOne, wsTwo, wsThree])
+  })
+})