feat(Browser): introduce browser.process() variable (#1581)

This patch adds a `browser.process()` getter to expose the child process
with running browser.

Fixes #1539.

docs/api.md

@@ -21,6 +21,7 @@
   * [browser.disconnect()](#browserdisconnect)
   * [browser.newPage()](#browsernewpage)
   * [browser.pages()](#browserpages)
+  * [browser.process()](#browserprocess)
   * [browser.targets()](#browsertargets)
   * [browser.version()](#browserversion)
   * [browser.wsEndpoint()](#browserwsendpoint)
@@ -334,6 +335,9 @@ Disconnects Puppeteer from the browser, but leaves the Chromium process running.
 #### browser.pages()
 - returns: <[Promise]<[Array]<[Page]>>> Promise which resolves to an array of all open pages.
 
+#### browser.process()
+- returns: <?[ChildProcess]> Spawned browser process. Returns `null` if the browser instance was created with `puppeteer.connect` method.
+
 #### browser.targets()
 - returns: <[Array]<[Target]>> An array of all active targets.
 
@@ -2118,6 +2122,7 @@ Identifies what kind of target this is. Can be `"page"`, `"service_worker"`, or
 [Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
 [Frame]: #class-frame "Frame"
 [ConsoleMessage]: #class-consolemessage "ConsoleMessage"
+[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
 [iterator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols "Iterator"
 [Response]: #class-response  "Response"
 [Request]: #class-request  "Request"

lib/Browser.js

@@ -22,12 +22,14 @@ class Browser extends EventEmitter {
   /**
    * @param {!Puppeteer.Connection} connection
    * @param {!Object=} options
+   * @param {?Puppeteer.ChildProcess} process
    * @param {(function():Promise)=} closeCallback
    */
-  constructor(connection, options = {}, closeCallback) {
+  constructor(connection, options = {}, process, closeCallback) {
     super();
     this._ignoreHTTPSErrors = !!options.ignoreHTTPSErrors;
     this._appMode = !!options.appMode;
+    this._process = process;
     this._screenshotTaskQueue = new TaskQueue();
     this._connection = connection;
     this._closeCallback = closeCallback || new Function();
@@ -41,13 +43,21 @@ class Browser extends EventEmitter {
     this._connection.on('Target.targetInfoChanged', this._targetInfoChanged.bind(this));
   }
 
+  /**
+   * @return {?Puppeteer.ChildProcess}
+   */
+  process() {
+    return this._process;
+  }
+
   /**
    * @param {!Puppeteer.Connection} connection
    * @param {!Object=} options
+   * @param {?Puppeteer.ChildProcess} process
    * @param {function()=} closeCallback
    */
-  static async create(connection, options, closeCallback) {
-    const browser = new Browser(connection, options, closeCallback);
+  static async create(connection, options, process, closeCallback) {
+    const browser = new Browser(connection, options, process, closeCallback);
     await connection.send('Target.setDiscoverTargets', {discover: true});
     return browser;
   }

lib/Launcher.js

@@ -136,7 +136,7 @@ class Launcher {
       const connectionDelay = options.slowMo || 0;
       const browserWSEndpoint = await waitForWSEndpoint(chromeProcess, options.timeout || 30 * 1000);
       connection = await Connection.create(browserWSEndpoint, connectionDelay);
-      return Browser.create(connection, options, killChrome);
+      return Browser.create(connection, options, chromeProcess, killChrome);
     } catch (e) {
       forceKillChrome();
       throw e;
@@ -187,7 +187,7 @@ class Launcher {
    */
   static async connect(options = {}) {
     const connection = await Connection.create(options.browserWSEndpoint);
-    return Browser.create(connection, options, () => connection.send('Browser.close'));
+    return Browser.create(connection, options, null, () => connection.send('Browser.close'));
   }
 }
 

test/test.js

@@ -263,6 +263,16 @@ describe('Page', function() {
     }));
   });
 
+  describe('Browser.process', function() {
+    it('should return child_process instance', SX(async function() {
+      const process = await browser.process();
+      expect(process.pid).toBeGreaterThan(0);
+      const browserWSEndpoint = browser.wsEndpoint();
+      const remoteBrowser = await puppeteer.connect({browserWSEndpoint});
+      expect(remoteBrowser.process()).toBe(null);
+    }));
+  });
+
   describe('Browser.Events.disconnected', function() {
     it('should emitted when: browser gets closed, disconnected or underlying websocket gets closed', SX(async function() {
       const originalBrowser = await puppeteer.launch(defaultBrowserOptions);