feat(BrowserContext): introduce Browser Contexts. (#2523)

This patch introduces Browser Contexts and methods to manage them:
- `browser.createIncognitoBrowserContext()` - to create new incognito
  context
- `browser.browserContext()` - to get all existing contexts
- `browserContext.dispose()` - to dispose incognito context.

Fixes #85.

lib/Browser.js

@@ -22,11 +22,12 @@ const TaskQueue = require('./TaskQueue');
 class Browser extends EventEmitter {
   /**
    * @param {!Puppeteer.Connection} connection
+   * @param {!Array<string>} contextIds
    * @param {!BrowserOptions=} options
    * @param {?Puppeteer.ChildProcess} process
    * @param {(function():Promise)=} closeCallback
    */
-  constructor(connection, options = {}, process, closeCallback) {
+  constructor(connection, contextIds, options = {}, process, closeCallback) {
     super();
     this._ignoreHTTPSErrors = !!options.ignoreHTTPSErrors;
     this._appMode = !!options.appMode;
@@ -34,6 +35,13 @@ class Browser extends EventEmitter {
     this._screenshotTaskQueue = new TaskQueue();
     this._connection = connection;
     this._closeCallback = closeCallback || new Function();
+
+    this._defaultContext = new BrowserContext(this, null);
+    /** @type {Map<string, BrowserContext>} */
+    this._contexts = new Map();
+    for (const contextId of contextIds)
+      this._contexts.set(contextId, new BrowserContext(this, contextId));
+
     /** @type {Map<string, Target>} */
     this._targets = new Map();
     this._connection.setClosedCallback(() => {
@@ -51,29 +59,60 @@ class Browser extends EventEmitter {
     return this._process;
   }
 
+  /**
+   * @return {!Promise<!BrowserContext>}
+   */
+  async createIncognitoBrowserContext() {
+    const {browserContextId} = await this._connection.send('Target.createBrowserContext');
+    const context = new BrowserContext(this, browserContextId);
+    this._contexts.set(browserContextId, context);
+    return context;
+  }
+
+  /**
+   * @return {!Array<!BrowserContext>}
+   */
+  browserContexts() {
+    return [this._defaultContext, ...Array.from(this._contexts.values())];
+  }
+
+  /**
+   * @param {?string} contextId
+   */
+  async _disposeContext(contextId) {
+    await this._connection.send('Target.disposeBrowserContext', {browserContextId: contextId || undefined});
+    this._contexts.delete(contextId);
+  }
+
   /**
    * @param {!Puppeteer.Connection} connection
+   * @param {!Array<string>} contextIds
    * @param {!BrowserOptions=} options
    * @param {?Puppeteer.ChildProcess} process
    * @param {function()=} closeCallback
    */
-  static async create(connection, options, process, closeCallback) {
-    const browser = new Browser(connection, options, process, closeCallback);
+  static async create(connection, contextIds, options, process, closeCallback) {
+    const browser = new Browser(connection, contextIds, options, process, closeCallback);
     await connection.send('Target.setDiscoverTargets', {discover: true});
     return browser;
   }
 
   /**
-   * @param {{targetInfo: !Puppeteer.TargetInfo}} event
+   * @param {!Protocol.Target.targetCreatedPayload} event
    */
   async _targetCreated(event) {
     const targetInfo = event.targetInfo;
-    const target = new Target(targetInfo, this, () => this._connection.createSession(targetInfo.targetId), this._ignoreHTTPSErrors, !this._appMode, this._screenshotTaskQueue);
+    const {browserContextId} = targetInfo;
+    const context = (browserContextId && this._contexts.has(browserContextId)) ? this._contexts.get(browserContextId) : this._defaultContext;
+
+    const target = new Target(targetInfo, context, () => this._connection.createSession(targetInfo.targetId), this._ignoreHTTPSErrors, !this._appMode, this._screenshotTaskQueue);
     console.assert(!this._targets.has(event.targetInfo.targetId), 'Target should not exist before targetCreated');
     this._targets.set(event.targetInfo.targetId, target);
 
-    if (await target._initializedPromise)
+    if (await target._initializedPromise) {
       this.emit(Browser.Events.TargetCreated, target);
+      context.emit(BrowserContext.Events.TargetCreated, target);
+    }
   }
 
   /**
@@ -84,12 +123,14 @@ class Browser extends EventEmitter {
     target._initializedCallback(false);
     this._targets.delete(event.targetId);
     target._closedCallback();
-    if (await target._initializedPromise)
+    if (await target._initializedPromise) {
       this.emit(Browser.Events.TargetDestroyed, target);
+      target.browserContext().emit(BrowserContext.Events.TargetDestroyed, target);
+    }
   }
 
   /**
-   * @param {{targetInfo: !Puppeteer.TargetInfo}} event
+   * @param {!Protocol.Target.targetInfoChangedPayload} event
    */
   _targetInfoChanged(event) {
     const target = this._targets.get(event.targetInfo.targetId);
@@ -97,8 +138,10 @@ class Browser extends EventEmitter {
     const previousURL = target.url();
     const wasInitialized = target._isInitialized;
     target._targetInfoChanged(event.targetInfo);
-    if (wasInitialized && previousURL !== target.url())
+    if (wasInitialized && previousURL !== target.url()) {
       this.emit(Browser.Events.TargetChanged, target);
+      target.browserContext().emit(BrowserContext.Events.TargetChanged, target);
+    }
   }
 
   /**
@@ -112,7 +155,15 @@ class Browser extends EventEmitter {
    * @return {!Promise<!Puppeteer.Page>}
    */
   async newPage() {
-    const {targetId} = await this._connection.send('Target.createTarget', {url: 'about:blank'});
+    return this._defaultContext.newPage();
+  }
+
+  /**
+   * @param {string} contextId
+   * @return {!Promise<!Puppeteer.Page>}
+   */
+  async _createPageInContext(contextId) {
+    const {targetId} = await this._connection.send('Target.createTarget', {url: 'about:blank', browserContextId: contextId || undefined});
     const target = await this._targets.get(targetId);
     console.assert(await target._initializedPromise, 'Failed to create target for page');
     const page = await target.page();
@@ -175,12 +226,65 @@ Browser.Events = {
   Disconnected: 'disconnected'
 };
 
+class BrowserContext extends EventEmitter {
+  /**
+   * @param {!Browser} browser
+   * @param {?string} contextId
+   */
+  constructor(browser, contextId) {
+    super();
+    this._browser = browser;
+    this._id = contextId;
+  }
+
+  /**
+   * @return {!Array<!Target>} target
+   */
+  targets() {
+    return this._browser.targets().filter(target => target.browserContext() === this);
+  }
+
+  /**
+   * @return {boolean}
+   */
+  isIncognito() {
+    return !!this._id;
+  }
+
+  /**
+   * @return {!Promise<!Puppeteer.Page>}
+   */
+  newPage() {
+    return this._browser._createPageInContext(this._id);
+  }
+
+  /**
+   * @return {!Browser}
+   */
+  browser() {
+    return this._browser;
+  }
+
+  async close() {
+    console.assert(this._id, 'Non-incognito profiles cannot be closed!');
+    await this._browser._disposeContext(this._id);
+  }
+}
+
+/** @enum {string} */
+BrowserContext.Events = {
+  TargetCreated: 'targetcreated',
+  TargetDestroyed: 'targetdestroyed',
+  TargetChanged: 'targetchanged',
+};
+
+helper.tracePublicAPI(BrowserContext);
 helper.tracePublicAPI(Browser);
 
-module.exports = Browser;
+module.exports = {Browser, BrowserContext};
 
 /**
  * @typedef {Object} BrowserOptions
  * @property {boolean=} appMode
  * @property {boolean=} ignoreHTTPSErrors
- */
+ */

lib/Launcher.js

@@ -19,7 +19,7 @@ const removeFolder = require('rimraf');
 const childProcess = require('child_process');
 const BrowserFetcher = require('./BrowserFetcher');
 const {Connection} = require('./Connection');
-const Browser = require('./Browser');
+const {Browser} = require('./Browser');
 const readline = require('readline');
 const fs = require('fs');
 const {helper, debugError} = require('./helper');
@@ -159,7 +159,7 @@ class Launcher {
       } else {
         connection = Connection.createForPipe(/** @type {!NodeJS.WritableStream} */(chromeProcess.stdio[3]), /** @type {!NodeJS.ReadableStream} */ (chromeProcess.stdio[4]), connectionDelay);
       }
-      return Browser.create(connection, options, chromeProcess, gracefullyCloseChrome);
+      return Browser.create(connection, [], options, chromeProcess, gracefullyCloseChrome);
     } catch (e) {
       killChrome();
       throw e;
@@ -226,7 +226,8 @@ class Launcher {
   static async connect(options = {}) {
     const connectionDelay = options.slowMo || 0;
     const connection = await Connection.createForWebSocket(options.browserWSEndpoint, connectionDelay);
-    return Browser.create(connection, options, null, () => connection.send('Browser.close').catch(debugError));
+    const {browserContextIds} = await connection.send('Target.getBrowserContexts');
+    return Browser.create(connection, browserContextIds, options, null, () => connection.send('Browser.close').catch(debugError));
   }
 }
 

lib/Target.js

@@ -3,16 +3,16 @@ const {helper} = require('./helper');
 
 class Target {
   /**
-   * @param {!Puppeteer.TargetInfo} targetInfo
-   * @param {!Puppeteer.Browser} browser
+   * @param {!Protocol.Target.TargetInfo} targetInfo
+   * @param {!Puppeteer.BrowserContext} browserContext
    * @param {!function():!Promise<!Puppeteer.CDPSession>} sessionFactory
    * @param {boolean} ignoreHTTPSErrors
    * @param {boolean} setDefaultViewport
    * @param {!Puppeteer.TaskQueue} screenshotTaskQueue
    */
-  constructor(targetInfo, browser, sessionFactory, ignoreHTTPSErrors, setDefaultViewport, screenshotTaskQueue) {
+  constructor(targetInfo, browserContext, sessionFactory, ignoreHTTPSErrors, setDefaultViewport, screenshotTaskQueue) {
     this._targetInfo = targetInfo;
-    this._browser = browser;
+    this._browserContext = browserContext;
     this._targetId = targetInfo.targetId;
     this._sessionFactory = sessionFactory;
     this._ignoreHTTPSErrors = ignoreHTTPSErrors;
@@ -66,11 +66,18 @@ class Target {
    * @return {!Puppeteer.Browser}
    */
   browser() {
-    return this._browser;
+    return this._browserContext.browser();
   }
 
   /**
-   * @param {!Puppeteer.TargetInfo} targetInfo
+   * @return {!Puppeteer.BrowserContext}
+   */
+  browserContext() {
+    return this._browserContext;
+  }
+
+  /**
+   * @param {!Protocol.Target.TargetInfo} targetInfo
    */
   _targetInfoChanged(targetInfo) {
     this._targetInfo = targetInfo;

lib/externs.d.ts

@@ -1,5 +1,5 @@
 import { Connection as RealConnection, CDPSession as RealCDPSession } from './Connection.js';
-import * as RealBrowser from './Browser.js';
+import { Browser as RealBrowser, BrowserContext as RealBrowserContext} from './Browser.js';
 import * as RealTarget from './Target.js';
 import * as RealPage from './Page.js';
 import * as RealTaskQueue from './TaskQueue.js';
@@ -21,6 +21,7 @@ declare global {
     export class Touchscreen extends RealTouchscreen {}
     export class TaskQueue extends RealTaskQueue {}
     export class Browser extends RealBrowser {}
+    export class BrowserContext extends RealBrowserContext {}
     export class Target extends RealTarget {}
     export class Frame extends RealFrame {}
     export class FrameManager extends RealFrameManager {}
@@ -37,15 +38,7 @@ declare global {
       close();
     }
 
-    export interface TargetInfo {
-      type: string;
-      targetId: string;
-      title: string;
-      url: string;
-      attached: boolean;
-    }
-
     export interface ChildProcess extends child_process.ChildProcess {}
 
   }
-}
+}