feat(launch): introduce client, server & persistent launch modes (1) (#838)

Author: pavelfeldman

docs/api.md

@@ -149,10 +149,10 @@ An example of launching a browser executable and connecting to a [Browser] later
 const { webkit } = require('playwright');  // Or 'chromium' or 'firefox'.
 
 (async () => {
-  const browserApp = await webkit.launchBrowserApp({ webSocket: true });
-  const connectOptions = browserApp.connectOptions();
-  // Use connect options later to establish a connection.
-  const browser = await webkit.connect(connectOptions);
+  const browserApp = await webkit.launchBrowserApp();
+  const wsEndpoint = browserApp.wsEndpoint();
+  // Use web socket endpoint later to establish a connection.
+  const browser = await webkit.connect({ wsEndpoint });
   // Close browser instance.
   await browserApp.close();
 })();
@@ -3413,7 +3413,6 @@ If the function passed to the `worker.evaluateHandle` returns a [Promise], then
 <!-- GEN:toc -->
 - [event: 'close'](#event-close-2)
 - [browserApp.close()](#browserappclose)
-- [browserApp.connectOptions()](#browserappconnectoptions)
 - [browserApp.kill()](#browserappkill)
 - [browserApp.process()](#browserappprocess)
 - [browserApp.wsEndpoint()](#browserappwsendpoint)
@@ -3428,14 +3427,6 @@ Emitted when the browser app closes.
 
 Closes the browser gracefully and makes sure the process is terminated.
 
-#### browserApp.connectOptions()
-- returns: <[Object]>
-  - `browserWSEndpoint` <?[string]> a browser websocket endpoint to connect to.
-  - `slowMo` <[number]>
-  - `transport` <[ConnectionTransport]> **Experimental** A custom transport object which should be used to connect.
-
-This options object can be passed to [browserType.connect(options)](#browsertypeconnectoptions) to establish connection to the browser.
-
 #### browserApp.kill()
 
 Kills the browser process.
@@ -3444,10 +3435,9 @@ Kills the browser process.
 - returns: <?[ChildProcess]> Spawned browser application process.
 
 #### browserApp.wsEndpoint()
-- returns: <?[string]> Browser websocket url.
-
-Browser websocket endpoint which can be used as an argument to [browserType.connect(options)] to establish connection to the browser. Requires browser app to be launched with `browserType.launchBrowserApp({ webSocket: true, ... })`.
+- returns: <[string]> Browser websocket url.
 
+Browser websocket endpoint which can be used as an argument to [browserType.connect(options)](#browsertypeconnectoptions) to establish connection to the browser.
 
 ### class: BrowserType
 
@@ -3478,10 +3468,8 @@ const { chromium } = require('playwright');  // Or 'firefox' or 'webkit'.
 
 #### browserType.connect(options)
 - `options` <[Object]>
-  - `browserWSEndpoint` <?[string]> A browser websocket endpoint to connect to.
+  - `wsEndpoint` <?[string]> A browser websocket endpoint to connect to.
   - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on.
-  - `browserURL` <?[string]> **Chromium-only** A browser url to connect to, in format `http://${host}:${port}`. Use interchangeably with `browserWSEndpoint` to let Playwright fetch it from [metadata endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target).
-  - `transport` <[ConnectionTransport]> **Experimental** Specify a custom transport object for Playwright to use.
 - returns: <[Promise]<[Browser]>>
 
 This methods attaches Playwright to an existing browser instance.
@@ -3547,7 +3535,6 @@ try {
 - `options` <[Object]>  Set of configurable options to set on the browser. Can have the following fields:
   - `headless` <[boolean]> Whether to run browser in headless mode. More details for [Chromium](https://developers.google.com/web/updates/2017/04/headless-chrome) and [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Headless_mode). Defaults to `true` unless the `devtools` option is `true`.
   - `executablePath` <[string]> Path to a browser executable to run instead of the bundled one. If `executablePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). **BEWARE**: Playwright is only [guaranteed to work](https://github.com/Microsoft/playwright/#q-why-doesnt-playwright-vxxx-work-with-chromium-vyyy) with the bundled Chromium, Firefox or WebKit, use at your own risk.
-  - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on.
   - `args` <[Array]<[string]>> Additional arguments to pass to the browser instance. The list of Chromium flags can be found [here](http://peter.sh/experiments/chromium-command-line-switches/).
   - `ignoreDefaultArgs` <[boolean]|[Array]<[string]>> If `true`, then do not use [`browserType.defaultArgs()`](#browsertypedefaultargsoptions). If an array is given, then filter out the given default arguments. Dangerous option; use with care. Defaults to `false`.
   - `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`.
@@ -3557,7 +3544,6 @@ try {
   - `dumpio` <[boolean]> Whether to pipe the browser process stdout and stderr into `process.stdout` and `process.stderr`. Defaults to `false`.
   - `userDataDir` <[string]> Path to a User Data Directory, which stores browser session data like cookies and local storage. More details for [Chromium](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md) and [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options#User_Profile).
   - `env` <[Object]> Specify environment variables that will be visible to the browser. Defaults to `process.env`.
-  - `webSocket` <[boolean]> Connects to the browser over a WebSocket instead of a pipe. Defaults to `false`.
   - `devtools` <[boolean]> **Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the `headless` option will be set `false`.
 - returns: <[Promise]<[Browser]>> Promise which resolves to browser instance.
 
@@ -3591,7 +3577,6 @@ const browser = await chromium.launch({  // Or 'firefox' or 'webkit'.
   - `dumpio` <[boolean]> Whether to pipe the browser process stdout and stderr into `process.stdout` and `process.stderr`. Defaults to `false`.
   - `userDataDir` <[string]> Path to a User Data Directory, which stores browser session data like cookies and local storage. More details for [Chromium](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md) and [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options#User_Profile).
   - `env` <[Object]> Specify environment variables that will be visible to the browser. Defaults to `process.env`.
-  - `webSocket` <[boolean]> Connects to the browser over a WebSocket instead of a pipe. Defaults to `false`.
   - `devtools` <[boolean]> **Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the `headless` option will be set `false`.
 - returns: <[Promise]<[BrowserApp]>> Promise which resolves to the browser app instance.
 
@@ -3898,7 +3883,6 @@ const { chromium } = require('playwright');
 [ChromiumBrowser]: #class-chromiumbrowser "ChromiumBrowser"
 [ChromiumSession]: #class-chromiumsession  "ChromiumSession"
 [ChromiumTarget]: #class-chromiumtarget "ChromiumTarget"
-[ConnectionTransport]: ../lib/WebSocketTransport.js "ConnectionTransport"
 [ConsoleMessage]: #class-consolemessage "ConsoleMessage"
 [Coverage]: #class-coverage "Coverage"
 [Dialog]: #class-dialog "Dialog"

src/browser.ts

@@ -15,9 +15,7 @@
  */
 
 import { BrowserContext, BrowserContextOptions } from './browserContext';
-import { ConnectionTransport, SlowMoTransport } from './transport';
 import * as platform from './platform';
-import { assert } from './helper';
 
 export interface Browser extends platform.EventEmitterType {
   newContext(options?: BrowserContextOptions): Promise<BrowserContext>;
@@ -31,16 +29,5 @@ export interface Browser extends platform.EventEmitterType {
 
 export type ConnectOptions = {
   slowMo?: number,
-  browserWSEndpoint?: string;
-  transport?: ConnectionTransport;
+  wsEndpoint: string
 };
-
-export async function createTransport(options: ConnectOptions): Promise<ConnectionTransport> {
-  assert(Number(!!options.browserWSEndpoint) + Number(!!options.transport) === 1, 'Exactly one of browserWSEndpoint or transport must be passed to connect');
-  let transport: ConnectionTransport | undefined;
-  if (options.transport)
-    transport = options.transport;
-  else if (options.browserWSEndpoint)
-    transport = await platform.createWebSocketTransport(options.browserWSEndpoint);
-  return SlowMoTransport.wrap(transport!, options.slowMo);
-}

src/chromium/crBrowser.ts

@@ -24,11 +24,12 @@ import { Page, Worker } from '../page';
 import { CRTarget } from './crTarget';
 import { Protocol } from './protocol';
 import { CRPage } from './crPage';
-import { Browser, createTransport, ConnectOptions } from '../browser';
+import { Browser } from '../browser';
 import * as network from '../network';
 import * as types from '../types';
 import * as platform from '../platform';
 import { readProtocolStream } from './crProtocolHelper';
+import { ConnectionTransport, SlowMoTransport } from '../transport';
 
 export class CRBrowser extends platform.EventEmitter implements Browser {
   _connection: CRConnection;
@@ -41,9 +42,8 @@ export class CRBrowser extends platform.EventEmitter implements Browser {
   private _tracingPath: string | null = '';
   private _tracingClient: CRSession | undefined;
 
-  static async connect(options: ConnectOptions): Promise<CRBrowser> {
-    const transport = await createTransport(options);
-    const connection = new CRConnection(transport);
+  static async connect(transport: ConnectionTransport, slowMo?: number): Promise<CRBrowser> {
+    const connection = new CRConnection(SlowMoTransport.wrap(transport, slowMo));
     const { browserContextIds } = await connection.rootSession.send('Target.getBrowserContexts');
     const browser = new CRBrowser(connection, browserContextIds);
     await connection.rootSession.send('Target.setDiscoverTargets', { discover: true });

src/firefox/ffBrowser.ts

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 
-import { Browser, createTransport, ConnectOptions } from '../browser';
+import { Browser } from '../browser';
 import { BrowserContext, BrowserContextOptions } from '../browserContext';
 import { Events } from '../events';
 import { assert, helper, RegisteredListener } from '../helper';
@@ -26,6 +26,7 @@ import { ConnectionEvents, FFConnection, FFSessionEvents } from './ffConnection'
 import { FFPage } from './ffPage';
 import * as platform from '../platform';
 import { Protocol } from './protocol';
+import { ConnectionTransport, SlowMoTransport } from '../transport';
 
 export class FFBrowser extends platform.EventEmitter implements Browser {
   _connection: FFConnection;
@@ -34,10 +35,9 @@ export class FFBrowser extends platform.EventEmitter implements Browser {
   private _contexts: Map<string, BrowserContext>;
   private _eventListeners: RegisteredListener[];
 
-  static async connect(options: ConnectOptions): Promise<FFBrowser> {
-    const transport = await createTransport(options);
-    const connection = new FFConnection(transport);
-    const {browserContextIds} = await connection.send('Target.getBrowserContexts');
+  static async connect(transport: ConnectionTransport, slowMo?: number): Promise<FFBrowser> {
+    const connection = new FFConnection(SlowMoTransport.wrap(transport, slowMo));
+    const { browserContextIds } = await connection.send('Target.getBrowserContexts');
     const browser = new FFBrowser(connection, browserContextIds);
     await connection.send('Target.enable');
     await browser._waitForTarget(t => t.type() === 'page');

src/server/browserApp.ts

@@ -15,31 +15,26 @@
  */
 
 import { ChildProcess, execSync } from 'child_process';
-import { ConnectOptions } from '../browser';
 import * as platform from '../platform';
 
 export class BrowserApp extends platform.EventEmitter {
   private _process: ChildProcess;
   private _gracefullyClose: () => Promise<void>;
-  private _connectOptions: ConnectOptions;
+  private _browserWSEndpoint: string | null = null;
 
-  constructor(process: ChildProcess, gracefullyClose: () => Promise<void>, connectOptions: ConnectOptions) {
+  constructor(process: ChildProcess, gracefullyClose: () => Promise<void>, wsEndpoint: string | null) {
     super();
     this._process = process;
     this._gracefullyClose = gracefullyClose;
-    this._connectOptions = connectOptions;
+    this._browserWSEndpoint = wsEndpoint;
   }
 
   process(): ChildProcess {
     return this._process;
   }
 
   wsEndpoint(): string | null {
-    return this._connectOptions.browserWSEndpoint || null;
-  }
-
-  connectOptions(): ConnectOptions {
-    return this._connectOptions;
+    return this._browserWSEndpoint;
   }
 
   kill() {

src/server/browserType.ts

@@ -34,18 +34,16 @@ export type LaunchOptions = BrowserArgOptions & {
   handleSIGHUP?: boolean,
   timeout?: number,
   dumpio?: boolean,
-  env?: {[key: string]: string} | undefined,
-  webSocket?: boolean,
-  slowMo?: number,  // TODO: we probably don't want this in launchBrowserApp.
+  env?: {[key: string]: string} | undefined
 };
 
 export interface BrowserType {
   executablePath(): string;
   name(): string;
   launchBrowserApp(options?: LaunchOptions): Promise<BrowserApp>;
-  launch(options?: LaunchOptions): Promise<Browser>;
+  launch(options?: LaunchOptions & { slowMo?: number }): Promise<Browser>;
   defaultArgs(options?: BrowserArgOptions): string[];
-  connect(options: ConnectOptions & { browserURL?: string }): Promise<Browser>;
+  connect(options: ConnectOptions): Promise<Browser>;
   devices: types.Devices;
   errors: { TimeoutError: typeof TimeoutError };
 }

src/server/chromium.ts

@@ -30,9 +30,10 @@ import { launchProcess, waitForLine } from '../server/processLauncher';
 import { kBrowserCloseMessageId } from '../chromium/crConnection';
 import { PipeTransport } from './pipeTransport';
 import { LaunchOptions, BrowserArgOptions, BrowserType } from './browserType';
-import { createTransport, ConnectOptions } from '../browser';
+import { ConnectOptions } from '../browser';
 import { BrowserApp } from './browserApp';
 import { Events } from '../events';
+import { ConnectionTransport } from '../transport';
 
 export class Chromium implements BrowserType {
   private _projectRoot: string;
@@ -47,26 +48,29 @@ export class Chromium implements BrowserType {
     return 'chromium';
   }
 
-  async launch(options?: LaunchOptions): Promise<CRBrowser> {
-    const app = await this.launchBrowserApp(options);
-    const browser = await CRBrowser.connect(app.connectOptions());
+  async launch(options?: LaunchOptions & { slowMo?: number }): Promise<CRBrowser> {
+    const { browserApp, transport } = await this._launchBrowserApp(options, false);
+    const browser = await CRBrowser.connect(transport!, options && options.slowMo);
     // Hack: for typical launch scenario, ensure that close waits for actual process termination.
-    browser.close = () => app.close();
+    browser.close = () => browserApp.close();
+    (browser as any)['__app__'] = browserApp;
     return browser;
   }
 
-  async launchBrowserApp(options: LaunchOptions = {}): Promise<BrowserApp> {
+  async launchBrowserApp(options?: LaunchOptions): Promise<BrowserApp> {
+    return (await this._launchBrowserApp(options, true)).browserApp;
+  }
+
+  async _launchBrowserApp(options: LaunchOptions = {}, isServer: boolean): Promise<{ browserApp: BrowserApp, transport?: ConnectionTransport }> {
     const {
       ignoreDefaultArgs = false,
       args = [],
       dumpio = false,
       executablePath = null,
-      webSocket = false,
       env = process.env,
       handleSIGINT = true,
       handleSIGTERM = true,
       handleSIGHUP = true,
-      slowMo = 0,
       timeout = 30000
     } = options;
 
@@ -81,7 +85,7 @@ export class Chromium implements BrowserType {
     let temporaryUserDataDir: string | null = null;
 
     if (!chromeArguments.some(argument => argument.startsWith('--remote-debugging-')))
-      chromeArguments.push(webSocket ? '--remote-debugging-port=0' : '--remote-debugging-pipe');
+      chromeArguments.push(isServer ? '--remote-debugging-port=0' : '--remote-debugging-pipe');
     if (!chromeArguments.some(arg => arg.startsWith('--user-data-dir'))) {
       temporaryUserDataDir = await mkdtempAsync(CHROMIUM_PROFILE_PATH);
       chromeArguments.push(`--user-data-dir=${temporaryUserDataDir}`);
@@ -96,8 +100,8 @@ export class Chromium implements BrowserType {
     }
 
     const usePipe = chromeArguments.includes('--remote-debugging-pipe');
-    if (usePipe && webSocket)
-      throw new Error(`Argument "--remote-debugging-pipe" is not compatible with "webSocket" launch option.`);
+    if (usePipe && isServer)
+      throw new Error(`Argument "--remote-debugging-pipe" is not compatible with the launchBrowserApp.`);
 
     let browserApp: BrowserApp | undefined = undefined;
     const { launchedProcess, gracefullyClose } = await launchProcess({
@@ -116,47 +120,33 @@ export class Chromium implements BrowserType {
         // We try to gracefully close to prevent crash reporting and core dumps.
         // Note that it's fine to reuse the pipe transport, since
         // our connection ignores kBrowserCloseMessageId.
-        const transport = await createTransport(browserApp.connectOptions());
+        const t = transport || await platform.createWebSocketTransport(browserWSEndpoint!);
         const message = { method: 'Browser.close', id: kBrowserCloseMessageId };
-        transport.send(JSON.stringify(message));
+        t.send(JSON.stringify(message));
       },
       onkill: (exitCode, signal) => {
         if (browserApp)
           browserApp.emit(Events.BrowserApp.Close, exitCode, signal);
       },
     });
 
-    let connectOptions: ConnectOptions;
-    if (!usePipe) {
+    let transport: ConnectionTransport | undefined;
+    let browserWSEndpoint: string | null;
+    if (isServer) {
       const timeoutError = new TimeoutError(`Timed out after ${timeout} ms while trying to connect to Chromium! The only Chromium revision guaranteed to work is r${this._revision}`);
       const match = await waitForLine(launchedProcess, launchedProcess.stderr, /^DevTools listening on (ws:\/\/.*)$/, timeout, timeoutError);
-      const browserWSEndpoint = match[1];
-      connectOptions = { browserWSEndpoint, slowMo };
+      browserWSEndpoint = match[1];
     } else {
-      const transport = new PipeTransport(launchedProcess.stdio[3] as NodeJS.WritableStream, launchedProcess.stdio[4] as NodeJS.ReadableStream);
-      connectOptions = { slowMo, transport };
+      transport = new PipeTransport(launchedProcess.stdio[3] as NodeJS.WritableStream, launchedProcess.stdio[4] as NodeJS.ReadableStream);
+      browserWSEndpoint = null;
     }
-    browserApp = new BrowserApp(launchedProcess, gracefullyClose, connectOptions);
-    return browserApp;
+    browserApp = new BrowserApp(launchedProcess, gracefullyClose, browserWSEndpoint);
+    return { browserApp, transport };
   }
 
-  async connect(options: ConnectOptions & { browserURL?: string }): Promise<CRBrowser> {
-    if (options.transport && options.transport.onmessage)
-      throw new Error('Transport is already in use');
-    if (options.browserURL) {
-      assert(!options.browserWSEndpoint && !options.transport, 'Exactly one of browserWSEndpoint, browserURL or transport must be passed to connect');
-      let connectionURL: string;
-      try {
-        const data = await platform.fetchUrl(new URL('/json/version', options.browserURL).href);
-        connectionURL = JSON.parse(data).webSocketDebuggerUrl;
-      } catch (e) {
-        e.message = `Failed to fetch browser webSocket url from ${options.browserURL}: ` + e.message;
-        throw e;
-      }
-      const transport = await platform.createWebSocketTransport(connectionURL);
-      options = { ...options, transport };
-    }
-    return CRBrowser.connect(options);
+  async connect(options: ConnectOptions): Promise<CRBrowser> {
+    const transport = await platform.createWebSocketTransport(options.wsEndpoint);
+    return CRBrowser.connect(transport, options.slowMo);
   }
 
   executablePath(): string {