WebSocket Support Beta

[kettanaito]

Hi! Thanks for finding time to share your feedback on the WebSocket support in MSW!

Goals

The main goal behind this RFC is to gather feedback on the WebSocket interception API in MSW and give the beta release a try once it's out.

Before you begin

Important

MSW will only support mocking WebSocket connections implemented via the WHATWG WebSocket API. We are committed to the standard-driven API mocking, and that includes WebSockets! The WebSocket API is globally available in the browser, and it's also coming to Node.js this year (already available as an experimental WebSocket API in undici).

• Get up-to-date with the issue: Support mocking WebSocket APIs #156
• The implementation: feat: support mocking WebSocket APIs #2011

Getting started

Install the msw@next package to get the work-in-progress ws API:

npm i msw@next

• 👉 Documentation: Handling WebSocket events
• Documentation: ws API

General statements

• Outgoing client events are not forwarded to the server by default. Client-to-server event forwarding is opt-in via server.connect().
• Incoming actual server events are forwarded to the client by default. Server-to-client event forwarding is opt-out via event.preventDefault() in the relevant server event listener.

MSW API

In the context of MSW, I propose the following API to intercept WebSocket connections:

const api = ws.url('wss://chat.service.com')

api.on('connection', ({ client }) => {
  client.on('message', (event) => {
    console.log(event.data)
    client.send('Hello from server!')
  })
})

1. The only way to intercept a WebSocket connection is to call the ws.url() method and provide it a valid WebSocket connection URL (using with the ws:/wss: scheme).
2. The result of calling the ws.url() method will be an EventTarget-like object that allows you to subscribe to a single "connection" event. This mirrors the WebSocketInterceptor public API.
3. In the "connection" event listener, you can access the client and the server connection representations.
   • The client lets you intercept outgoing client events (client.on(event, listener)) and mock incoming server events (client.send(data)).
   • The server lets you establish the actual server connection (server.connect()), intercept incoming server events (server.on(event, listener)), and mock outgoing client events (server.send()).

Below, see some of the use cases for the WebSocket interception.

Developing mock-first

const api = ws.url('wss://does-not-exist-yet.com')

api.on('connection', ({ client }) => {
  client.send('hello from server!')

  client.on('message', (event) => {
    if (event.data === 'outgoing') {
      // Send text.
      client.send('reply to outgoing')

      // Send binary.
      client.send(new Blob(['hello'])
      client.send(new TextEncoder().encode('hello'))
    }
  })
})

const ws = new WebSocket('wss://does-not-exist-yet.com')
ws.onopen = () => {
  ws.send('outgoing')
}
ws.onmessage = (event) => {
  console.log(event.data)
  // "hello from server!"
  // later, "reply to outgoing"
}

Event patching

This is an example of combining the actual WebSocket connection and the mock to intercept the duplex communication and mock it bothways.

const api = ws.url('wss://example.com')

api.on('connection', ({ client, server }) => {
  // You MUST establish the actual server connection
  // before you can receive or send server events.
  server.connect()

  // Forward all outgoing client events to the actual server.
  client.on('message', (event) => server.send(event.data))

  client.on('message', (event) => {
    client.send('got it!')
  })

  // Introspect incoming server events.
  server.on('message', (event) => {
    console.log(event.data)
  })

  // Prevent server-to-client event forwarding.
  server.on('message', (event) => {
    if (event.data === 'some-server-event') {
      // Preventing default on the incoming server event
      // prevents server-to-client event forwarding.
      event.preventDefault()
      // This way, you can handle an incoming actual event
      // by sending a mocked event to the client.
      client.send('mocked-server-event')
      return
    }
  })
})

Closing the connection

api.on('connection', ({ client }) => {
  // Graceful close (1000).
  client.close()

  // Close using a non-configurable status code.
  client.close(1003, 'reason')
})

Since the connection listener, just like the HTTP request handlers, is written from the server's perspective, you can use otherwise non-configurable status codes (see RFC6455) to close the client connection. This allows you to mock various server close scenarios.

Usage with Socket.IO

Since Socket.IO supports the websocket transport, you can intercept and mock Socket.IO connections. However, since Socket.IO introduces a custom protocol to encode and decode messages, you will receive the raw encoded messages if you observe the traffic using the interceptor:

api.on('connection', ({ client }) => {
  client.on('message', (event) => {
    console.log(event.data)
    // 40 - internal OPEN event
    // 42["message","hello world"] - outgoing message event
  })
})

const client = io('ws://example.com')
client.send('hello world')

Operating with Socket.IO connections on the raw WebSocket level requires you to understand its protocol, which is not something you should know in order to use Socket.IO. With that in mind, I'm proposing to introduce a concept of bindings.

Here's an example of a Socket.IO binding that converts the raw WebSocket connections into a more familiar Socket.IO-like connection:

import { bind } from '@mswjs/socket.io-binding'

api.on('connection', (connection) => {
  const io = bind(connection)
  io.on('message', (event, data) => {
    console.log(data) // "hello!"
  })
  io.on('hello', (event, data) => {
    console.log(data) // "hello!"
  })
})

const client = io('wss://example.com')
client.send('hello!')

Socket.IO binding only ever concerns itself with encoding and decoding data messages (42 and 451). You are still expected to forward the raw data to the original server if you wish to establish an actual WebSocket connection.

Questions

• ws.url or ws.link? I'd like to have consistency with graphql.link so one of them should be renamed.
  • Going with ws.link() for consistency.
• Where should WebSocket network description be declared? The ws "event handlers" are self-contained, meaning that they don't follow the usual request resolution pipeline (request -> handlers list -> response). But I still wish for WebSocket logic to be placed alongside the rest of your handlers.
  • WebSocket handlers must be declared alongside the rest of your handlers.
• Runtime event handlers (.use()). How should these work? Once again, the ws API is self-contained. It will dispatch the "connection" event to all ws interceptors but there's no conventional event propagation here to stop to support a fallthrough behavior akin to request handlers.
  • Runtime handlers for WebSocket work the same way as they do for HTTP handlers.
  • The difference is that fallthrough can be opt-out not via return but via event.stopImmediatePropagation(). This supports opting-out even from individual client/server events as those share the same event instance across multiple listeners and even WebSocket event handlers.

[kettanaito]

Allow preventing connection-level actions

Right now, if a handler has some action on the connection event, like greeting any connected client, it's impossible to opt-out from that behavior completely:

api.on('connection', ({ client }) => client.send('hello'))

server.use(
  api.on('connection', ({ client }) => ???)
)

No matter what you do in the override handler, the connected client will always receive "hello". The connection event instance is not exposed (and doesn't really exist afaik in the Interceptors), so you cannot event.stopImmediatePropagation() to opt out from any following listeners. This will be the easiest way to support this.

api.on('connection', (event) => {
  event.client.send('hello')
})

server.use(
  api.on('connection', (event) => {
    event.stopImmediatePropagation()
    event.client.send('howdy')
  })
)

This likely means a medium/large refactoring in the Interceptors to rework the connection events.

Downsides:

1. It's hard to keep the connection event listener arguments ergonomic. I dislike exposing a single event that is both an Event instance but also an object with a bunch of custom properties, like client, server, params, etc.
2. High cost of refactoring.

[kettanaito]

On the topic of keeping the set of connected clients in the browser, I think the best approach is to introduce something called a remote connection class.

class RemoteWebSocketClientConnection implements WebSocketClientConnection {}

The idea behind this class is to provide a 1-1 API with the regular client argument you get in the connection event listener but implement its methods (.send(), .addEventListener()) via the BroadcastChannel instructions. Those instructions will post messages to the channel, letting the relevant client (by its ID) know what to do, even if it lives in a different runtime (e.g. another open tab).

So api.clients will be a set of those "remote" connection instances. This way the developer gets consistent experience while we manage all the internal doings of this behind the scenes.

I imagine this to be browser-specific. In Node.js, your app/tests usually share the runtime so all connections will be stored as-is (no need for the remote interface). But Node.js supports BroadcastChannel as well, so perhaps reusing a single implementation can be beneficial.

[kettanaito]

This has been implemented using the .broadcast() and .broadcastExcept() methods on the event handler object.

[kettanaito]

Routing events through Service Worker

All data sent by WebSocket is transferable: string, blob, arraybuffer. We can route the connection through the Service Worker. Here's why we should consider doing so:

1. Service Worker can act as a shared state across tabs. This way, we can keep the set of all connected clients and expose it correctly in the browser as api.clients (right now impossible since each tab spawns its own runtime and no data structure will persist across runtimes).
2. Service Worker can implement the broadcasting (we are using BroadcastChannel right now).

There are some minor downsides to this too. Mainly, the browser and Node.js handling of WebSocket events will be different internally. This doesn't affect the developer's experience in a negative way. If anything, it may improve DX by providing a consistent clients set.

In Node.js, broadcasting is possible within the same process but multi-client scenarios are generally harder to reproduce on the developer's end. In-memory set should work nicely.

[kettanaito]

For now, I think we will use BroadcastChannel. This is mainly for simplicity. The messaging interface of the BC is similar to that of a Service Worker, so if we decide to migrate to SW, it shouldn't be a large internal change.

I'm a bit concerned with keeping the set of connected clients in the worker due to caching issues. Those are unlikely but there's always a chance of something getting out of sync, and we try to store as little persistent data in the worker as possible to prevent such situations.

Not to mention that client-to-worker communication is always 3-steps-based: client -> worker -> reply. Whereas using BroadcastChannel is 2 steps: client -> other client. This can be a bit snappier in terms of updates.

[kettanaito]

Implemented in mswjs/interceptors#528.

[kettanaito]

I've added the tests for setupServer and setupWorker to ensure the interceptor is not applied until server.listen()/worker.start() are called.

This is not optimal though. Applying the interceptor will patch the WebSocket class even if there's no ws.link() defined by the user.

[kettanaito]

Added failing tests for this in a4cd20cea19acf93f5ee8f922bca2e6487dd138e. Won't address it now because logging affects handleWebSocketEvents call signature and I'd rather not resolve conflicts and merge logging first.

[kettanaito]

Won't fix

I see no reason to change the current behavior. If you call setupServer(), you get the http module patched regardless if you've defined any handlers or not. Granted, it's different in the browser but not because of MSW but rather due to the worker. Since WebSocket connections don't go through the worker, we shouldn't be designing a custom interceptor application logic for that case alone.

[kettanaito]

Fixing in 372f183.

[Narretz]

Hi @kettanaito I was looking at and looking forward to the websocket support. Is it possible to clarify what is meant with "MSW will only support mocking WebSocket connections implemented via the WHATWG WebSocket API"?

How can I find out if what is running via websocket is supported by MSW? Specifically, I'm trying to get it to work with https://github.com/enisdenjo/graphql-ws/, but on('connection', ...) doesn't work. Looks like it's never called., i.e. MSW doesn't intercept the connection.

Would be cool to have a bit more info about this. And possibly a debug mode where MSW intercepts all Websocket connections and shows if it can work with them? Idk if this is even possible, just a thought.

[kettanaito]

It's connecting to the WebSocket server by the URL you have provided when creating a client:

https://github.com/mswjs/examples/compare/with-graphql-ws...Narretz:examples:graphql-ws?expand=1#diff-8eff4f915a14fa354ca2efa50710f444761e19e289fdcbc35534b66f5025e4bfR4

WebSocket connections are opened immediately as you construct a WebSocket instance. There's no way to defer them. That is why the connection is opened as soon as you call createClient() from graphql-ws. Because of that, MSW has to be imported first, before that call happens. If you want to intercept that connection, of course.

Please follow the example I posted closely, which intercepts all connections by graphql-ws. The crucial part is the import order, which you've already discovered.

For example, here's the mistake that prevents MSW from intercepting your connection:

https://github.com/mswjs/examples/compare/with-graphql-ws...Narretz:examples:graphql-ws?expand=1#diff-21d6ffea4ee8352ae5e6bddbeeed0b7ffc09695a8f06cb3661b0222d65740628R8-R9

Swap these two imports:

-import './client.ts'
import './mocks/browser.ts'
+import './client.ts'

This will start MSW, allowing it to spy on the WebSocket instances, and the connection created in ./client.ts will be correctly intercepted.

[Narretz]

I understand what you're saying, but it's not what I'm seeing in practice. createClient() is lazy by default (I got that part wrong initially), so it doesn't create a connection to the server / an instance of WebSocket. This happens when you call subscribe(). createClient() does however immediately store the WebSocket implementation it will use in a variable. That means when msw patches WebSocket with a proxied version in the WebSocketClientConnection interceptor afterwards, it's too late. I guess I should have looked at the code immediately, then it would have been obvious.

The docs should definitely mention that intercepting WebSocket works by patching the WebSocket class. It's not just an implementation detail, it's necessary to know about for some cases. I previously thought msw had some special sauce that made it work without patching.

While I don't like adding logic for testing tools in my app code, it's relatively simple (and tool agnostic) to make graphql-ws use the patched version of WebSocket like this:

class LazyWebSocket {
  static CLOSED = globalThis.WebSocket.CLOSED
  static CLOSING = globalThis.WebSocket.CLOSING
  static CONNECTING = globalThis.WebSocket.CONNECTING
  static OPEN = globalThis.WebSocket.OPEN

  constructor(...args) {
    console.log('lazy', globalThis.WebSocket)

    return new globalThis.WebSocket(...args)
  }
}

export const client = createClient({
  url: 'ws://localhost:5173/graphql',
  webSocketImpl: LazyWebSocket,
})

[kettanaito]

That means when msw patches WebSocket with a proxied version in the WebSocketClientConnection interceptor afterwards, it's too late.

This is a great find! It doesn't affect the need to have a proper import order (which is also the case when using MSW for HTTP you just don't notice that since you put it in the setup phase of your test runner). But this will help me explain why you need this better. Thanks.

The docs should definitely mention that intercepting WebSocket works by patching the WebSocket class.

Fully agree. There are multiple reasons to mention this:

• It's a bit against MSW's principles but there's only as much we can do without a standard API to intercept WebSocket connections;
• Developers should consider that if they provide custom WebSocket implementations to clients like graphql-ws. I'm tempted to say they shouldn't do that in general but we need to mention that won't be supported by MSW.

I previously thought msw had some special sauce that made it work without patching.

No, not the WebSocket interception, sadly. On the bright side, since both the browser and Node.js implement the same WHATWG spec, we still get consistent behavior across environments.

While I don't like adding logic for testing tools in my app code, it's relatively simple (and tool agnostic) to make graphql-ws use the patched version of WebSocket like this:

Why not:

createClient({
  webSocketImpl: () => globalThis.WebSocket
})

Given createClient accepts this.

[Narretz]

Good to hear there's going to be more stuff about the internals into the docs!

Why not:

createClient({
  webSocketImpl: () => globalThis.WebSocket
})

Given createClient accepts this.

createClient is badly typed here - it validates webSocketImpl to have a constructor and these 4 properties.

[andreev-artem]

@kettanaito got a similar issue - it looked to me like on('connection', ...) handler is not called. The root cause was StrictMode - on the second initialization I was getting the following info message [websocket:on] cannot listen to events, already disposed!

[kettanaito]

Add logging

Would be great to add logging for outgoing and incoming events like what we have for HTTP requests. Twice as useful given the interception takes away the observability in the Network tab.

[RayOei]

Hi @kettanaito Can you add a Jest (yes, I know you are not a fan :-) ) example as well? I am wondering how you envision the handling of events within a specific jest test or group of tests.

[kettanaito]

I won't be adding Jest as of now because it has nothing specific to WebSockets.

Take a look at the application where I'm testing WebSockets right now:
https://github.com/kettanaito/tug-o-war/blob/7947b368b14554f05a843718c0ffc6528df374c1/app/components/tug-o-war.test.tsx#L12-L14

Jest workflow will be quite the same. The only prerequisite is exposing the WebSocket constructor globally as it's not a part of Node.js globals yet. I do that using a custom environment and that will be the recommendation for integration level testing with WebSockets.

[maurice]

Hi @kettanaito, I recently starting using MSW's existing HTTP and new WS (@mswjs/interceptors/WebSocket) APIs and have had a lot of success with in-browser-process mocks. I'm using this for daily development and Playwright tests, and I'm boosting MSW to anyone that'll listen :)

+1 for logging WS traffic - I already implemented it myself in my app, because I wanted the visibility.

I'd like to try to write an integration test though, eg, Vitest + @testing-library/react + Node so I was curious to see what you'd done here. But I get 404s for the links above 😢

Specifically I'm wondering if I need an in-Node-process HTTP/WS server that I can use to proxy my mocks, or can I do something simpler, ie, patch the WebSocket locally?

[kettanaito]

@maurice, thanks for trying out the WebSocket mocking! Take a look at this WebSocket mocking+testing example that features both integration tests with Vitest + RTL, as well as end-to-end tests with Playwright.

Specifically I'm wondering if I need an in-Node-process HTTP/WS server that I can use to proxy my mocks, or can I do something simpler, ie, patch the WebSocket locally?

You don't need a WebSocket server to use MSW. In fact, you can use it without any server, developing entirely mock-first, or integrate it to sit between the actual client-server communication. Both are possible and are your choice.

[kettanaito]

Unhandled connections

With the introduction of a new protocol to MSW, I consider adding different protocol-based options to the setupServer/setupWorker calls.

server.listen({
  http: {
    onUnhandledRequest({ request, print }) {}
  },
  ws: {
    onUnhandledConnection({ client, print }) {}
  }
})

This can help greatly to decouple the configurations for different protocols, such as mocking, debugging, handling of unhandled requests/connections.

[kettanaito]

Implementation in mswjs/interceptors#545.