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
- */
+ */