chore: add _connectOverCDPTransport method (#39251)

Author: yury-s

packages/playwright-core/src/client/browserType.ts

@@ -209,4 +209,15 @@ export class BrowserType extends ChannelOwner<channels.BrowserTypeChannel> imple
       await this._instrumentation.runAfterCreateBrowserContext(BrowserContext.from(result.defaultContext));
     return browser;
   }
+
+  async _connectOverCDPTransport(transport: /* ConnectionTransport */ any) {
+    if (this.name() !== 'chromium')
+      throw new Error('Connecting over CDP is only supported in Chromium.');
+    const result = await this._channel.connectOverCDPTransport({ transport });
+    const browser = Browser.from(result.browser);
+    browser._connectToBrowserType(this, {}, undefined);
+    if (result.defaultContext)
+      await this._instrumentation.runAfterCreateBrowserContext(BrowserContext.from(result.defaultContext));
+    return browser;
+  }
 }

packages/playwright-core/src/protocol/validator.ts

@@ -630,6 +630,13 @@ scheme.BrowserTypeConnectOverCDPResult = tObject({
   browser: tChannel(['Browser']),
   defaultContext: tOptional(tChannel(['BrowserContext'])),
 });
+scheme.BrowserTypeConnectOverCDPTransportParams = tObject({
+  transport: tBinary,
+});
+scheme.BrowserTypeConnectOverCDPTransportResult = tObject({
+  browser: tChannel(['Browser']),
+  defaultContext: tOptional(tChannel(['BrowserContext'])),
+});
 scheme.BrowserInitializer = tObject({
   version: tString,
   name: tString,

packages/playwright-core/src/protocol/validatorPrimitives.ts

@@ -84,7 +84,8 @@ export const tBinary: Validator = (arg: any, path: string, context: ValidatorCon
     return (arg as Buffer).toString('base64');
   }
   if (context.binary === 'buffer') {
-    if (!(arg instanceof Buffer))
+    // TODO: support custom binary types.
+    if (!(arg instanceof Buffer) && !(arg instanceof Object))
       throw new ValidationError(`${path}: expected Buffer, got ${typeof arg}`);
     return arg;
   }

packages/playwright-core/src/server/browserType.ts

@@ -283,6 +283,10 @@ export abstract class BrowserType extends SdkObject {
     throw new Error('CDP connections are only supported by Chromium');
   }
 
+  async connectOverCDPTransport(progress: Progress, transport: ConnectionTransport): Promise<Browser> {
+    throw new Error('CDP connections are only supported by Chromium');
+  }
+
   async _launchWithSeleniumHub(progress: Progress, hubUrl: string, options: types.LaunchOptions): Promise<Browser> {
     throw new Error('Connecting to SELENIUM_REMOTE_URL is only supported by Chromium');
   }

packages/playwright-core/src/server/chromium/chromium.ts

@@ -89,6 +89,13 @@ export class Chromium extends BrowserType {
     else if (headersMap && !Object.keys(headersMap).some(key => key.toLowerCase() === 'user-agent'))
       headersMap['User-Agent'] = getUserAgent();
 
+    const wsEndpoint = await urlToWSEndpoint(progress, endpointURL, headersMap);
+    const chromeTransport = await WebSocketTransport.connect(progress, wsEndpoint, { headers: headersMap });
+    const closeAndWait = async () => await chromeTransport.closeAndWait();
+    return this._connectOverCDPImpl(progress, chromeTransport, closeAndWait, options, onClose);
+  }
+
+  private async _connectOverCDPImpl(progress: Progress, transport: ConnectionTransport, closeAndWait: () => Promise<void>, options: types.LaunchOptions & { isLocal?: boolean }, onClose?: () => Promise<void>) {
     const artifactsDir = await progress.race(fs.promises.mkdtemp(ARTIFACTS_FOLDER));
     const doCleanup = async () => {
       await removeFolders([artifactsDir]);
@@ -97,16 +104,12 @@ export class Chromium extends BrowserType {
       await cb?.();
     };
 
-    let chromeTransport: WebSocketTransport | undefined;
     const doClose = async () => {
-      await chromeTransport?.closeAndWait();
+      await closeAndWait();
       await doCleanup();
     };
 
     try {
-      const wsEndpoint = await urlToWSEndpoint(progress, endpointURL, headersMap);
-      chromeTransport = await WebSocketTransport.connect(progress, wsEndpoint, { headers: headersMap });
-
       const browserProcess: BrowserProcess = { close: doClose, kill: doClose };
       const persistent: types.BrowserContextOptions = { noDefaultViewport: true };
       const browserOptions: BrowserOptions = {
@@ -123,7 +126,7 @@ export class Chromium extends BrowserType {
         originalLaunchOptions: {},
       };
       validateBrowserContextOptions(persistent, browserOptions);
-      const browser = await progress.race(CRBrowser.connect(this.attribution.playwright, chromeTransport, browserOptions));
+      const browser = await progress.race(CRBrowser.connect(this.attribution.playwright, transport, browserOptions));
       if (!options.isLocal)
         browser._isCollocatedWithServer = false;
       browser.on(Browser.Events.Disconnected, doCleanup);
@@ -134,6 +137,11 @@ export class Chromium extends BrowserType {
     }
   }
 
+  override async connectOverCDPTransport(progress: Progress, transport: ConnectionTransport) {
+    const closeAndWait = async () => transport.close();
+    return this._connectOverCDPImpl(progress, transport, closeAndWait, { isLocal: true });
+  }
+
   private _createDevTools() {
     // TODO: this is totally wrong when using channels.
     const directory = registry.findExecutable('chromium').directory;

packages/playwright-core/src/server/dispatchers/browserTypeDispatcher.ts

@@ -63,4 +63,13 @@ export class BrowserTypeDispatcher extends Dispatcher<BrowserType, channels.Brow
       defaultContext: browser._defaultContext ? BrowserContextDispatcher.from(browserDispatcher, browser._defaultContext) : undefined,
     };
   }
+
+  async connectOverCDPTransport(params: channels.BrowserTypeConnectOverCDPTransportParams, progress: Progress): Promise<channels.BrowserTypeConnectOverCDPTransportResult> {
+    if (this._denyLaunch)
+      throw new Error(`Launching more browsers is not allowed.`);
+
+    const browser = await this._object.connectOverCDPTransport(progress, params.transport as any);
+    const browserDispatcher = new BrowserDispatcher(this, browser);
+    return { browser: browserDispatcher, defaultContext: browser._defaultContext ? BrowserContextDispatcher.from(browserDispatcher, browser._defaultContext) : undefined };
+  }
 }

packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts

@@ -50,6 +50,7 @@ export const methodMetainfo = new Map<string, { internal?: boolean, title?: stri
   ['BrowserType.launch', { title: 'Launch browser', }],
   ['BrowserType.launchPersistentContext', { title: 'Launch persistent context', }],
   ['BrowserType.connectOverCDP', { title: 'Connect over CDP', }],
+  ['BrowserType.connectOverCDPTransport', { title: 'Connect over CDP transport', }],
   ['Browser.close', { title: 'Close browser', pausesBeforeAction: true, }],
   ['Browser.killForTests', { internal: true, }],
   ['Browser.defaultUserAgentForTest', { internal: true, }],

packages/protocol/src/channels.d.ts

@@ -887,6 +887,7 @@ export interface BrowserTypeChannel extends BrowserTypeEventTarget, Channel {
   launch(params: BrowserTypeLaunchParams, progress?: Progress): Promise<BrowserTypeLaunchResult>;
   launchPersistentContext(params: BrowserTypeLaunchPersistentContextParams, progress?: Progress): Promise<BrowserTypeLaunchPersistentContextResult>;
   connectOverCDP(params: BrowserTypeConnectOverCDPParams, progress?: Progress): Promise<BrowserTypeConnectOverCDPResult>;
+  connectOverCDPTransport(params: BrowserTypeConnectOverCDPTransportParams, progress?: Progress): Promise<BrowserTypeConnectOverCDPTransportResult>;
 }
 export type BrowserTypeLaunchParams = {
   channel?: string,
@@ -1126,6 +1127,16 @@ export type BrowserTypeConnectOverCDPResult = {
   browser: BrowserChannel,
   defaultContext?: BrowserContextChannel,
 };
+export type BrowserTypeConnectOverCDPTransportParams = {
+  transport: Binary,
+};
+export type BrowserTypeConnectOverCDPTransportOptions = {
+
+};
+export type BrowserTypeConnectOverCDPTransportResult = {
+  browser: BrowserChannel,
+  defaultContext?: BrowserContextChannel,
+};
 
 export interface BrowserTypeEvents {
 }

packages/protocol/src/protocol.yml

@@ -1006,6 +1006,14 @@ BrowserType:
         browser: Browser
         defaultContext: BrowserContext?
 
+    connectOverCDPTransport:
+      title: Connect over CDP transport
+      parameters:
+        transport: binary
+      returns:
+        browser: Browser
+        defaultContext: BrowserContext?
+
 Browser:
   type: interface
 

tests/library/chromium/connect-over-cdp.spec.ts

@@ -19,6 +19,7 @@ import { playwrightTest as test, expect } from '../../config/browserTest';
 import http from 'http';
 import fs from 'fs';
 import { getUserAgent } from '../../../packages/playwright-core/lib/server/utils/userAgent';
+import { WebSocketTransport } from '../../../packages/playwright-core/lib/server/transport';
 import { suppressCertificateWarning } from '../../config/utils';
 import type { Frame } from '../../../packages/playwright-core/lib/server/frames';
 
@@ -643,3 +644,32 @@ test('should get title and URL of existing page', async ({ browserType, mode, se
     await browserServer.close();
   }
 });
+
+test('should connect over CDP using a ConnectionTransport', async ({ browserType, mode, server }, testInfo) => {
+  test.skip(mode !== 'default', '_connectOverCDPTransport is only available in-process');
+
+  const port = 9339 + testInfo.workerIndex;
+  const browserServer = await browserType.launch({
+    args: ['--remote-debugging-port=' + port]
+  });
+  try {
+    const json = await new Promise<string>((resolve, reject) => {
+      http.get(`http://127.0.0.1:${port}/json/version/`, resp => {
+        let data = '';
+        resp.on('data', chunk => data += chunk);
+        resp.on('end', () => resolve(data));
+      }).on('error', reject);
+    });
+    const wsEndpoint = JSON.parse(json).webSocketDebuggerUrl;
+    const transport = await WebSocketTransport.connect(undefined, wsEndpoint);
+    const cdpBrowser = await (browserType as any)._connectOverCDPTransport(transport);
+    const contexts = cdpBrowser.contexts();
+    expect(contexts.length).toBe(1);
+    const page = await contexts[0].newPage();
+    await page.goto(server.EMPTY_PAGE);
+    expect(page.url()).toBe(server.EMPTY_PAGE);
+    await cdpBrowser.close();
+  } finally {
+    await browserServer.close();
+  }
+});