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.

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.

[kettanaito]

Thank you for your kind words ❤️ I needed to hear that.

[ernestostifano]

Hello guys! Thanks for your work. Any idea if this would work with @mswjs/http-middleware out-of-the-box? (@kettanaito)

[kettanaito]

Hi, @ernestostifano 👋 That's a good question. No, I think we need to create an integration for that. Looks like a matter of pulling in ws and resolving the messages using MSW's event handlers.

Opened an issue for that mswjs/http-middleware#46.

[kettanaito]

There's no server.on() anymore.

[itsdouges]

Hi folks 👋 - I'm looking into this to try using it in Jest + node but I haven't been able to get it working (I never get an open event in the WebSocket instance). Is there any canonical example that's up-to-date where I can find it working?

[kettanaito]

Hi! All the tests we have on this feature branch are canonical and functional. You can also check out the example repository for reference.

The key point is to create a custom Jest environment since Node.js doesn't expose the WebSocket class globally yet. See those examples to see how we do that.

[itsdouges]

Thanks, will give it a go and report back.

[kettanaito]

Hi, @alessbell. Take a look at the docs, the event handlers you define go straight to the handlers array. We maintain that architecture because there must be a single place to describe your network.

const handlers = [...httpHandlers, ...webSocketHandlers]

WebSocket handlers also support all the other experiences around mocking HTTP—handler order, fallthrough, overrides, etc.

Please let me know if you have any other questions or points of feedback! Would love to learn more from you and the team. Thanks.

[alessbell]

Wow, I don't know how I missed that 😅

Appreciate the reply @kettanaito - I'll be adding support for GraphQL subscriptions over in https://github.com/apollographql/graphql-testing-library this week so I'm excited to be able to use this. Thank you 🙏

[kettanaito]

Let's go!! 🚀

[hajnyon]

This behavior is expected and documented https://website-git-docs-ws-mswjs.vercel.app/docs/basics/handling-websocket-events#logging

[nemonemi]

You are totally correct, here. Thanks for the hint!

[kettanaito]

Hi. Yes, this will be a technical limitation due to Service Workers not designed for intercepting WebSocket connections. You do see the same logs in the console though. We need to design a proper logging levels here but I doubt I have the capacity to squeeze it into the WebSocket release.

[davidgoli]

Hello! I think I'm missing something here. I have a Node.js server that is a sort of coordination layer - it is both a websocket server (for browser clients) and a websocket client (streaming with 3rd party services). So I've been able to use @mswjs/interceptors/WebSocket successfully for my browser client code, but not for my Node.js client code.

Until now, I've been using the excellent and widely adopted ws package which is close to but not quite standards-compliant, so I've been trying out undici as an alternative just so I can use msw's WebSocket capabilities. However, that doesn't appear to be working, either. Test case:

import { WebSocket } from 'undici'
import { ws } from 'msw'

const url = 'ws://localhost/stream'
const mockServer = ws.link(url)

it('connects', (done) => {
  mockServer.on('connection', () => done())

  new WebSocket(url)
})

Result: test timeout (Exceeded timeout of 5000 ms for a test while waiting for `done()` to be called.)
Expected: test success

Am I missing something here? Note that node --experimental-websocket is probably off the table; we've been bitten by experimental Node.js flags in the past. Thanks!

[davidgoli]

In either case, both the ws API and the WebSocketInterceptor only work on a global WebSocket class

this is awesome to hear! Could also be something to mention in the docs, since I couldn't find anything about that. But I'm stoked that ws support is available, when I have the time to circle back I'll try it out.

[davidgoli]

Ok, I've started integrating this, and setting globalThis.WebSocket totally gets the goods! However, now I'm intercepting the Upgrade request:

    [MSW] Warning: intercepted a request without a matching request handler:
    
      • GET https://...

is this expected? should I be handling the connection upgrade, or should I expect ws.link to handle this for me?

[kettanaito]

Just offering feedback on my experience as a multi-year user of msw, feel free to take it or leave it!

Grateful for your feedback! The docs are your best guide. Interceptors is not something most people use. MSW uses them for you, providing a higher-level interface to work with the network. I understand those two might've caused the confusion.

Could also be something to mention in the docs, since I couldn't find anything about that.

Agreed. We need to add it to the docs so this is really clear 👍

should I be handling the connection upgrade, or should I expect ws.link to handle this for me?

I'm trying to remember what was the intention... Do you have a reproduction repo to share when this is happening, please?

I want to say yes, it should handle the upgrade events, but I suppose that needs more work on the interceptor's side. To make things a bit more tangled, the connection upgrade is an HTTP request, and those are handled differently in the browser (using Service Worker) and in Node.js (using Interceptors).

We can account for that difference on MSW's level, by making ws.link() produce multiple handlers:

• One fixed http.* handler for the connection upgrade;
• Additional multiple event handlers whenever you do link.on('connection').

The only blocker I see here is that handlers list is flat, and multiple handlers would have to be spread in setupWorker/setupServer in order to work. That's not an experience I'd recommend using. This definitely needs more thought.

[davidgoli]

Here's a minimal repro:

import { WebSocket } from 'ws'
import { ws } from 'msw'
import { setupServer } from 'msw/node'

const url = 'ws://localhost/stream'
const wsMock = ws.link(url)

const server = setupServer()

beforeAll(() => {
  server.listen()
})

afterAll(() => {
  server.close()
})

it('connects', (done) => {
  server.use(
    wsMock.on('connection', () => {
      console.log('got mock connection')
      done()
    }),
  )

  new WebSocket(url)
})

[kettanaito]

@davidgoli, MSW works with the global WebSocket class only. Expose that WebSocket class from ws as a global, and you will get the interception working. Or even better—use Undici or the latest Node.js to get the global WebSocket class for free.

[kettanaito]

Proposal: Connection-wide message encoding/decoding

The way we support custom WebSocket clients like SocketIO is through the concept of a binding. Binding applies itself on the connection object (the argument to the connection event listener), and encodes/decodes the messages you receive/send in your mock.

I propose we moved that logic up to the ws.link() itself.

const api = ws.link('wss://example.com', {
  encode: (messageEvent) => {},
  decode: (messageEvent) => {}
})

My reasoning is this:

• The entire WebSocket server is likely using the same messaging mechanism. It's not like the same URL will yield you messages with different encoding format.

The interceptor will know when to apply the encode() and decode() methods to properly handle the outgoing/incoming messages.

The bindings usage would then look like this:

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

const api = ws.link('wss://example.com', {
  encode: binding.encode,
  decode: binding.decode,
})

Just need to check if bindings are designed to do more than message encoding.

[kettanaito]

Likely not going to do that during this iteration. A feature to consider.

[kettanaito]

Hi, @KaisaSiSD. Thanks for sharing this!

Runtime overrides for WebSocket connections are meant to work on the event basis. Here's what it means:

const api = ws.link('ws://localhost')

const worker = setupWorker(
  api.on('connection', ({ client }) => {
    client.addEventListener("message", (event) => {
      console.log('do base stuff')
    })
  })
)

// Someplace later in tests.
worker.use(
  api.on('connection', ({ client }) => {
    client.addEventListener('message', (event) => {
      event.stopPropagation()
      console.log('do different stuff')
    })
  })
)

By calling event.stopPropagation() in the override handler, you stop that event from being emitted anywhere else. You can also use event.stopImmediatePropagation() to prevent the event across the sibling client.addEventListener('message') targets (similar to how you would do with an event dispatched in DOM).

So the intention is for you to override handling of specific events, not the entire connection listeners. There is no state of a connection for it to be considered "handled", but there is such state for individual client and server events (through the event reference).

Let me know if this helps. Also, I think this isn't mentioned in the docs, right? Might be something to improve.

[KaisaSiSD]

Yes this exactly helped me! I didn't quite know what I didn't understand so figuring things out was quite challenging. Clearly I was trying to do something I was not supposed to do. I'm still studying development so there is a lot to learn and sometimes it feels like I already know something, but actually I know only parts of it.

I had to use the preventDefault, as my problem was mainly that when running tests I would like to run them so that nothing bothers the actual server and create mocked satatic responses with fake data. Adding the stopImmediatePropagation also lets me make sure nothing unnecessary is run during the test from the initial handler.
While developing I want to pass stuff through. I already had established connection to the server with the other version of the handler which I set when I create the worker, so when I tried to overwrite the handler with worker.use() it did not prevent things from being forwarded to the actual server.

I think I had firstly misunderstood how worker.use() works, so I guess I wasn't straight away able to figure out what was supposed to happen. I think my hunch was that the 'connection' eventListener would have fired only once, so the overridden one that contains server.connect() would not have run. Then I had not quite understood, over all, the event propagation and default prevention in this context.

I think it would be helpful to make a section about the usage of worker.use and these eventListeners to the documentation.

Thank you for a quick and insightful answer!

[kettanaito]

Glad it helped!

Runtime handlers (.use()) are generally accumulative. They are prepended to the list of all handlers MSW considers at a given point in time. In HTTP case, there's a clear state of "this request has been handled"—it's when you either respond to it or error it. For WebSockets, there's no state like "this connection is handled". So when you have multiple "connection" listeners, they will all execute in order, with runtime ones taking precedence.

You achieve exclusion and composition of events through the event: Event interface of events like message or close, on both client and server objects that the connection listener gives you.

This is a must read: https://website-git-docs-ws-mswjs.vercel.app/docs/basics/handling-websocket-events#important-defaults

[catz]

Hello!

Maybe someone has an idea or an example of how to use the msw library to mock websocket connections that are inside web worker ?
I have full access to the worker script.

Maybe it's worth considering changing the code so that in case of tests the logic is in the main thread? In this case standard interceptor might work.

tia

[kettanaito]

Since MSW is a third-party library, you'd have to bundle your web worker to enable it there. Alternatively, cross-process interception may work (#1617) but it's in early development.

In that regard, it's no different than including any other third-party package in a web worker. You can research how to do that online. Once you have msw in your worker, you can describe the WebSocket behaviors you need. Note that it will only affect WebSocket connections initiated by the worker, not the main page. If you need it on the main page, enable MSW there instead.