feat(default context): support selected options for default context (#2177)

Author: dgozman

browsers.json

@@ -6,7 +6,7 @@
     },
     {
       "name": "firefox",
-      "revision": "1094"
+      "revision": "1097"
     },
     {
       "name": "webkit",

docs/api.md

@@ -4031,9 +4031,32 @@ const browser = await chromium.launch({  // Or 'firefox' or 'webkit'.
   - `env` <[Object]<[string], [string]|[number]|[boolean]>> Specify environment variables that will be visible to the browser. Defaults to `process.env`.
   - `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`.
   - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. Defaults to 0.
-- returns: <[Promise]<[BrowserContext]>> Promise which resolves to the browser app instance.
+  - `ignoreHTTPSErrors` <[boolean]> Whether to ignore HTTPS errors during navigation. Defaults to `false`.
+  - `bypassCSP` <[boolean]> Toggles bypassing page's Content-Security-Policy.
+  - `viewport` <?[Object]> Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
+    - `width` <[number]> page width in pixels.
+    - `height` <[number]> page height in pixels.
+  - `userAgent` <[string]> Specific user agent to use in this context.
+  - `deviceScaleFactor` <[number]> Specify device scale factor (can be thought of as dpr). Defaults to `1`.
+  - `isMobile` <[boolean]> Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not supported in Firefox.
+  - `hasTouch` <[boolean]> Specifies if viewport supports touch events. Defaults to false.
+  - `javaScriptEnabled` <[boolean]> Whether or not to enable JavaScript in the context. Defaults to true.
+  - `timezoneId` <[string]> Changes the timezone of the context. See [ICU’s `metaZones.txt`](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) for a list of supported timezone IDs.
+  - `geolocation` <[Object]>
+    - `latitude` <[number]> Latitude between -90 and 90.
+    - `longitude` <[number]> Longitude between -180 and 180.
+    - `accuracy` <[number]> Non-negative accuracy value. Defaults to `0`.
+  - `locale` <[string]> Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value, `Accept-Language` request header value as well as number and date formatting rules.
+  - `permissions` <[Array]<[string]>> A list of permissions to grant to all pages in this context. See [browserContext.grantPermissions](#browsercontextgrantpermissionspermissions-options) for more details.
+  - `extraHTTPHeaders` <[Object]<[string], [string]>> An object containing additional HTTP headers to be sent with every request. All header values must be strings.
+  - `offline` <[boolean]> Whether to emulate network being offline. Defaults to `false`.
+  - `httpCredentials` <[Object]> Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
+    - `username` <[string]>
+    - `password` <[string]>
+  - `colorScheme` <"dark"|"light"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See [page.emulateMedia(options)](#pageemulatemediaoptions) for more details. Defaults to '`light`'.
+- returns: <[Promise]<[BrowserContext]>> Promise that resolves to the persistent browser context instance.
 
-Launches browser instance that uses persistent storage located at `userDataDir`.
+Launches browser that uses persistent storage located at `userDataDir` and returns the only context. Closing this context will automatically close the browser.
 
 #### browserType.launchServer([options])
 - `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields:

src/browser.ts

@@ -14,22 +14,20 @@
  * limitations under the License.
  */
 
-import { BrowserContext, BrowserContextOptions, BrowserContextBase } from './browserContext';
+import { BrowserContext, BrowserContextOptions, BrowserContextBase, PersistentContextOptions } from './browserContext';
 import { Page } from './page';
 import { EventEmitter } from 'events';
 import { Download } from './download';
 import type { BrowserServer } from './server/browserServer';
 import { Events } from './events';
 import { InnerLogger, Log } from './logger';
-import * as types from './types';
 
 export type BrowserOptions = {
   logger: InnerLogger,
-  downloadsPath: string,
+  downloadsPath?: string,
   headful?: boolean,
-  persistent?: boolean,
+  persistent?: PersistentContextOptions,  // Undefined means no persistent context.
   slowMo?: number,
-  viewport?: types.Size | null,
   ownedServer?: BrowserServer,
 };
 
@@ -64,7 +62,7 @@ export abstract class BrowserBase extends EventEmitter implements Browser, Inner
   }
 
   _downloadCreated(page: Page, uuid: string, url: string, suggestedFilename?: string) {
-    const download = new Download(page, this._options.downloadsPath, uuid, url, suggestedFilename);
+    const download = new Download(page, this._options.downloadsPath || '', uuid, url, suggestedFilename);
     this._downloads.set(uuid, download);
   }
 

src/browserContext.ts

@@ -27,7 +27,7 @@ import { BrowserBase } from './browser';
 import { Log, InnerLogger, Logger, RootLogger } from './logger';
 import { FunctionWithSource } from './frames';
 
-export type BrowserContextOptions = {
+export type PersistentContextOptions = {
   viewport?: types.Size | null,
   ignoreHTTPSErrors?: boolean,
   javaScriptEnabled?: boolean,
@@ -44,6 +44,9 @@ export type BrowserContextOptions = {
   isMobile?: boolean,
   hasTouch?: boolean,
   colorScheme?: types.ColorScheme,
+};
+
+export type BrowserContextOptions = PersistentContextOptions & {
   acceptDownloads?: boolean,
   logger?: Logger,
 };
@@ -188,9 +191,15 @@ export abstract class BrowserContextBase extends ExtendedEventEmitter implements
       await this.waitForEvent('page');
     const pages = this.pages();
     await pages[0].waitForLoadState();
-    if (pages.length !== 1 || pages[0].url() !== 'about:blank') {
-      await this.close().catch(e => null);
+    if (pages.length !== 1 || pages[0].url() !== 'about:blank')
       throw new Error(`Arguments can not specify page to be opened (first url is ${pages[0].url()})`);
+    if (this._options.isMobile || this._options.locale) {
+      // Workaround for:
+      // - chromium fails to change isMobile for existing page;
+      // - webkit fails to change locale for existing page.
+      const oldPage = pages[0];
+      await this.newPage();
+      await oldPage.close();
     }
   }
 }
@@ -203,7 +212,28 @@ export function assertBrowserContextIsNotOwned(context: BrowserContextBase) {
 }
 
 export function validateBrowserContextOptions(options: BrowserContextOptions): BrowserContextOptions {
-  const result = { ...options };
+  // Copy all fields manually to strip any extra junk.
+  // Especially useful when we share context and launch options for launchPersistent.
+  const result: BrowserContextOptions = {
+    ignoreHTTPSErrors: options.ignoreHTTPSErrors,
+    bypassCSP: options.bypassCSP,
+    locale: options.locale,
+    timezoneId: options.timezoneId,
+    offline: options.offline,
+    colorScheme: options.colorScheme,
+    acceptDownloads: options.acceptDownloads,
+    viewport: options.viewport,
+    javaScriptEnabled: options.javaScriptEnabled,
+    userAgent: options.userAgent,
+    geolocation: options.geolocation,
+    permissions: options.permissions,
+    extraHTTPHeaders: options.extraHTTPHeaders,
+    httpCredentials: options.httpCredentials,
+    deviceScaleFactor: options.deviceScaleFactor,
+    isMobile: options.isMobile,
+    hasTouch: options.hasTouch,
+    logger: options.logger,
+  };
   if (result.viewport === null && result.deviceScaleFactor !== undefined)
     throw new Error(`"deviceScaleFactor" option is not supported with null "viewport"`);
   if (result.viewport === null && result.isMobile !== undefined)
@@ -219,6 +249,12 @@ export function validateBrowserContextOptions(options: BrowserContextOptions): B
   return result;
 }
 
+export function validatePersistentContextOptions(options: PersistentContextOptions): PersistentContextOptions {
+  if ((options as any).acceptDownloads !== undefined)
+    throw new Error(`Option "acceptDownloads" is not supported for persistent context`);
+  return validateBrowserContextOptions(options);
+}
+
 export function verifyGeolocation(geolocation: types.Geolocation): types.Geolocation {
   const result = { ...geolocation };
   result.accuracy = result.accuracy || 0;

src/chromium/crBrowser.ts

@@ -56,6 +56,8 @@ export class CRBrowser extends BrowserBase {
       return browser;
     }
 
+    browser._defaultContext = new CRBrowserContext(browser, null, options.persistent);
+
     const existingTargetAttachPromises: Promise<any>[] = [];
     // First page, background pages and their service workers in the persistent context
     // are created automatically and may be initialized before we enable auto-attach.
@@ -77,6 +79,7 @@ export class CRBrowser extends BrowserBase {
     await Promise.all([
       startDiscover,
       autoAttachAndStopDiscover,
+      (browser._defaultContext as CRBrowserContext)._initialize(),
     ]);
 
     // Wait for initial targets to arrive.
@@ -88,9 +91,6 @@ export class CRBrowser extends BrowserBase {
     super(options);
     this._connection = connection;
     this._session = this._connection.rootSession;
-
-    if (options.persistent)
-      this._defaultContext = new CRBrowserContext(this, null, validateBrowserContextOptions({ viewport: options.viewport }));
     this._connection.on(ConnectionEvents.Disconnected, () => {
       for (const context of this._contexts.values())
         context._browserClosed();
@@ -290,19 +290,17 @@ export class CRBrowserContext extends BrowserContextBase {
   }
 
   async _initialize() {
-    const promises: Promise<any>[] = [
-      this._browser._session.send('Browser.setDownloadBehavior', {
+    assert(!Array.from(this._browser._crPages.values()).some(page => page._browserContext === this));
+    const promises: Promise<any>[] = [];
+    if (this._browser._options.downloadsPath) {
+      promises.push(this._browser._session.send('Browser.setDownloadBehavior', {
         behavior: this._options.acceptDownloads ? 'allowAndName' : 'deny',
         browserContextId: this._browserContextId || undefined,
         downloadPath: this._browser._options.downloadsPath
-      })
-    ];
+      }));
+    }
     if (this._options.permissions)
       promises.push(this.grantPermissions(this._options.permissions));
-    if (this._options.offline)
-      promises.push(this.setOffline(this._options.offline));
-    if (this._options.httpCredentials)
-      promises.push(this.setHTTPCredentials(this._options.httpCredentials));
     await Promise.all(promises);
   }
 

src/firefox/ffBrowser.ts

@@ -37,17 +37,21 @@ export class FFBrowser extends BrowserBase {
   static async connect(transport: ConnectionTransport, options: BrowserOptions): Promise<FFBrowser> {
     const connection = new FFConnection(SlowMoTransport.wrap(transport, options.slowMo), options.logger);
     const browser = new FFBrowser(connection, options);
-    await connection.send('Browser.enable', { attachToDefaultContext: !!options.persistent });
+    const promises: Promise<any>[] = [
+      connection.send('Browser.enable', { attachToDefaultContext: !!options.persistent }),
+    ];
+    if (options.persistent) {
+      browser._defaultContext = new FFBrowserContext(browser, null, options.persistent);
+      promises.push((browser._defaultContext as FFBrowserContext)._initialize());
+    }
+    await Promise.all(promises);
     return browser;
   }
 
   constructor(connection: FFConnection, options: BrowserOptions) {
     super(options);
     this._connection = connection;
     this._ffPages = new Map();
-
-    if (options.persistent)
-      this._defaultContext = new FFBrowserContext(this, null, validateBrowserContextOptions({}));
     this._contexts = new Map();
     this._connection.on(ConnectionEvents.Disconnected, () => {
       for (const context of this._contexts.values())
@@ -151,16 +155,18 @@ export class FFBrowserContext extends BrowserContextBase {
   }
 
   async _initialize() {
+    assert(!this._ffPages().length);
     const browserContextId = this._browserContextId || undefined;
-    const promises: Promise<any>[] = [
-      this._browser._connection.send('Browser.setDownloadOptions', {
+    const promises: Promise<any>[] = [];
+    if (this._browser._options.downloadsPath) {
+      promises.push(this._browser._connection.send('Browser.setDownloadOptions', {
         browserContextId,
         downloadOptions: {
           behavior: this._options.acceptDownloads ? 'saveToDisk' : 'cancel',
           downloadsDir: this._browser._options.downloadsPath,
         },
-      }),
-    ];
+      }));
+    }
     if (this._options.viewport) {
       const viewport = {
         viewportSize: { width: this._options.viewport.width, height: this._options.viewport.height },

src/server/browserServer.ts

@@ -56,11 +56,11 @@ export class BrowserServer extends EventEmitter {
   private _webSocketWrapper: WebSocketWrapper | null = null;
   readonly _launchOptions: LaunchOptions;
   readonly _logger: RootLogger;
-  readonly _downloadsPath: string;
+  readonly _downloadsPath: string | undefined;
   readonly _transport: ConnectionTransport;
   readonly _headful: boolean;
 
-  constructor(options: LaunchOptions, process: ChildProcess, gracefullyClose: () => Promise<void>, transport: ConnectionTransport, downloadsPath: string, webSocketWrapper: WebSocketWrapper | null) {
+  constructor(options: LaunchOptions, process: ChildProcess, gracefullyClose: () => Promise<void>, transport: ConnectionTransport, downloadsPath: string | undefined, webSocketWrapper: WebSocketWrapper | null) {
     super();
     this._launchOptions = options;
     this._headful = !processBrowserArgOptions(options).headless;

src/server/browserType.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { BrowserContext } from '../browserContext';
+import { BrowserContext, PersistentContextOptions, validatePersistentContextOptions } from '../browserContext';
 import { BrowserServer } from './browserServer';
 import * as browserPaths from '../install/browserPaths';
 import { Logger, RootLogger } from '../logger';
@@ -60,7 +60,7 @@ export interface BrowserType {
   name(): string;
   launch(options?: LaunchOptions): Promise<Browser>;
   launchServer(options?: LaunchServerOptions): Promise<BrowserServer>;
-  launchPersistentContext(userDataDir: string, options?: LaunchOptions): Promise<BrowserContext>;
+  launchPersistentContext(userDataDir: string, options?: LaunchOptions & PersistentContextOptions): Promise<BrowserContext>;
   connect(options: ConnectOptions): Promise<Browser>;
 }
 
@@ -88,23 +88,24 @@ export abstract class BrowserTypeBase implements BrowserType {
 
   async launch(options: LaunchOptions = {}): Promise<Browser> {
     assert(!(options as any).userDataDir, 'userDataDir option is not supported in `browserType.launch`. Use `browserType.launchPersistentContext` instead');
-    return this._innerLaunch('local', options);
+    return this._innerLaunch('local', options, undefined);
   }
 
-  async launchPersistentContext(userDataDir: string, options: LaunchOptions = {}): Promise<BrowserContext> {
-    const browser = await this._innerLaunch('persistent', options, userDataDir);
+  async launchPersistentContext(userDataDir: string, options: LaunchOptions & PersistentContextOptions = {}): Promise<BrowserContext> {
+    const persistent = validatePersistentContextOptions(options);
+    const browser = await this._innerLaunch('persistent', options, persistent, userDataDir);
     return browser._defaultContext!;
   }
 
-  async _innerLaunch(launchType: LaunchType, options: LaunchOptions, userDataDir?: string): Promise<BrowserBase> {
+  async _innerLaunch(launchType: LaunchType, options: LaunchOptions, persistent: PersistentContextOptions | undefined, userDataDir?: string): Promise<BrowserBase> {
     const deadline = TimeoutSettings.computeDeadline(options.timeout, 30000);
     const logger = new RootLogger(options.logger);
     logger.startLaunchRecording();
 
     let browserServer: BrowserServer | undefined;
     try {
       browserServer = await this._launchServer(options, launchType, logger, deadline, userDataDir);
-      const promise = this._innerLaunchPromise(browserServer, launchType, options);
+      const promise = this._innerLaunchPromise(browserServer, options, persistent);
       const browser = await helper.waitWithDeadline(promise, 'the browser to launch', deadline, 'pw:browser*');
       return browser;
     } catch (e) {
@@ -119,12 +120,12 @@ export abstract class BrowserTypeBase implements BrowserType {
     }
   }
 
-  async _innerLaunchPromise(browserServer: BrowserServer, launchType: LaunchType, options: LaunchOptions): Promise<BrowserBase> {
+  async _innerLaunchPromise(browserServer: BrowserServer, options: LaunchOptions, persistent: PersistentContextOptions | undefined): Promise<BrowserBase> {
     if ((options as any).__testHookBeforeCreateBrowser)
       await (options as any).__testHookBeforeCreateBrowser();
 
-    const browser = await this._connectToServer(browserServer, launchType === 'persistent');
-    if (launchType === 'persistent' && (!options.ignoreDefaultArgs || Array.isArray(options.ignoreDefaultArgs))) {
+    const browser = await this._connectToServer(browserServer, persistent);
+    if (persistent && (!options.ignoreDefaultArgs || Array.isArray(options.ignoreDefaultArgs))) {
       const context = browser._defaultContext!;
       await context._loadDefaultContext();
     }
@@ -166,10 +167,10 @@ export abstract class BrowserTypeBase implements BrowserType {
   async _innerConnectPromise(transport: ConnectionTransport, options: ConnectOptions, logger: RootLogger): Promise<Browser> {
     if ((options as any).__testHookBeforeCreateBrowser)
       await (options as any).__testHookBeforeCreateBrowser();
-    return this._connectToTransport(transport, { slowMo: options.slowMo, logger, downloadsPath: '' });
+    return this._connectToTransport(transport, { slowMo: options.slowMo, logger });
   }
 
   abstract _launchServer(options: LaunchServerOptions, launchType: LaunchType, logger: RootLogger, deadline: number, userDataDir?: string): Promise<BrowserServer>;
-  abstract _connectToServer(browserServer: BrowserServer, persistent: boolean): Promise<BrowserBase>;
+  abstract _connectToServer(browserServer: BrowserServer, persistent: PersistentContextOptions | undefined): Promise<BrowserBase>;
   abstract _connectToTransport(transport: ConnectionTransport, options: BrowserOptions): Promise<BrowserBase>;
 }

src/server/chromium.ts

@@ -33,6 +33,7 @@ import { InnerLogger, logError, RootLogger } from '../logger';
 import { BrowserDescriptor } from '../install/browserPaths';
 import { CRDevTools } from '../chromium/crDevTools';
 import { BrowserBase, BrowserOptions } from '../browser';
+import { PersistentContextOptions } from '../browserContext';
 
 export class Chromium extends BrowserTypeBase {
   private _devtools: CRDevTools | undefined;
@@ -47,7 +48,7 @@ export class Chromium extends BrowserTypeBase {
     return new CRDevTools(path.join(this._browserPath, 'devtools-preferences.json'));
   }
 
-  async _connectToServer(browserServer: BrowserServer, persistent: boolean): Promise<BrowserBase> {
+  async _connectToServer(browserServer: BrowserServer, persistent: PersistentContextOptions | undefined): Promise<BrowserBase> {
     const options = browserServer._launchOptions;
     let devtools = this._devtools;
     if ((options as any).__testHookForDevTools) {