From 13d80f184ec34621f877ef46b64ecb930e9f6410 Mon Sep 17 00:00:00 2001 From: Adam Gastineau Date: Thu, 30 Jan 2025 12:36:40 -0800 Subject: [PATCH] cherry-pick(#34560): chore(docs): clarify connection method via BrowserType.connect (#34562) --- docs/src/api/class-browsertype.md | 24 ++++++++++++++-- packages/playwright-core/types/types.d.ts | 34 +++++++++++++++++------ 2 files changed, 48 insertions(+), 10 deletions(-) diff --git a/docs/src/api/class-browsertype.md b/docs/src/api/class-browsertype.md index 0d41bb1aa7a03..87a684db3df53 100644 --- a/docs/src/api/class-browsertype.md +++ b/docs/src/api/class-browsertype.md @@ -87,15 +87,31 @@ class BrowserTypeExamples ## async method: BrowserType.connect * since: v1.8 +* langs: js - returns: <[Browser]> -This method attaches Playwright to an existing browser instance. When connecting to another browser launched via `BrowserType.launchServer` in Node.js, the major and minor version needs to match the client version (1.2.3 → is compatible with 1.2.x). +This method attaches Playwright to an existing browser instance created via [`method: BrowserType.launchServer`]. + +:::note +The major and minor version of the Playwright instance that connects needs to match the version of Playwright that launches the browser (1.2.3 → is compatible with 1.2.x). +::: + +## async method: BrowserType.connect +* since: v1.8 +* langs: python, csharp, java +- returns: <[Browser]> + +This method attaches Playwright to an existing browser instance created via `BrowserType.launchServer` in Node.js. + +:::note +The major and minor version of the Playwright instance that connects needs to match the version of Playwright that launches the browser (1.2.3 → is compatible with 1.2.x). +::: ### param: BrowserType.connect.wsEndpoint * since: v1.10 - `wsEndpoint` <[string]> -A browser websocket endpoint to connect to. +A Playwright browser websocket endpoint to connect to. You obtain this endpoint via [`method: BrowserServer.wsEndpoint`]. ### option: BrowserType.connect.headers * since: v1.11 @@ -152,6 +168,10 @@ The default browser context is accessible via [`method: Browser.contexts`]. Connecting over the Chrome DevTools Protocol is only supported for Chromium-based browsers. ::: +:::note +This connection is significantly lower fidelity than the Playwright protocol connection via [`method: BrowserType.connect`]. If you are experiencing issues or attempting to use advanced functionality, you probably want to use [`method: BrowserType.connect`]. +::: + **Usage** ```js diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts index a87d18b3073f4..4bea0948d8da6 100644 --- a/packages/playwright-core/types/types.d.ts +++ b/packages/playwright-core/types/types.d.ts @@ -14566,6 +14566,11 @@ export interface BrowserType { * * **NOTE** Connecting over the Chrome DevTools Protocol is only supported for Chromium-based browsers. * + * **NOTE** This connection is significantly lower fidelity than the Playwright protocol connection via + * [browserType.connect(wsEndpoint[, options])](https://playwright.dev/docs/api/class-browsertype#browser-type-connect). + * If you are experiencing issues or attempting to use advanced functionality, you probably want to use + * [browserType.connect(wsEndpoint[, options])](https://playwright.dev/docs/api/class-browsertype#browser-type-connect). + * * **Usage** * * ```js @@ -14591,6 +14596,11 @@ export interface BrowserType { * * **NOTE** Connecting over the Chrome DevTools Protocol is only supported for Chromium-based browsers. * + * **NOTE** This connection is significantly lower fidelity than the Playwright protocol connection via + * [browserType.connect(wsEndpoint[, options])](https://playwright.dev/docs/api/class-browsertype#browser-type-connect). + * If you are experiencing issues or attempting to use advanced functionality, you probably want to use + * [browserType.connect(wsEndpoint[, options])](https://playwright.dev/docs/api/class-browsertype#browser-type-connect). + * * **Usage** * * ```js @@ -14605,10 +14615,14 @@ export interface BrowserType { */ connectOverCDP(options: ConnectOverCDPOptions & { wsEndpoint?: string }): Promise; /** - * This method attaches Playwright to an existing browser instance. When connecting to another browser launched via - * `BrowserType.launchServer` in Node.js, the major and minor version needs to match the client version (1.2.3 → is - * compatible with 1.2.x). - * @param wsEndpoint A browser websocket endpoint to connect to. + * This method attaches Playwright to an existing browser instance created via + * [browserType.launchServer([options])](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-server). + * + * **NOTE** The major and minor version of the Playwright instance that connects needs to match the version of + * Playwright that launches the browser (1.2.3 → is compatible with 1.2.x). + * + * @param wsEndpoint A Playwright browser websocket endpoint to connect to. You obtain this endpoint via + * [browserServer.wsEndpoint()](https://playwright.dev/docs/api/class-browserserver#browser-server-ws-endpoint). * @param options */ connect(wsEndpoint: string, options?: ConnectOptions): Promise; @@ -14619,10 +14633,14 @@ export interface BrowserType { * @deprecated */ /** - * This method attaches Playwright to an existing browser instance. When connecting to another browser launched via - * `BrowserType.launchServer` in Node.js, the major and minor version needs to match the client version (1.2.3 → is - * compatible with 1.2.x). - * @param wsEndpoint A browser websocket endpoint to connect to. + * This method attaches Playwright to an existing browser instance created via + * [browserType.launchServer([options])](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-server). + * + * **NOTE** The major and minor version of the Playwright instance that connects needs to match the version of + * Playwright that launches the browser (1.2.3 → is compatible with 1.2.x). + * + * @param wsEndpoint A Playwright browser websocket endpoint to connect to. You obtain this endpoint via + * [browserServer.wsEndpoint()](https://playwright.dev/docs/api/class-browserserver#browser-server-ws-endpoint). * @param options */ connect(options: ConnectOptions & { wsEndpoint?: string }): Promise;