Merge branch 'main' into feat/yet-another-socket-interceptor

Author: kettanaito

README.md

@@ -339,10 +339,11 @@ intereceptor.on('connection', ({ client }) => {
 
 The `connection` event exposes the following arguments:
 
-| Name     | Type                                                      | Description                                                      |
-| -------- | --------------------------------------------------------- | ---------------------------------------------------------------- |
-| `client` | [`WebSocketClientConnection`](#websocketclientconnection) | An object representing a connected WebSocket client instance.    |
-| `server` | [`WebSocketServerConnection`](#websocketserverconnection) | An object representing the original WebSocket server connection. |
+| Name     | Type                                                      | Description                                                                         |
+| -------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `client` | [`WebSocketClientConnection`](#websocketclientconnection) | An object representing a connected WebSocket client instance.                       |
+| `server` | [`WebSocketServerConnection`](#websocketserverconnection) | An object representing the original WebSocket server connection.                    |
+| `info`   | `object`                                                  | Additional WebSocket connection information (like the original client `protocols`). |
 
 ### `WebSocketClientConnection`
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mswjs/interceptors",
   "description": "Low-level HTTP/HTTPS/XHR/fetch request interception library.",
-  "version": "0.29.1",
+  "version": "0.30.0",
   "main": "./lib/node/index.js",
   "module": "./lib/node/index.mjs",
   "types": "./lib/node/index.d.ts",

src/interceptors/WebSocket/WebSocketOverride.ts

@@ -51,7 +51,12 @@ export class WebSocketOverride extends EventTarget implements WebSocket {
     Reflect.set(this, 'readyState', this.CONNECTING)
     queueMicrotask(() => {
       Reflect.set(this, 'readyState', this.OPEN)
-      this.protocol = protocols ? protocols[0] : 'ws'
+      this.protocol =
+        typeof protocols === 'string'
+          ? protocols
+          : Array.isArray(protocols) && protocols.length > 0
+          ? protocols[0]
+          : ''
 
       this.dispatchEvent(bindEvent(this, new Event('open')))
     })

src/interceptors/WebSocket/index.ts

@@ -28,6 +28,16 @@ export type WebSocketConnectionData = {
    * The original WebSocket server connection.
    */
   server: WebSocketServerConnection
+
+  /**
+   * The connection information.
+   */
+  info: {
+    /**
+     * The protocols supported by the WebSocket client.
+     */
+    protocols: string | Array<string> | undefined
+  }
 }
 
 /**
@@ -82,6 +92,9 @@ export class WebSocketInterceptor extends Interceptor<WebSocketEventMap> {
               transport,
               createConnection
             ),
+            info: {
+              protocols,
+            },
           })
         })
 

test/modules/WebSocket/compliance/websocket.connection.test.ts

@@ -57,6 +57,9 @@ it('emits the correct "connection" event on the interceptor', async () => {
         addEventListener: expect.any(Function),
         removeEventListener: expect.any(Function),
       }),
+      info: {
+        protocols: undefined,
+      },
     })
   )
 })
@@ -74,3 +77,22 @@ it('does not connect to the actual WebSocket server by default', async () => {
   expect(connectionListener).toHaveBeenCalledTimes(1)
   expect(realConnectionListener).not.toHaveBeenCalled()
 })
+
+it('includes connection information in the "connection" event payload', async () => {
+  const connectionListener = vi.fn()
+  interceptor.once('connection', connectionListener)
+
+  new WebSocket('wss://example.com', ['protocol1', 'protocol2'])
+  await waitForNextTick()
+
+  expect(connectionListener).toHaveBeenCalledTimes(1)
+  expect(connectionListener).toHaveBeenNthCalledWith(
+    1,
+    expect.objectContaining({
+      info: {
+        // Preserves the client protocols as-is.
+        protocols: ['protocol1', 'protocol2'],
+      },
+    })
+  )
+})

test/modules/WebSocket/compliance/websocket.protocol.test.ts

@@ -0,0 +1,45 @@
+/**
+ * @vitest-environment node-with-websocket
+ * @see https://websockets.spec.whatwg.org/#dom-websocket-close
+ */
+import { it, expect, beforeAll, afterAll } from 'vitest'
+import { WebSocketInterceptor } from '../../../../src/interceptors/WebSocket'
+import { waitForWebSocketEvent } from '../utils/waitForWebSocketEvent'
+
+const interceptor = new WebSocketInterceptor()
+
+beforeAll(() => {
+  interceptor.apply()
+})
+
+afterAll(() => {
+  interceptor.dispose()
+})
+
+it('returns an empty string if no protocol was provided', async () => {
+  const ws = new WebSocket('wss://example.com')
+  expect(ws.protocol).toBe('')
+
+  await waitForWebSocketEvent('open', ws)
+  expect(ws.protocol).toBe('')
+})
+
+it('returns the protocol if a single protocol was provided', async () => {
+  const ws = new WebSocket('wss://example.com', 'chat')
+
+  // The protocol is empty on the first tick.
+  // This is where the client is waiting for the "server"
+  // to report back what protocol was chosen.
+  expect(ws.protocol).toBe('')
+
+  await waitForWebSocketEvent('open', ws)
+  expect(ws.protocol).toBe('chat')
+})
+
+it('returns the first protocol if an array of protocols was provided', async () => {
+  const ws = new WebSocket('wss://example.com', ['superchat', 'chat'])
+  expect(ws.protocol).toBe('')
+
+  await waitForWebSocketEvent('open', ws)
+  expect(ws.protocol).toBe('superchat')
+})