feat!: rewrite package to new network source architecture by christoph-fricke · Pull Request #48 · mswjs/playwright

christoph-fricke · 2026-04-08T14:53:52Z

This PR rewrites @msw/playwright to be based on the new network source architecture released in MSW v2.13.0.

Changes

defineNetworkFrame uses the new defineNetwork API with a PlaywrightSource underneath
The context option has been widened to accept either a BrowserContext or Page
Added a new routePattern option for providing a custom pattern passed to context.route(...).
Added a new websocketPattern options for providing a custom pattern passed to context.routeWebSocket(...).

Todo

All WebSocket related tests are broken after updating MSW to v2.13.2:

  [chromium] › tests/multiple-pages.test.ts:48:1 › intercepts a WebSocket connection on a programmatically created page
  [chromium] › tests/websockets.test.ts:31:1 › sends a text data to the client
  [chromium] › tests/websockets.test.ts:56:1 › sends a buffer data to the client
  [chromium] › tests/websockets.test.ts:84:1 › sends a blob data to the client
  [chromium] › tests/websockets.test.ts:109:1 › closes the client connection
  [chromium] › tests/websockets.test.ts:134:1 › closes the client connection with a custom reason
  [chromium] › tests/websockets.test.ts:162:1 › closes the client connection with a non-configurable code
  [chromium] › tests/websockets.test.ts:190:1 › connects to the actual server

Scafhold PlaywrightSource that extends NetworkSource.
- Accept either BrowserContext or Page as an interception target
Extract reusable parts from the current implementation into utils.
Support for HTTP request interception:
- Implement PlaywrightHttpNetworkFrame extends HttpNetworkFrame.
- Integrate PlaywrightHttpNetworkFrame into PlaywrightSource.
- Adjust HTTP based tests to verify implementation
- Infer and propagate baseUrl for WebSocket frames
Support for WebSocket request interception:
- Implement PlaywrightWebSocketNetworkFrame extends WebSocketNetworkFrame.
- Integrate PlaywrightHttpNetworkFrame into PlaywrightSource.
- Adjust WebSocket based tests to verify implementation
- Infer and propagate baseUrl for WebSocket frames
Replace defineNetworkFixture implementation with defineNetwork wrapper implementation

christoph-fricke · 2026-04-09T19:42:01Z

@kettanaito I am struggling a bit with implementing WebSocket handling, and would like to align on an approach before continuing. I don't have experience with using WebSocket mocking in MSW, which makes this a bit harder as well. So far I thought about three approaches to tackling this.

1. PlaywrightWebSocketNetworkFrame extends WebSocketNetworkFrame

Similar to the PlaywrightHttpNetworkFrame implementation, this seems like the most obvious choice. When constructing an implementation of the frame, it requires a WebSocketClientConnection and WebSocketServerConnection connection. First idea: Let's use the already existing Playwright connection classes that implement the WebSocket(Client|Server)ConnectionProtocol.

const frame = new PlaywrightWebSocketNetworkFrame({ connection: { client: new PlaywrightWebSocketClientConnection(route), server: new PlaywrightWebSocketServerConnection(route), info: { protocols: [] }, }, })

This does not work! It results in type errors for both client and server:

client: Type 'PlaywrightWebSocketClientConnection' is missing the following properties from type 'WebSocketClientConnection': socket, transport, [kEmitter$1]

server: Type 'PlaywrightWebSocketServerConnection' is missing the following properties from type 'WebSocketServerConnection': client, transport, createConnection, mockCloseController, and 7 more.

This also explains the TS errors in the existing fixture after updating MSW when calling webSockerHandler.run(...), and might explain why all WebSocket related tests have been failing.

=> Takeaway: Implementing WebSocket(Client|Server)ConnectionProtocol is not enough. We have to use WebSocket(Client|Server)Connection if we want to extend WebSocketNetworkFrame.

2. Implementing a WebSocketTransport

Since WebSocket(Client|Server)Connection are already usable classes, it might be enough to implement a custom WebSocketTransport, and construct WebSocket(Client|Server)Connection directly with a PlaywrightWebSocketTransport.

My concern with this approach is that this might not work. The two classes appear to be a bit too closely related to an actual WebSocket. Both require a WebSocket instance for construction and do operations with it to some extend. I fear that we cannot provide a reliable WebSocket instance (mock) with the stuff we get from Playwright's WebSocketRoute.

3. Extend a "low-level" NetworkFrame<"ws">

Maybe we do not need to extend WebSocketNetworkFrame. All we have to do is resolve/proxy WebSocket messages using the WebSocketRoute (famous last words...). Maybe the simplest, most robust approach, is a PlaywrightWebSocketNetworkFrame that extends NetworkFrame<"ws"> directly, and uses WebSocketRoute instead of WebSocket(Client|Server)Connection.

I started this third approach in this file. But as you can see, msw/experimental is missing a bunch of exports to be able to directly extend NetworkFrame. So I am wondering if this approach should be avoided at all cost.

What are your thoughts on this? What do you think is the best approach for handling Playwright WebSocket routes with the new network source architecture? Are there missing pieces in MSW to make this feasible?

Your first approach sounds correct. The type mismatch might as well be a bug. WebSocketClientConnectionProtocol type is a general type I created exactly for this reason (so the implementers don't have to worry about transport).

Yeah, it's definitely a bug. In websocket-frame.ts:

export interface WebSocketNetworkFrameOptions { connection: WebSocketConnectionData }

I'm getting the WebSocketConnectionData from the Interceptors as-is, but that's a mistake. That type is a narrower type than what the frame should care about.

We should probably annotate that connection option as WebSocketHandlerConnection from WebSocketHandler.ts, which contains the broader WebSocketClientConnectionProtocol.

Can you open an issue for this in the MSW repo, please? 🙏 I think this is a great find.

See mswjs/msw#2710

christoph-fricke

@kettanaito The rewrite is complete so far. All tests pass (when the "type as value" bug is fixed in MSW or locally) and the new implementation feels quite solid already. I think next good steps are:

We give the implementation a proper review
Clarify open questions and resolve missing MSW parts
~~Remove the old fixture.ts implementation~~
~~Update the README and add some JSDoc comments to the source class and its options.~~

christoph-fricke · 2026-04-15T21:20:56Z

+import type { RequestHandler } from 'msw'
+import type { NetworkFrameResolutionContext } from '../../node_modules/msw/lib/core/experimental/frames/network-frame.mjs'
+import type { UnhandledFrameHandle } from '../../node_modules/msw/lib/core/experimental/on-unhandled-frame.mjs'


❌ MSW should export these types before we merge this.

christoph-fricke · 2026-04-15T21:22:13Z

+import type { WebSocketHandler } from 'msw'
+import type { NetworkFrameResolutionContext } from '../../node_modules/msw/lib/core/experimental/frames/network-frame.mjs'
+import type { UnhandledFrameHandle } from '../../node_modules/msw/lib/core/experimental/on-unhandled-frame.mjs'


❌ MSW should export these types before we merge this.

christoph-fricke · 2026-04-15T21:23:30Z

+  }
+
+  passthrough(): void {
+    this.#route.connectToServer()


💭 Not sure if this approach, or calling this.data.connection.server.connect() is better? The latter registers pending event listeners from the mock. Does it even matter in the cases where passthrough is called?

christoph-fricke · 2026-04-15T21:25:21Z

+  }
+}
+
+class PlaywrightWebSocketClientConnection implements WebSocketClientConnectionProtocol {


💡 PlaywrightWebSocketClientConnection and PlaywrightWebSocketServerConnection are pretty much copied. Only made slight adjustment such as aligning the #route field naming.

christoph-fricke · 2026-04-15T21:31:33Z

+} from './route-utils.js'
+
+export interface PlaywrightSourceOptions {
+  skipAssetRequests?: boolean


💭 With support for custom route patterns, skipAssetRequests might be obsolete.

I added support for custom patterns, because in my experience most mock setups mock API(s) behind one (a few at most) endpoints. Alongside registering multiple PlaywrightSource sources, custom patterns can help reduce the interception overhead for this common case. What do you think about this?

Yes, if we go with the route of mapping handlers to page.route(), then I suppose there's no need in skipAssetRequests anymore. Just need to make sure the tests pass.

christoph-fricke · 2026-04-15T22:00:13Z

-  expect.soft(consoleSpy.callCount).toBe(2)
-  expect(consoleSpy.getCall(1)?.args).toEqual([
+  expect.soft(consoleSpy.callCount).toBe(3)
+  expect(consoleSpy.getCall(2)?.args).toEqual([


💭 The implementation in fixture.ts never tried to resolve Vite's dev-server WebSocket here, because it aborts early when no WebSocket handlers are defined. I let the orchestration happen completely in WebSocketNetworkFrame.resolve(), which leads to the additional warning.

If needed, we could add an early passthrough in PlaywrightWebSocketNetworkFrame to avoid the additional WebSocket warning.

christoph-fricke · 2026-04-15T22:03:43Z

+      connection: {
+        client: new PlaywrightWebSocketClientConnection(options.route),
+        server: new PlaywrightWebSocketServerConnection(options.route),
+        info: { protocols: [] },


❌ Depends on work in mswjs/msw#2710. Currently, this code surfaces a TS error.

Although, it (surprisingly) works at runtime already. At least all tests pass.

socket-security · 2026-05-06T16:46:56Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	msw@2.12.14 ⏵ 2.13.2	⁺¹

View full report

christoph-fricke added 4 commits April 8, 2026 16:48

feat!: update msw peer-dependency to ^2.13.2

f83c8ec

feat: scaffold PlaywrightSource as the new network source

ba95269

feat: add basic PlaywrightHttpNetworkFrame implementation

65d32b3

test: make first tests pass with network source architecture

f9b2c6e

kettanaito reviewed Apr 9, 2026

View reviewed changes

Comment thread src/playwright-source.ts

kettanaito reviewed Apr 9, 2026

View reviewed changes

Comment thread src/playwright-source.ts Outdated

christoph-fricke added 4 commits April 9, 2026 17:39

chore: remove resolved todo comment

dc880cd

test: migrate all tests to network source api

ee93708

refactor: remove override keyword usage

4340e11

feat: add empty websocket frame

e21c712

christoph-fricke commented Apr 9, 2026

View reviewed changes

This was referenced Apr 12, 2026

[experimental] WebSocketNetworkFrame cannot be initialized with WebSocket(Client|Server)ConnectionProtocol implementations mswjs/msw#2707

Open

[experimental] Pass NetworkFrameResolutionContext to NetworkSource.enable() mswjs/msw#2708

Open

christoph-fricke added 12 commits April 12, 2026 18:37

feat: implement websocket frame based on WebSocketNetworkFrame

e1402a1

feat: infer baseUrl from intercepted request

c6cf6ca

feat: accept either Page or BrowserContext

36d598c

feat: infer baseUrl for intercepted WebSocket connections

6ff9100

test: bypass unhandled frames in tests

2e3c505

refactor: rename utils to route-utils

bb06227

refactor: capsulate route handled error workaround in utils

4e2f76f

refactor: unify route handler registration

3238938

chore: organize imports

7da7eee

feat: add support for custom route patterns

a616f61

test: deduplicate internal route registration tests

f087d52

chore: remove open todo comments

d5e06cd

christoph-fricke commented Apr 15, 2026

View reviewed changes

christoph-fricke marked this pull request as ready for review April 15, 2026 22:16

christoph-fricke mentioned this pull request Apr 16, 2026

fix: use verbatimModuleSyntax consistently in exports mswjs/msw#2702

Merged

feat: use network source api in defineNetworkFixture

3f60c5a

christoph-fricke added 2 commits May 6, 2026 18:48

refactor: remove quit override from network frames

d5f6804

refactor: always provide inferred base url to frame resolution

a1ba6c3

christoph-fricke requested a review from kettanaito May 6, 2026 17:10

Uh oh!

Conversation

christoph-fricke commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Todo

Uh oh!

Uh oh!

Uh oh!

christoph-fricke Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

1. PlaywrightWebSocketNetworkFrame extends WebSocketNetworkFrame

2. Implementing a WebSocketTransport

3. Extend a "low-level" NetworkFrame<"ws">

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

christoph-fricke left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

christoph-fricke Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

socket-security Bot commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

christoph-fricke commented Apr 8, 2026 •

edited

Loading

christoph-fricke Apr 9, 2026 •

edited

Loading

1. `PlaywrightWebSocketNetworkFrame extends WebSocketNetworkFrame`

2. Implementing a `WebSocketTransport`

3. Extend a "low-level" `NetworkFrame<"ws">`

christoph-fricke left a comment •

edited

Loading

christoph-fricke Apr 15, 2026 •

edited

Loading

socket-security Bot commented May 6, 2026 •

edited

Loading