msw 2.14.7 → 3.0.0

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

@@ -1,10 +1,12 @@
 import { TypedEvent } from 'rettime'
-import { type WebSocketConnectionData } from '@mswjs/interceptors/WebSocket'
+import type { GraphQLSubscriptionEvent } from '#graphql/graphql-subscription-event'
+import type { WebSocketConnectionEventData } from '@mswjs/interceptors/WebSocket'
 import {
   kConnect,
   kAutoConnect,
   type WebSocketHandler,
-} from '../../handlers/WebSocketHandler'
+  type AnyWebSocketExtension,
+} from '#ws/websocket-handler'
 import {
   NetworkFrame,
   type NetworkFrameResolutionContext,
@@ -13,17 +15,28 @@ import {
   executeUnhandledFrameHandle,
   type UnhandledFrameHandle,
 } from '../on-unhandled-frame'
-import { devUtils } from '../../utils/internal/devUtils'
+import { devUtils } from '../../utils/internal/dev-utils'
 import type { HandlersController } from '../handlers-controller'
-import { type AnyHandler } from '../handlers-controller'
+import type { AnyHandler } from '../handlers-controller'
 
 export interface WebSocketNetworkFrameOptions {
-  connection: WebSocketConnectionData
+  connection: WebSocketConnectionEventData
 }
 
 export type WebSocketNetworkFrameEventMap = {
-  connection: WebSocketConnectionEvent
-  unhandledException: UnhandledWebSocketExceptionEvent
+  /**
+   * Emitted when a WebSocket connection is intercepted,
+   * before any handlers are resolved against it.
+   */
+  'websocket:connection': WebSocketConnectionEvent
+  /**
+   * Emitted when the WebSocket connection errors.
+   * This includes initial connection errors as well as runtime errors
+   * after the connection has been established.
+   */
+  'websocket:error': WebSocketErrorEvent
+  'graphql:subscription': GraphQLSubscriptionEvent
+  unhandledException: WebSocketErrorEvent
 }
 
 class WebSocketConnectionEvent<
@@ -44,7 +57,7 @@ class WebSocketConnectionEvent<
   }
 }
 
-class UnhandledWebSocketExceptionEvent<
+class WebSocketErrorEvent<
   DataType extends {
     url: URL
     protocols: string | Array<string> | undefined
@@ -56,15 +69,11 @@ class UnhandledWebSocketExceptionEvent<
   },
   ReturnType = void,
   EventType extends string = string,
-> extends TypedEvent<DataType, ReturnType, EventType> {
-  public readonly url: URL
-  public readonly protocols: string | Array<string> | undefined
+> extends WebSocketConnectionEvent<DataType, ReturnType, EventType> {
   public readonly error: unknown
 
   constructor(type: EventType, data: DataType) {
-    super(...([type, {}] as any))
-    this.url = data.url
-    this.protocols = data.protocols
+    super(type, data)
     this.error = data.error
   }
 }
@@ -72,7 +81,7 @@ class UnhandledWebSocketExceptionEvent<
 export abstract class WebSocketNetworkFrame extends NetworkFrame<
   'ws',
   {
-    connection: WebSocketConnectionData
+    connection: WebSocketConnectionEventData
   },
   WebSocketNetworkFrameEventMap
 > {
@@ -87,19 +96,38 @@ export abstract class WebSocketNetworkFrame extends NetworkFrame<
   }
 
   public async resolve(
-    handlers: Array<WebSocketHandler>,
+    handlers: Array<WebSocketHandler<AnyWebSocketExtension>>,
     onUnhandledFrame: UnhandledFrameHandle,
     resolutionContext?: NetworkFrameResolutionContext,
   ): Promise<boolean | null> {
     const { connection } = this.data
 
     this.events.emit(
-      new WebSocketConnectionEvent('connection', {
+      new WebSocketConnectionEvent('websocket:connection', {
         url: connection.client.url,
         protocols: connection.info.protocols,
       }),
     )
 
+    const handleSocketError = (event: Event) => {
+      this.events.emit(
+        new WebSocketErrorEvent('websocket:error', {
+          url: connection.client.url,
+          protocols: connection.info.protocols,
+          error: getErrorFromEvent(event),
+        }),
+      )
+    }
+
+    connection.client.socket.addEventListener('error', handleSocketError)
+    connection.client.socket.addEventListener(
+      'close',
+      () => {
+        connection.client.socket.removeEventListener('error', handleSocketError)
+      },
+      { once: true },
+    )
+
     // No WebSocket handlers defined.
     if (handlers.length === 0) {
       await executeUnhandledFrameHandle(this, onUnhandledFrame).then(
@@ -116,7 +144,13 @@ export abstract class WebSocketNetworkFrame extends NetworkFrame<
       const handlerConnection = await handler.run(connection, {
         baseUrl: resolutionContext?.baseUrl?.toString(),
         /**
-         * @note Do not emit the "connection" event when running the handler.
+         * @note Expose an emit-only reference to this frame's events
+         * so the handlers can emit additional events not covered by
+         * the frame (e.g. "graphql:subscription").
+         */
+        events: this.events,
+        /**
+         * @note Do not emit the handler's "connection" event when running the handler.
          * Use the run only to get the resolved connection object.
          */
         [kAutoConnect]: false,
@@ -129,7 +163,7 @@ export abstract class WebSocketNetworkFrame extends NetworkFrame<
       hasMatchingHandlers = true
 
       /**
-       * @note Attach the WebSocket logger *before* emitting the "connection" event.
+       * @note Attach the WebSocket logger *before* emitting the handler's "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.
@@ -145,7 +179,7 @@ export abstract class WebSocketNetworkFrame extends NetworkFrame<
       } catch (error) {
         if (
           !this.events.emit(
-            new UnhandledWebSocketExceptionEvent('unhandledException', {
+            new WebSocketErrorEvent('unhandledException', {
               error,
               url: connection.client.url,
               protocols: connection.info.protocols,
@@ -187,3 +221,20 @@ export abstract class WebSocketNetworkFrame extends NetworkFrame<
     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`
   }
 }
+
+/**
+ * Extract the error from the given "error" event, if any.
+ * Supports both the `ErrorEvent.error` property and the `cause`
+ * property that MSW sets when erroring the connection itself.
+ */
+function getErrorFromEvent(event: Event): unknown {
+  if ('error' in event && event.error != null) {
+    return event.error
+  }
+
+  if ('cause' in event && event.cause != null) {
+    return event.cause
+  }
+
+  return undefined
+}

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

@@ -1,11 +1,66 @@
-import { http } from '../http'
-import { graphql } from '../graphql'
-import { ws } from '../ws'
-import { getSiblingHandlers } from '../utils/internal/attachSiblingHandlers'
-import { InMemoryHandlersController } from './handlers-controller'
+import { http } from '#http/http'
+import { graphql } from '../../graphql'
+import { ws } from '../../ws'
+import {
+  attachSiblingHandlers,
+  getSiblingHandlers,
+} from '../utils/internal/attach-sibling-handlers'
+import {
+  groupHandlersByKind,
+  InMemoryHandlersController,
+} from './handlers-controller'
+
+const gql = graphql.link('*')
+
+describe(groupHandlersByKind, () => {
+  test('groups handlers attached as siblings of siblings', () => {
+    const grandchildHandler = http.get('/grandchild', () => {})
+    const childHandler = attachSiblingHandlers(
+      http.get('/child', () => {}),
+      [grandchildHandler],
+    )
+    const ownerHandler = attachSiblingHandlers(
+      http.get('/owner', () => {}),
+      [childHandler],
+    )
+
+    expect(groupHandlersByKind([ownerHandler]).request).toEqual([
+      ownerHandler,
+      childHandler,
+      grandchildHandler,
+    ])
+  })
+
+  test('groups nested siblings of a different kind into their own bucket', () => {
+    const chat = ws.link('*')
+    const wsHandler = chat.addEventListener('connection', () => {})
+    const [upgradeHandler] = getSiblingHandlers(wsHandler)
+    const ownerHandler = attachSiblingHandlers(
+      http.get('/owner', () => {}),
+      [wsHandler],
+    )
+
+    const groups = groupHandlersByKind([ownerHandler])
+
+    expect(groups.websocket).toEqual([wsHandler])
+    expect(groups.request).toEqual([ownerHandler, upgradeHandler])
+  })
+
+  test('does not recurse infinitely given a cyclic sibling graph', () => {
+    const handlerOne = http.get('/one', () => {})
+    const handlerTwo = http.get('/two', () => {})
+    attachSiblingHandlers(handlerOne, [handlerTwo])
+    attachSiblingHandlers(handlerTwo, [handlerOne])
+
+    expect(groupHandlersByKind([handlerOne]).request).toEqual([
+      handlerOne,
+      handlerTwo,
+    ])
+  })
+})
 
 describe('constructor', () => {
-  it('places the sibling in its own kind bucket', () => {
+  test('places the sibling in its own kind bucket', () => {
     const wsHandler = ws.link('*').addEventListener('connection', () => {})
     const [upgradeHandler] = getSiblingHandlers(wsHandler)
 
@@ -15,7 +70,7 @@ describe('constructor', () => {
     expect(controller.getHandlersByKind('request')).toEqual([upgradeHandler])
   })
 
-  it('interleaves the sibling at the owner position when grouping by kind', () => {
+  test('interleaves the sibling at the owner position when grouping by kind', () => {
     const httpOne = http.get('/', () => {})
     const wsHandler = ws.link('*').addEventListener('connection', () => {})
     const [upgradeHandler] = getSiblingHandlers(wsHandler)
@@ -35,7 +90,7 @@ describe('constructor', () => {
     expect(controller.getHandlersByKind('websocket')).toEqual([wsHandler])
   })
 
-  it('extracts siblings from every owner in the input list', () => {
+  test('extracts siblings from every owner in the input list', () => {
     const wsOne = ws.link('*').addEventListener('connection', () => {})
     const wsTwo = ws.link('*').addEventListener('connection', () => {})
     const [upgradeOne] = getSiblingHandlers(wsOne)
@@ -50,7 +105,7 @@ describe('constructor', () => {
     ])
   })
 
-  it('dedupes the shared upgrade sibling across multiple handlers from the same link', () => {
+  test('dedupes the shared upgrade sibling across multiple handlers from the same link', () => {
     const chat = ws.link('*')
     const wsOne = chat.addEventListener('connection', () => {})
     const wsTwo = chat.addEventListener('connection', () => {})
@@ -64,7 +119,7 @@ describe('constructor', () => {
 })
 
 describe(InMemoryHandlersController.prototype.use, () => {
-  it('prepends a handler to an empty controller', () => {
+  test('prepends a handler to an empty controller', () => {
     const controller = new InMemoryHandlersController([])
     const httpHandler = http.get('/', () => {})
     controller.use([httpHandler])
@@ -73,7 +128,7 @@ describe(InMemoryHandlersController.prototype.use, () => {
     expect(controller.getHandlersByKind('request')).toEqual([httpHandler])
   })
 
-  it('prepends a single handler', () => {
+  test('prepends a single handler', () => {
     const httpOne = http.get('/', () => {})
     const httpTwo = http.get('/', () => {})
 
@@ -84,7 +139,7 @@ describe(InMemoryHandlersController.prototype.use, () => {
     expect(controller.getHandlersByKind('request')).toEqual([httpTwo, httpOne])
   })
 
-  it('prepends multiple handlers', () => {
+  test('prepends multiple handlers', () => {
     const httpOne = http.get('/', () => {})
     const httpTwo = http.get('/', () => {})
     const httpThree = http.get('/', () => {})
@@ -101,9 +156,9 @@ describe(InMemoryHandlersController.prototype.use, () => {
     ])
   })
 
-  it('preserves order of handlers', () => {
+  test('preserves order of handlers', () => {
     const httpOne = http.get('/', () => {})
-    const graphqlOne = graphql.query('', () => {})
+    const graphqlOne = gql.query('', () => {})
     const httpTwo = http.get('/', () => {})
 
     const controller = new InMemoryHandlersController([httpOne])
@@ -112,7 +167,7 @@ describe(InMemoryHandlersController.prototype.use, () => {
     expect(controller.currentHandlers()).toEqual([graphqlOne, httpTwo, httpOne])
   })
 
-  it('propagates siblings to their kind buckets at runtime', () => {
+  test('propagates siblings to their kind buckets at runtime', () => {
     const controller = new InMemoryHandlersController([])
     const wsHandler = ws.link('*').addEventListener('connection', () => {})
     const [upgradeHandler] = getSiblingHandlers(wsHandler)
@@ -123,7 +178,7 @@ describe(InMemoryHandlersController.prototype.use, () => {
     expect(controller.getHandlersByKind('request')).toEqual([upgradeHandler])
   })
 
-  it('prepends incoming siblings before existing handlers of the same kind', () => {
+  test('prepends incoming siblings before existing handlers of the same kind', () => {
     const existingHttp = http.get('/existing', () => {})
     const controller = new InMemoryHandlersController([existingHttp])
     const wsHandler = ws.link('*').addEventListener('connection', () => {})
@@ -137,7 +192,7 @@ describe(InMemoryHandlersController.prototype.use, () => {
     ])
   })
 
-  it('dedupes the shared upgrade sibling when called with multiple handlers from the same link', () => {
+  test('dedupes the shared upgrade sibling when called with multiple handlers from the same link', () => {
     const chat = ws.link('*')
     const wsOne = chat.addEventListener('connection', () => {})
     const wsTwo = chat.addEventListener('connection', () => {})
@@ -149,10 +204,33 @@ describe(InMemoryHandlersController.prototype.use, () => {
     expect(controller.getHandlersByKind('websocket')).toEqual([wsOne, wsTwo])
     expect(controller.getHandlersByKind('request')).toEqual([upgradeHandler])
   })
+
+  test('dedupes the shared upgrade sibling against already-registered handlers', () => {
+    const chat = ws.link('*')
+    const wsOne = chat.addEventListener('connection', () => {})
+    const [upgradeHandler] = getSiblingHandlers(wsOne)
+    const controller = new InMemoryHandlersController([wsOne])
+
+    const wsTwo = chat.addEventListener('connection', () => {})
+    controller.use([wsTwo])
+
+    expect(controller.getHandlersByKind('websocket')).toEqual([wsTwo, wsOne])
+    expect(controller.getHandlersByKind('request')).toEqual([upgradeHandler])
+  })
+
+  test('moves an already-registered handler to the front when used again', () => {
+    const httpOne = http.get('/one', () => {})
+    const httpTwo = http.get('/two', () => {})
+    const controller = new InMemoryHandlersController([httpOne, httpTwo])
+
+    controller.use([httpTwo])
+
+    expect(controller.getHandlersByKind('request')).toEqual([httpTwo, httpOne])
+  })
 })
 
 describe(InMemoryHandlersController.prototype.reset, () => {
-  it('resets to the initial handlers if called with an empty list', () => {
+  test('resets to the initial handlers if called with an empty list', () => {
     {
       const controller = new InMemoryHandlersController([])
       controller.reset([])
@@ -168,7 +246,7 @@ describe(InMemoryHandlersController.prototype.reset, () => {
     }
   })
 
-  it('replaces the initial handlers if called with a list of handlers', () => {
+  test('replaces the initial handlers if called with a list of handlers', () => {
     const httpOne = http.get('/', () => {})
     const httpTwo = http.get('/', () => {})
     const controller = new InMemoryHandlersController([httpOne])
@@ -177,7 +255,7 @@ describe(InMemoryHandlersController.prototype.reset, () => {
     expect(controller.currentHandlers()).toEqual([httpTwo])
   })
 
-  it('resets the initial handlers after runtime handlers are applied', () => {
+  test('resets the initial handlers after runtime handlers are applied', () => {
     const httpOne = http.get('/', () => {})
     const httpTwo = http.get('/', () => {})
     const controller = new InMemoryHandlersController([])
@@ -195,7 +273,7 @@ describe(InMemoryHandlersController.prototype.reset, () => {
     expect(controller.currentHandlers()).toEqual([httpTwo])
   })
 
-  it('places siblings into their kind buckets when resetting to next handlers', () => {
+  test('places siblings into their kind buckets when resetting to next handlers', () => {
     const controller = new InMemoryHandlersController([])
     const wsHandler = ws.link('*').addEventListener('connection', () => {})
     const [upgradeHandler] = getSiblingHandlers(wsHandler)
@@ -206,7 +284,7 @@ describe(InMemoryHandlersController.prototype.reset, () => {
     expect(controller.getHandlersByKind('request')).toEqual([upgradeHandler])
   })
 
-  it('restores siblings when resetting to the initial handlers', () => {
+  test('restores siblings when resetting to the initial handlers', () => {
     const wsHandler = ws.link('*').addEventListener('connection', () => {})
     const [upgradeHandler] = getSiblingHandlers(wsHandler)
     const controller = new InMemoryHandlersController([wsHandler])
@@ -218,7 +296,7 @@ describe(InMemoryHandlersController.prototype.reset, () => {
     expect(controller.getHandlersByKind('request')).toEqual([upgradeHandler])
   })
 
-  it('dedupes the shared upgrade sibling when reset with multiple handlers from the same link', () => {
+  test('dedupes the shared upgrade sibling when reset with multiple handlers from the same link', () => {
     const chat = ws.link('*')
     const wsOne = chat.addEventListener('connection', () => {})
     const wsTwo = chat.addEventListener('connection', () => {})
@@ -232,17 +310,46 @@ describe(InMemoryHandlersController.prototype.reset, () => {
   })
 })
 
+describe(InMemoryHandlersController.prototype.listHandlers, () => {
+  test('lists explicitly registered handlers, hiding their siblings', () => {
+    const httpHandler = http.get('/', () => {})
+    const wsHandler = ws.link('*').addEventListener('connection', () => {})
+
+    const controller = new InMemoryHandlersController([httpHandler, wsHandler])
+
+    expect(controller.listHandlers()).toEqual([httpHandler, wsHandler])
+  })
+
+  test('hides siblings of runtime handlers', () => {
+    const controller = new InMemoryHandlersController([])
+    const wsHandler = ws.link('*').addEventListener('connection', () => {})
+
+    controller.use([wsHandler])
+
+    expect(controller.listHandlers()).toEqual([wsHandler])
+  })
+
+  test('keeps siblings in "currentHandlers()" so the handler lifecycle reaches them', () => {
+    const wsHandler = ws.link('*').addEventListener('connection', () => {})
+    const [upgradeHandler] = getSiblingHandlers(wsHandler)
+
+    const controller = new InMemoryHandlersController([wsHandler])
+
+    expect(controller.currentHandlers()).toEqual([wsHandler, upgradeHandler])
+  })
+})
+
 describe(InMemoryHandlersController.prototype.getHandlersByKind, () => {
-  it('returns an empty array given an empty controller', () => {
+  test('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', () => {
+  test('returns an empty array given no handlers by the given kind', () => {
     expect(
       new InMemoryHandlersController([
         http.get('/', () => {}),
-        graphql.query('', () => {}),
+        gql.query('', () => {}),
       ]).getHandlersByKind('websocket'),
     ).toEqual([])
 
@@ -252,9 +359,9 @@ describe(InMemoryHandlersController.prototype.getHandlersByKind, () => {
     ).toEqual(getSiblingHandlers(wsHandler))
   })
 
-  it('returns all handlers if they all match', () => {
+  test('returns all handlers if they all match', () => {
     const httpHandler = http.get('/', () => {})
-    const graphqlHandler = graphql.query('', () => {})
+    const graphqlHandler = gql.query('', () => {})
     const wsHandler = ws.link('*').addEventListener('connection', () => {})
 
     expect(
@@ -271,9 +378,9 @@ describe(InMemoryHandlersController.prototype.getHandlersByKind, () => {
     ).toEqual([wsHandler])
   })
 
-  it('returns only the matching handlers', () => {
+  test('returns only the matching handlers', () => {
     const httpHandler = http.get('/', () => {})
-    const graphqlHandler = graphql.query('', () => {})
+    const graphqlHandler = gql.query('', () => {})
     const wsHandler = ws.link('*').addEventListener('connection', () => {})
     const wsHandlerSiblings = getSiblingHandlers(wsHandler)
 
@@ -294,7 +401,7 @@ describe(InMemoryHandlersController.prototype.getHandlersByKind, () => {
     ).toEqual([wsHandler])
   })
 
-  it('preserves the order of returned handlers', () => {
+  test('preserves the order of returned handlers', () => {
     const httpOne = http.get('/', () => {})
     const httpTwo = http.get('/', () => {})
     const httpThree = http.get('/', () => {})
@@ -307,9 +414,9 @@ describe(InMemoryHandlersController.prototype.getHandlersByKind, () => {
       ]).getHandlersByKind('request'),
     ).toEqual([httpOne, httpTwo, httpThree])
 
-    const graphqlOne = graphql.query('', () => {})
-    const graphqlTwo = graphql.query('', () => {})
-    const graphqlThree = graphql.query('', () => {})
+    const graphqlOne = gql.query('', () => {})
+    const graphqlTwo = gql.query('', () => {})
+    const graphqlThree = gql.query('', () => {})
 
     expect(
       new InMemoryHandlersController([