feat(launch): introduce client, server & persistent launch modes (2) (#840)

Author: pavelfeldman

README.md

@@ -40,9 +40,7 @@ const playwright = require('playwright');
 (async () => {
   for (const browserType of ['chromium', 'firefox', 'webkit']) {
     const browser = await playwright[browserType].launch();
-    const context = await browser.newContext();
-    const page = await context.newPage('http://whatsmyuseragent.org/');
-
+    const page = await browser.newPage('http://whatsmyuseragent.org/');
     await page.screenshot({ path: `example-${browserType}.png` });
     await browser.close();
   }
@@ -59,14 +57,13 @@ const iPhone11 = devices['iPhone 11 Pro'];
 
 (async () => {
   const browser = await webkit.launch();
-  const context = await browser.newContext({
+  const page = await browser.newPage('https://maps.google.com', {
     viewport: iPhone11.viewport,
     userAgent: iPhone11.userAgent,
     geolocation: { longitude: 12.492507, latitude: 41.889938 },
     permissions: { 'https://www.google.com': ['geolocation'] }
   });
 
-  const page = await context.newPage('https://maps.google.com');
   await page.click('text="Your location"');
   await page.waitForRequest(/.*preview\/pwa/);
   await page.screenshot({ path: 'colosseum-iphone.png' });
@@ -82,14 +79,12 @@ const pixel2 = devices['Pixel 2'];
 
 (async () => {
   const browser = await chromium.launch();
-  const context = await browser.newContext({
+  const page = await browser.newPage('https://maps.google.com', {
     viewport: pixel2.viewport,
     userAgent: pixel2.userAgent,
     geolocation: { longitude: 12.492507, latitude: 41.889938 },
     permissions: { 'https://www.google.com': ['geolocation'] }
   });
-
-  const page = await context.newPage('https://maps.google.com');
   await page.click('text="Your location"');
   await page.waitForRequest(/.*pwa\/net.js.*/);
   await page.screenshot({ path: 'colosseum-android.png' });
@@ -106,10 +101,7 @@ const { firefox } = require('playwright');
 
 (async () => {
   const browser = await firefox.launch();
-  const context = await browser.newContext();
-  const page = await context.newPage();
-
-  await page.goto('https://www.example.com/');
+  const page = await browser.newPage('https://www.example.com/');
   const dimensions = await page.evaluate(() => {
     return {
       width: document.documentElement.clientWidth,

docs/api.md

@@ -37,4 +37,4 @@ export { FFBrowser as FirefoxBrowser } from './firefox/ffBrowser';
 export { WKBrowser as WebKitBrowser } from './webkit/wkBrowser';
 
 export { BrowserType } from './server/browserType';
-export { BrowserApp } from './server/browserApp';
+export { BrowserServer } from './server/browserServer';

src/api.ts

@@ -16,12 +16,13 @@
 
 import { BrowserContext, BrowserContextOptions } from './browserContext';
 import * as platform from './platform';
+import { Page } from './page';
 
 export interface Browser extends platform.EventEmitterType {
   newContext(options?: BrowserContextOptions): Promise<BrowserContext>;
   browserContexts(): BrowserContext[];
-  defaultContext(): BrowserContext;
-
+  pages(): Promise<Page[]>;
+  newPage(url?: string, options?: BrowserContextOptions): Promise<Page>;
   disconnect(): Promise<void>;
   isConnected(): boolean;
   close(): Promise<void>;
@@ -31,3 +32,15 @@ export type ConnectOptions = {
   slowMo?: number,
   wsEndpoint: string
 };
+
+export async function collectPages(browser: Browser): Promise<Page[]> {
+  const result: Promise<Page[]>[] = [];
+  for (const browserContext of browser.browserContexts())
+    result.push(browserContext.pages());
+  const pages: Page[] = [];
+  for (const group of await Promise.all(result))
+    pages.push(...group);
+  return pages;
+}
+
+export type LaunchType = 'local' | 'server' | 'persistent';

src/browser.ts

@@ -24,7 +24,7 @@ import { Page, Worker } from '../page';
 import { CRTarget } from './crTarget';
 import { Protocol } from './protocol';
 import { CRPage } from './crPage';
-import { Browser } from '../browser';
+import { Browser, collectPages } from '../browser';
 import * as network from '../network';
 import * as types from '../types';
 import * as platform from '../platform';
@@ -34,7 +34,7 @@ import { ConnectionTransport, SlowMoTransport } from '../transport';
 export class CRBrowser extends platform.EventEmitter implements Browser {
   _connection: CRConnection;
   _client: CRSession;
-  private _defaultContext: BrowserContext;
+  readonly _defaultContext: BrowserContext;
   private _contexts = new Map<string, BrowserContext>();
   _targets = new Map<string, CRTarget>();
 
@@ -165,11 +165,16 @@ export class CRBrowser extends platform.EventEmitter implements Browser {
   }
 
   browserContexts(): BrowserContext[] {
-    return [this._defaultContext, ...Array.from(this._contexts.values())];
+    return Array.from(this._contexts.values());
   }
 
-  defaultContext(): BrowserContext {
-    return this._defaultContext;
+  async pages(): Promise<Page[]> {
+    return collectPages(this);
+  }
+
+  async newPage(url?: string, options?: BrowserContextOptions): Promise<Page> {
+    const browserContext = await this.newContext(options);
+    return browserContext.newPage(url);
   }
 
   async _targetCreated(event: Protocol.Target.targetCreatedPayload) {

src/chromium/crBrowser.ts

@@ -20,7 +20,7 @@ export const Events = {
     Disconnected: 'disconnected'
   },
 
-  BrowserApp: {
+  BrowserServer: {
     Close: 'close',
   },
 

src/events.ts

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 
-import { Browser } from '../browser';
+import { Browser, collectPages } from '../browser';
 import { BrowserContext, BrowserContextOptions } from '../browserContext';
 import { Events } from '../events';
 import { assert, helper, RegisteredListener } from '../helper';
@@ -31,7 +31,7 @@ import { ConnectionTransport, SlowMoTransport } from '../transport';
 export class FFBrowser extends platform.EventEmitter implements Browser {
   _connection: FFConnection;
   _targets: Map<string, Target>;
-  private _defaultContext: BrowserContext;
+  readonly _defaultContext: BrowserContext;
   private _contexts: Map<string, BrowserContext>;
   private _eventListeners: RegisteredListener[];
 
@@ -84,12 +84,17 @@ export class FFBrowser extends platform.EventEmitter implements Browser {
     return context;
   }
 
-  browserContexts(): Array<BrowserContext> {
-    return [this._defaultContext, ...Array.from(this._contexts.values())];
+  browserContexts(): BrowserContext[] {
+    return Array.from(this._contexts.values());
   }
 
-  defaultContext() {
-    return this._defaultContext;
+  async pages(): Promise<Page[]> {
+    return collectPages(this);
+  }
+
+  async newPage(url?: string, options?: BrowserContextOptions): Promise<Page> {
+    const browserContext = await this.newContext(options);
+    return browserContext.newPage(url);
   }
 
   async _waitForTarget(predicate: (target: Target) => boolean, options: { timeout?: number; } = {}): Promise<Target> {

src/firefox/ffBrowser.ts

@@ -17,7 +17,7 @@
 import { ChildProcess, execSync } from 'child_process';
 import * as platform from '../platform';
 
-export class BrowserApp extends platform.EventEmitter {
+export class BrowserServer extends platform.EventEmitter {
   private _process: ChildProcess;
   private _gracefullyClose: () => Promise<void>;
   private _browserWSEndpoint: string | null = null;

src/server/browserApp.ts renamed to src/server/browserServer.ts

@@ -17,12 +17,12 @@
 import * as types from '../types';
 import { TimeoutError } from '../errors';
 import { Browser, ConnectOptions } from '../browser';
-import { BrowserApp } from './browserApp';
+import { BrowserContext } from '../browserContext';
+import { BrowserServer } from './browserServer';
 
 export type BrowserArgOptions = {
   headless?: boolean,
   args?: string[],
-  userDataDir?: string,
   devtools?: boolean,
 };
 
@@ -40,8 +40,9 @@ export type LaunchOptions = BrowserArgOptions & {
 export interface BrowserType {
   executablePath(): string;
   name(): string;
-  launchBrowserApp(options?: LaunchOptions): Promise<BrowserApp>;
   launch(options?: LaunchOptions & { slowMo?: number }): Promise<Browser>;
+  launchServer(options?: LaunchOptions & { port?: number }): Promise<BrowserServer>;
+  launchPersistent(options?: LaunchOptions & { userDataDir: string }): Promise<BrowserContext>;
   defaultArgs(options?: BrowserArgOptions): string[];
   connect(options: ConnectOptions): Promise<Browser>;
   devices: types.Devices;

src/server/browserType.ts

@@ -30,10 +30,11 @@ import { launchProcess, waitForLine } from '../server/processLauncher';
 import { kBrowserCloseMessageId } from '../chromium/crConnection';
 import { PipeTransport } from './pipeTransport';
 import { LaunchOptions, BrowserArgOptions, BrowserType } from './browserType';
-import { ConnectOptions } from '../browser';
-import { BrowserApp } from './browserApp';
+import { ConnectOptions, LaunchType } from '../browser';
+import { BrowserServer } from './browserServer';
 import { Events } from '../events';
 import { ConnectionTransport } from '../transport';
+import { BrowserContext } from '../browserContext';
 
 export class Chromium implements BrowserType {
   private _projectRoot: string;
@@ -49,19 +50,28 @@ export class Chromium implements BrowserType {
   }
 
   async launch(options?: LaunchOptions & { slowMo?: number }): Promise<CRBrowser> {
-    const { browserApp, transport } = await this._launchBrowserApp(options, false);
+    const { browserServer, transport } = await this._launchServer(options, 'local');
     const browser = await CRBrowser.connect(transport!, options && options.slowMo);
     // Hack: for typical launch scenario, ensure that close waits for actual process termination.
-    browser.close = () => browserApp.close();
-    (browser as any)['__app__'] = browserApp;
+    browser.close = () => browserServer.close();
+    (browser as any)['__server__'] = browserServer;
     return browser;
   }
 
-  async launchBrowserApp(options?: LaunchOptions): Promise<BrowserApp> {
-    return (await this._launchBrowserApp(options, true)).browserApp;
+  async launchServer(options?: LaunchOptions & { port?: number }): Promise<BrowserServer> {
+    return (await this._launchServer(options, 'server', undefined, options && options.port)).browserServer;
   }
 
-  async _launchBrowserApp(options: LaunchOptions = {}, isServer: boolean): Promise<{ browserApp: BrowserApp, transport?: ConnectionTransport }> {
+  async launchPersistent(options?: LaunchOptions & { userDataDir?: string }): Promise<BrowserContext> {
+    const { browserServer, transport } = await this._launchServer(options, 'persistent', options && options.userDataDir);
+    const browser = await CRBrowser.connect(transport!);
+    // Hack: for typical launch scenario, ensure that close waits for actual process termination.
+    const browserContext = browser._defaultContext;
+    browserContext.close = () => browserServer.close();
+    return browserContext;
+  }
+
+  private async _launchServer(options: LaunchOptions = {}, launchType: LaunchType, userDataDir?: string, port?: number): Promise<{ browserServer: BrowserServer, transport?: ConnectionTransport }> {
     const {
       ignoreDefaultArgs = false,
       args = [],
@@ -82,14 +92,19 @@ export class Chromium implements BrowserType {
     else
       chromeArguments.push(...args);
 
-    let temporaryUserDataDir: string | null = null;
+    const userDataDirArg = chromeArguments.find(arg => arg.startsWith('--user-data-dir='));
+    if (userDataDirArg)
+      throw new Error('Pass userDataDir parameter instead of specifying --user-data-dir argument');
+    if (chromeArguments.find(arg => arg.startsWith('--remote-debugging-')))
+      throw new Error('Can\' use --remote-debugging-* args. Playwright manages remote debugging connection itself');
 
-    if (!chromeArguments.some(argument => argument.startsWith('--remote-debugging-')))
-      chromeArguments.push(isServer ? '--remote-debugging-port=0' : '--remote-debugging-pipe');
-    if (!chromeArguments.some(arg => arg.startsWith('--user-data-dir'))) {
+    let temporaryUserDataDir: string | null = null;
+    if (!userDataDir) {
+      userDataDir = await mkdtempAsync(CHROMIUM_PROFILE_PATH);
       temporaryUserDataDir = await mkdtempAsync(CHROMIUM_PROFILE_PATH);
-      chromeArguments.push(`--user-data-dir=${temporaryUserDataDir}`);
     }
+    chromeArguments.push(`--user-data-dir=${userDataDir}`);
+    chromeArguments.push(launchType === 'server' ? `--remote-debugging-port=${port || 0}` : '--remote-debugging-pipe');
 
     let chromeExecutable = executablePath;
     if (!executablePath) {
@@ -99,11 +114,7 @@ export class Chromium implements BrowserType {
       chromeExecutable = executablePath;
     }
 
-    const usePipe = chromeArguments.includes('--remote-debugging-pipe');
-    if (usePipe && isServer)
-      throw new Error(`Argument "--remote-debugging-pipe" is not compatible with the launchBrowserApp.`);
-
-    let browserApp: BrowserApp | undefined = undefined;
+    let browserServer: BrowserServer | undefined = undefined;
     const { launchedProcess, gracefullyClose } = await launchProcess({
       executablePath: chromeExecutable!,
       args: chromeArguments,
@@ -112,10 +123,10 @@ export class Chromium implements BrowserType {
       handleSIGTERM,
       handleSIGHUP,
       dumpio,
-      pipe: usePipe,
+      pipe: launchType !== 'server',
       tempDir: temporaryUserDataDir || undefined,
       attemptToGracefullyClose: async () => {
-        if (!browserApp)
+        if (!browserServer)
           return Promise.reject();
         // We try to gracefully close to prevent crash reporting and core dumps.
         // Note that it's fine to reuse the pipe transport, since
@@ -125,23 +136,23 @@ export class Chromium implements BrowserType {
         t.send(JSON.stringify(message));
       },
       onkill: (exitCode, signal) => {
-        if (browserApp)
-          browserApp.emit(Events.BrowserApp.Close, exitCode, signal);
+        if (browserServer)
+          browserServer.emit(Events.BrowserServer.Close, exitCode, signal);
       },
     });
 
     let transport: ConnectionTransport | undefined;
     let browserWSEndpoint: string | null;
-    if (isServer) {
+    if (launchType === 'server') {
       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);
       browserWSEndpoint = match[1];
     } else {
       transport = new PipeTransport(launchedProcess.stdio[3] as NodeJS.WritableStream, launchedProcess.stdio[4] as NodeJS.ReadableStream);
       browserWSEndpoint = null;
     }
-    browserApp = new BrowserApp(launchedProcess, gracefullyClose, browserWSEndpoint);
-    return { browserApp, transport };
+    browserServer = new BrowserServer(launchedProcess, gracefullyClose, browserWSEndpoint);
+    return { browserServer, transport };
   }
 
   async connect(options: ConnectOptions): Promise<CRBrowser> {
@@ -166,11 +177,8 @@ export class Chromium implements BrowserType {
       devtools = false,
       headless = !devtools,
       args = [],
-      userDataDir = null
     } = options;
     const chromeArguments = [...DEFAULT_ARGS];
-    if (userDataDir)
-      chromeArguments.push(`--user-data-dir=${userDataDir}`);
     if (devtools)
       chromeArguments.push('--auto-open-devtools-for-tabs');
     if (headless) {