feat(webkit): support connectOverCDP(transport) for direct WVPage attach (#41038)

pavelfeldman · web-flow · commit f14741d73b34 · 2026-05-28T16:29:06.000-07:00
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -106,7 +106,7 @@
     "@types/react-dom": "^19.2.1",
     "@types/retry": "^0.12.5",
     "@types/source-map-support": "^0.5.4",
-    "@types/ws": "8.2.2",
+    "@types/ws": "8.18.1",
     "@types/xml2js": "^0.4.9",
     "@types/yazl": "^2.4.2",
     "@typescript-eslint/eslint-plugin": "^8.59.0",
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
@@ -15384,10 +15384,6 @@ export interface BrowserType<Unused = {}> {
    * @param options
    */
   connectOverCDP(endpointURL: string, options?: ConnectOverCDPOptions): Promise<Browser>;
-  /**
-   * Option `wsEndpoint` is deprecated. Instead use `endpointURL`.
-   * @deprecated
-   */
   /**
    * This method attaches Playwright to an existing browser instance using the Chrome DevTools Protocol.
    *
@@ -15413,7 +15409,11 @@ export interface BrowserType<Unused = {}> {
    * `ws://127.0.0.1:9222/devtools/browser/387adf4c-243f-4051-a181-46798f4a46f4`.
    * @param options
    */
-  connectOverCDP(options: ConnectOverCDPOptions & { wsEndpoint?: string }): Promise<Browser>;
+  connectOverCDP(transport: ConnectOverCDPTransport, options?: ConnectOverCDPOptions): Promise<Browser>;
+  /**
+   * Option `wsEndpoint` is deprecated. Instead use `endpointURL`.
+   * @deprecated
+   */
   /**
    * This method attaches Playwright to an existing browser instance using the Chrome DevTools Protocol.
    *
@@ -15439,7 +15439,7 @@ export interface BrowserType<Unused = {}> {
    * `ws://127.0.0.1:9222/devtools/browser/387adf4c-243f-4051-a181-46798f4a46f4`.
    * @param options
    */
-  connectOverCDP(transport: ConnectionTransport, options?: ConnectOverCDPOptions): Promise<Browser>;
+  connectOverCDP(options: ConnectOverCDPOptions & { wsEndpoint?: string }): Promise<Browser>;
 
   /**
    * This method attaches Playwright to an existing browser instance created via `BrowserType.launchServer` in Node.js.
@@ -16221,7 +16221,8 @@ export interface BrowserType<Unused = {}> {
   name(): string;
 }
 
-export interface ConnectionTransport {
+export interface ConnectOverCDPTransport {
+  open?(): void;
   send(message: object): void;
   close(): void;
   onmessage?: (message: object) => void;
diff --git a/packages/playwright-core/src/client/browserType.ts b/packages/playwright-core/src/client/browserType.ts
@@ -138,10 +138,10 @@ export class BrowserType extends ChannelOwner<channels.BrowserTypeChannel> imple
 
   async connectOverCDP(options: api.ConnectOverCDPOptions  & { wsEndpoint?: string }): Promise<api.Browser>;
   async connectOverCDP(endpointURL: string, options?: api.ConnectOverCDPOptions): Promise<api.Browser>;
-  async connectOverCDP(transport: api.ConnectionTransport, options?: api.ConnectOverCDPOptions): Promise<api.Browser>;
-  async connectOverCDP(overloaded: (api.ConnectOverCDPOptions & { wsEndpoint?: string }) | string | api.ConnectionTransport, options?: api.ConnectOverCDPOptions): Promise<Browser> {
+  async connectOverCDP(transport: api.ConnectOverCDPTransport, options?: api.ConnectOverCDPOptions): Promise<api.Browser>;
+  async connectOverCDP(overloaded: (api.ConnectOverCDPOptions & { wsEndpoint?: string }) | string | api.ConnectOverCDPTransport, options?: api.ConnectOverCDPOptions): Promise<Browser> {
     let endpointURL: string | undefined;
-    let transport: api.ConnectionTransport | undefined;
+    let transport: api.ConnectOverCDPTransport | undefined;
     let params: api.ConnectOverCDPOptions;
     if (typeof overloaded === 'string') {
       endpointURL = overloaded;
@@ -193,6 +193,6 @@ export class BrowserType extends ChannelOwner<channels.BrowserTypeChannel> imple
   }
 }
 
-function isConnectionTransport(value: any): value is api.ConnectionTransport {
+function isConnectionTransport(value: any): value is api.ConnectOverCDPTransport {
   return !!value && typeof value === 'object' && typeof value.send === 'function' && typeof value.close === 'function';
 }
diff --git a/packages/playwright-core/src/server/webkit/DEPS.list b/packages/playwright-core/src/server/webkit/DEPS.list
@@ -5,6 +5,7 @@
 ../registry/
 node_modules/jpeg-js
 node_modules/pngjs
+node_modules/ws
 
 [webkit.ts]
 ./webview/wvBrowser.ts
diff --git a/packages/playwright-core/src/server/webkit/webkit.ts b/packages/playwright-core/src/server/webkit/webkit.ts
@@ -42,7 +42,7 @@ export class WebKit extends BrowserType {
   }
 
   override async connectOverCDP(progress: Progress, params: channels.BrowserTypeConnectOverCDPParams): Promise<Browser> {
-    return connectOverRDP(progress, this, params.endpointURL!, params);
+    return connectOverRDP(progress, this, params);
   }
 
   override amendEnvironment(env: NodeJS.ProcessEnv, userDataDir: string, isPersistent: boolean, options: types.LaunchOptions): NodeJS.ProcessEnv {
diff --git a/packages/playwright-core/src/server/webkit/webview/wvBrowser.ts b/packages/playwright-core/src/server/webkit/webview/wvBrowser.ts
@@ -18,12 +18,14 @@
 import os from 'os';
 import path from 'path';
 
+import ws from 'ws';
 import { debugLogger, RecentLogsCollector } from '@utils/debugLogger';
 import { removeFolders } from '@utils/fileUtils';
+import { httpHappyEyeballsAgent, httpsHappyEyeballsAgent } from '@utils/happyEyeballs';
 import { headersArrayToObject } from '@isomorphic/headers';
 import { Browser } from '../../browser';
 import { helper } from '../../helper';
-import { WebSocketTransport } from '../../transport';
+import { perMessageDeflate } from '../../transport';
 import { getUserAgent } from '../../userAgent';
 import { BrowserContext } from '../../browserContext';
 import { DialogBridge } from './dialogBridge';
@@ -33,9 +35,11 @@ import { WVPage } from './wvPage';
 import type { BrowserOptions, BrowserProcess } from '../../browser';
 import type { SdkObject } from '../../instrumentation';
 import type { InitScript, Page } from '../../page';
+import type { ProtocolRequest, ProtocolResponse } from '../../transport';
 import type * as types from '../../types';
 import type * as channels from '@protocol/channels';
 import type { Progress } from '../../progress';
+import type { ConnectOverCDPTransport } from '../../../../types/types.d.ts';
 
 type ProxyTab = {
   url: string;
@@ -64,26 +68,82 @@ async function listTabs(proxyBase: string, headers: { [key: string]: string }):
   return data.filter(t => !!t.webSocketDebuggerUrl);
 }
 
-export async function connectOverRDP(progress: Progress, parent: SdkObject, endpointURL: string, options: { slowMo?: number, headers?: types.HeadersArray, isLocal?: boolean, noDefaults?: boolean, artifactsDir?: string }): Promise<Browser> {
+// Local WebSocket-backed transport: defers opening the socket until `open()`
+// is called, so listeners on `onmessage` are wired before the remote side
+// starts emitting events.
+class DeferredWebSocketTransport implements ConnectOverCDPTransport {
+  private readonly _url: string;
+  private readonly _headers: { [key: string]: string };
+  private _ws: ws | undefined;
+  private _closed = false;
+
+  onmessage?: (message: object) => void;
+  onclose?: (reason?: string) => void;
+
+  constructor(url: string, headers: { [key: string]: string }) {
+    this._url = url;
+    this._headers = headers;
+  }
+
+  open(): void {
+    if (this._closed)
+      return;
+    const url = this._url;
+    this._ws = new ws(url, [], {
+      maxPayload: 256 * 1024 * 1024,
+      headers: this._headers,
+      followRedirects: true,
+      agent: (/^(https|wss):\/\//.test(url)) ? httpsHappyEyeballsAgent : httpHappyEyeballsAgent,
+      perMessageDeflate,
+      allowSynchronousEvents: false,
+    });
+    this._ws.addEventListener('message', event => {
+      const eventData = event.data as string;
+      let parsedJson: ProtocolResponse;
+      try {
+        parsedJson = JSON.parse(eventData);
+        this.onmessage?.(parsedJson);
+      } catch {
+        this._ws?.close();
+      }
+    });
+    this._ws.addEventListener('close', event => {
+      this.onclose?.(event.reason);
+    });
+    this._ws.addEventListener('error', () => {});
+  }
+
+  send(message: object): void {
+    this._ws?.send(JSON.stringify(message as ProtocolRequest));
+  }
+
+  close(): void {
+    this._closed = true;
+    this._ws?.close();
+  }
+}
+
+export async function connectOverRDP(progress: Progress, parent: SdkObject, params: channels.BrowserTypeConnectOverCDPParams): Promise<Browser> {
   let headersMap: { [key: string]: string; } | undefined;
-  if (options.headers)
-    headersMap = headersArrayToObject(options.headers, false);
+  if (params.headers)
+    headersMap = headersArrayToObject(params.headers, false);
   if (!headersMap)
     headersMap = { 'User-Agent': getUserAgent() };
   else if (!Object.keys(headersMap).some(key => key.toLowerCase() === 'user-agent'))
     headersMap['User-Agent'] = getUserAgent();
 
-  const proxyBase = deriveProxyBase(endpointURL);
+  const transport = params.transport as ConnectOverCDPTransport | undefined;
+  const proxyBase = transport ? '' : deriveProxyBase(params.endpointURL!);
 
-  const artifactsDir = options.artifactsDir ?? path.join(os.tmpdir(), 'playwright-artifacts-');
+  const artifactsDir = params.artifactsDir ?? path.join(os.tmpdir(), 'playwright-artifacts-');
   const doCleanup = async () => {
     await removeFolders([artifactsDir]);
   };
 
   const browser = await progress.race((async () => {
     const dialogBridge = await DialogBridge.start();
-    const created = new WVBrowser(parent, proxyBase, headersMap!, dialogBridge, {
-      slowMo: options.slowMo,
+    const created = new WVBrowser(parent, proxyBase, headersMap!, dialogBridge, transport, {
+      slowMo: params.slowMo,
       name: 'webkit',
       browserType: 'webkit',
       browserProcess: { close: async () => {}, kill: async () => {} } as BrowserProcess,
@@ -104,15 +164,15 @@ export async function connectOverRDP(progress: Progress, parent: SdkObject, endp
     return created;
   })());
 
-  if (!options.isLocal)
+  if (!params.isLocal)
     browser._isCollocatedWithServer = false;
   browser.on(Browser.Events.Disconnected, doCleanup);
   return browser;
 }
 
 type TabEntry = {
   pageId: string;
-  transport: WebSocketTransport;
+  transport: ConnectOverCDPTransport;
   connection: WVConnection;
   page: WVPage;
 };
@@ -122,24 +182,30 @@ export class WVBrowser extends Browser {
   readonly _proxyBase: string;
   readonly _headers: { [key: string]: string };
   readonly _dialogBridge: DialogBridge;
+  readonly _directPageTransport: ConnectOverCDPTransport | undefined;
   readonly _tabs = new Map<string, TabEntry>();
   private _didCloseFired = false;
   // Backwards compat — old code still reads `_page` for the "primary" tab.
   _page!: WVPage;
 
-  constructor(parent: SdkObject, proxyBase: string, headers: { [key: string]: string }, dialogBridge: DialogBridge, options: BrowserOptions) {
+  constructor(parent: SdkObject, proxyBase: string, headers: { [key: string]: string }, dialogBridge: DialogBridge, directPageTransport: ConnectOverCDPTransport | undefined, options: BrowserOptions) {
     super(parent, options);
     this._proxyBase = proxyBase;
     this._headers = headers;
     this._dialogBridge = dialogBridge;
+    this._directPageTransport = directPageTransport;
     this._context = new WVBrowserContext(this);
   }
 
   async _initialize(): Promise<void> {
     await this._context.initialize();
-    await this._syncTabs();
-    if (!this._tabs.size)
-      throw new Error(`No Mobile Safari tabs found at ${this._proxyBase}/json — open Safari first.`);
+    if (this._directPageTransport) {
+      await this._attachTab('rdp-transport', this._directPageTransport);
+    } else {
+      await this._syncTabs();
+      if (!this._tabs.size)
+        throw new Error(`No Mobile Safari tabs found at ${this._proxyBase}/json — open Safari first.`);
+    }
     this._page = this._firstTab().page;
   }
 
@@ -156,7 +222,7 @@ export class WVBrowser extends Browser {
       if (this._tabs.has(pageId))
         continue;
       try {
-        await this._attachTab(pageId, tab);
+        await this._attachTab(pageId, new DeferredWebSocketTransport(tab.webSocketDebuggerUrl, this._headers));
       } catch (e) {
         debugLogger.log('error', `webview: failed to attach to tab ${pageId}: ${(e as Error).message}`);
       }
@@ -168,15 +234,14 @@ export class WVBrowser extends Browser {
     }
   }
 
-  private async _attachTab(pageId: string, tab: ProxyTab): Promise<void> {
-    const transport = await WebSocketTransport.connect(undefined, tab.webSocketDebuggerUrl, { headers: this._headers, followRedirects: true });
+  private async _attachTab(pageId: string, transport: ConnectOverCDPTransport): Promise<void> {
     const connection = new WVConnection(transport, () => this._detachTab(pageId), this.options.protocolLogger, this.options.browserLogsCollector);
-    // TODO: handle this as RDP connection parameter.
-    connection.outerSession.sendMayFail('Target.setPauseOnStart', { pauseOnStart: true });
     const dialogEndpoint = this._dialogBridge.endpointFor(pageId);
     const page = new WVPage(this._context, connection.outerSession, dialogEndpoint);
     this._dialogBridge.registerTab(pageId, req => page.onBridgeDialog(req));
     this._tabs.set(pageId, { pageId, transport, connection, page });
+    transport.open?.();
+    connection.outerSession.sendMayFail('Target.setPauseOnStart', { pauseOnStart: true });
     await page.waitForInitialized();
   }
 
diff --git a/packages/playwright-core/src/server/webkit/webview/wvPage.ts b/packages/playwright-core/src/server/webkit/webview/wvPage.ts
@@ -19,6 +19,7 @@ import { PNG } from 'pngjs';
 import jpegjs from 'jpeg-js';
 import { assert } from '@isomorphic/assert';
 import { headersArrayToObject } from '@isomorphic/headers';
+import { ManualPromise } from '@isomorphic/manualPromise';
 import { splitErrorMessage } from '@isomorphic/stackTrace';
 import { debugLogger } from '@utils/debugLogger';
 import { eventsHelper } from '@utils/eventsHelper';
@@ -65,8 +66,7 @@ export class WVPage implements PageDelegate {
   private _firstNonInitialNavigationCommittedPromise: Promise<void>;
   private _firstNonInitialNavigationCommittedFulfill = () => {};
   _firstNonInitialNavigationCommittedReject = (e: Error) => {};
-  private _initializedPromise: Promise<void>;
-  private _initializedFulfill = () => {};
+  private _initializedPromise = new ManualPromise<void>();
   private _lastConsoleMessage: { derivedType: string, text: string, handles: JSHandle[]; count: number, location: types.ConsoleMessageLocation; } | null = null;
   private readonly _requestIdToResponseReceivedPayloadEvent = new Map<string, Protocol.Network.responseReceivedPayload>();
 
@@ -95,7 +95,6 @@ export class WVPage implements PageDelegate {
     });
     // Avoid unhandled rejection on disconnect in the middle of initialization.
     this._firstNonInitialNavigationCommittedPromise.catch(() => {});
-    this._initializedPromise = new Promise(f => { this._initializedFulfill = f; });
   }
 
   waitForInitialized(): Promise<void> {
@@ -225,7 +224,7 @@ export class WVPage implements PageDelegate {
       if (targetInfo.isPaused)
         this._outerSession.sendMayFail('Target.resume', { targetId: targetInfo.targetId });
       await this._page.reportAsNew(undefined, pageOrError instanceof Page ? undefined : pageOrError);
-      this._initializedFulfill();
+      this._initializedPromise.resolve();
     } else {
       assert(!this._provisionalPage);
       this._provisionalPage = new WVProvisionalPage(session, this);
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
@@ -15384,10 +15384,6 @@ export interface BrowserType<Unused = {}> {
    * @param options
    */
   connectOverCDP(endpointURL: string, options?: ConnectOverCDPOptions): Promise<Browser>;
-  /**
-   * Option `wsEndpoint` is deprecated. Instead use `endpointURL`.
-   * @deprecated
-   */
   /**
    * This method attaches Playwright to an existing browser instance using the Chrome DevTools Protocol.
    *
@@ -15413,7 +15409,11 @@ export interface BrowserType<Unused = {}> {
    * `ws://127.0.0.1:9222/devtools/browser/387adf4c-243f-4051-a181-46798f4a46f4`.
    * @param options
    */
-  connectOverCDP(options: ConnectOverCDPOptions & { wsEndpoint?: string }): Promise<Browser>;
+  connectOverCDP(transport: ConnectOverCDPTransport, options?: ConnectOverCDPOptions): Promise<Browser>;
+  /**
+   * Option `wsEndpoint` is deprecated. Instead use `endpointURL`.
+   * @deprecated
+   */
   /**
    * This method attaches Playwright to an existing browser instance using the Chrome DevTools Protocol.
    *
@@ -15439,7 +15439,7 @@ export interface BrowserType<Unused = {}> {
    * `ws://127.0.0.1:9222/devtools/browser/387adf4c-243f-4051-a181-46798f4a46f4`.
    * @param options
    */
-  connectOverCDP(transport: ConnectionTransport, options?: ConnectOverCDPOptions): Promise<Browser>;
+  connectOverCDP(options: ConnectOverCDPOptions & { wsEndpoint?: string }): Promise<Browser>;
 
   /**
    * This method attaches Playwright to an existing browser instance created via `BrowserType.launchServer` in Node.js.
@@ -16221,7 +16221,8 @@ export interface BrowserType<Unused = {}> {
   name(): string;
 }
 
-export interface ConnectionTransport {
+export interface ConnectOverCDPTransport {
+  open?(): void;
   send(message: object): void;
   close(): void;
   onmessage?: (message: object) => void;
diff --git a/utils/generate_types/index.js b/utils/generate_types/index.js
@@ -522,7 +522,7 @@ class TypesGenerator {
         ...assertionClasses,
       ]),
       ignoreMissing: new Set([
-        'ConnectionTransport',
+        'ConnectOverCDPTransport',
       ]),
     });
     let types = await generator.generateTypes(path.join(__dirname, 'overrides.d.ts'));
diff --git a/utils/generate_types/overrides.d.ts b/utils/generate_types/overrides.d.ts

Original file line number	Diff line number	Diff line change
`@@ -138,10 +138,10 @@ export class BrowserType extends ChannelOwner<channels.BrowserTypeChannel> imple`
`138`	`138`
`139`	`139`	`async connectOverCDP(options: api.ConnectOverCDPOptions & { wsEndpoint?: string }): Promise<api.Browser>;`
`140`	`140`	`async connectOverCDP(endpointURL: string, options?: api.ConnectOverCDPOptions): Promise<api.Browser>;`
`141`		`- async connectOverCDP(transport: api.ConnectionTransport, options?: api.ConnectOverCDPOptions): Promise<api.Browser>;`
`142`		`- async connectOverCDP(overloaded: (api.ConnectOverCDPOptions & { wsEndpoint?: string }) \| string \| api.ConnectionTransport, options?: api.ConnectOverCDPOptions): Promise<Browser> {`
	`141`	`+ async connectOverCDP(transport: api.ConnectOverCDPTransport, options?: api.ConnectOverCDPOptions): Promise<api.Browser>;`
	`142`	`+ async connectOverCDP(overloaded: (api.ConnectOverCDPOptions & { wsEndpoint?: string }) \| string \| api.ConnectOverCDPTransport, options?: api.ConnectOverCDPOptions): Promise<Browser> {`
`143`	`143`	`let endpointURL: string \| undefined;`
`144`		`- let transport: api.ConnectionTransport \| undefined;`
	`144`	`+ let transport: api.ConnectOverCDPTransport \| undefined;`
`145`	`145`	`let params: api.ConnectOverCDPOptions;`
`146`	`146`	`if (typeof overloaded === 'string') {`
`147`	`147`	`endpointURL = overloaded;`
`@@ -193,6 +193,6 @@ export class BrowserType extends ChannelOwner<channels.BrowserTypeChannel> imple`
`193`	`193`	`}`
`194`	`194`	`}`
`195`	`195`
`196`		`-function isConnectionTransport(value: any): value is api.ConnectionTransport {`
	`196`	`+function isConnectionTransport(value: any): value is api.ConnectOverCDPTransport {`
`197`	`197`	`return !!value && typeof value === 'object' && typeof value.send === 'function' && typeof value.close === 'function';`
`198`	`198`	`}`
Original file line number	Diff line number	Diff line change
`@@ -42,7 +42,7 @@ export class WebKit extends BrowserType {`
`42`	`42`	`}`
`43`	`43`
`44`	`44`	`override async connectOverCDP(progress: Progress, params: channels.BrowserTypeConnectOverCDPParams): Promise<Browser> {`
`45`		`- return connectOverRDP(progress, this, params.endpointURL!, params);`
	`45`	`+ return connectOverRDP(progress, this, params);`
`46`	`46`	`}`
`47`	`47`
`48`	`48`	`override amendEnvironment(env: NodeJS.ProcessEnv, userDataDir: string, isPersistent: boolean, options: types.LaunchOptions): NodeJS.ProcessEnv {`