Improve handling of connection with remote browser using Puppeteer (#1402)

* Disconnect from remote browser instead of terminating running instance.

* Ensure clean session on remote browser by closing any open pages once connected to endpoint.

* Abort running of tests when connection with remote browser was lost.

* Display error message when unable to connect with remote browser.

* Update Puppeteer helper documentation for connecting with remote browser using websocket.

* Restored 'test-helpers' service in order to easily run helper tests locally in Docker.

* Added tests to cover Puppeteer helper behavior when connected to remote browser.

* Rely on protocol error when connection was lost instead of listening for 'disconnected' event.
Considering it is not possible to unbind event handler using '.off' until node version 10.

* Move tests for remote browser behavior to main Puppeteer test file.
Avoiding unnecessary multiple execution of unit/runner tests with Puppeteer helper.

Author: martomo

docs/helpers/Puppeteer.md

@@ -5,7 +5,7 @@
 **Extends Helper**
 
 Uses [Google Chrome's Puppeteer][1] library to run tests inside headless Chrome.
-Browser control is executed via DevTools without Selenium.
+Browser control is executed via DevTools Protocol (instead of Selenium).
 This helper works with a browser out of the box with no additional tools required to install.
 
 Requires `puppeteer` package to be installed.
@@ -27,10 +27,9 @@ This helper should be configured in codecept.json or codecept.conf.js
 -   `getPageTimeout` (optional, default: '0') config option to set maximum navigation time in milliseconds.
 -   `waitForTimeout`: (optional) default wait\* timeout in ms. Default: 1000.
 -   `windowSize`: (optional) default window size. Set a dimension like `640x480`.
--   `WSEndpoint`: (optional) Chrome websocket URL to use remote browser
 -   `userAgent`: (optional) user-agent string.
 -   `manualStart`: (optional, default: false) - do not start browser before a test, start it manually inside a helper with `this.helpers["Puppeteer"]._startBrowser()`.
--   `chrome`: (optional) pass additional [Puppeteer run options][3]. Example
+-   `chrome`: (optional) pass additional [Puppeteer run options][3].
 
 #### Example #1: Wait for 0 network connections.
 
@@ -75,15 +74,23 @@ This helper should be configured in codecept.json or codecept.conf.js
 }
 ```
 
-#### Example #4: Using remote WS endpoint
+#### Example #4: Connect to remote browser by specifying [websocket endpoint][4]
 
-```js
-"chrome": {
-  "executablePath" : "/path/to/Chrome",
-  "browserWSEndpoint": "ws://localhost:3000"
+```json
+{
+   "helpers": {
+     "Puppeteer" : {
+       "url": "http://localhost",
+       "chrome": {
+         "browserWSEndpoint": "ws://localhost:9222/devtools/browser/c5aa6160-b5bc-4d53-bb49-6ecb36cd2e0a"
+       }
+     }
+   }
 }
 ```
 
+Note: When connecting to remote browser `show` and specific `chrome` options (e.g. `headless` or `devtools`) are ignored.
+
 ## Access From Helpers
 
 Receive Puppeteer client from a custom helper by accessing `browser` for the Browser object or `page` for the current Page object:
@@ -169,13 +176,13 @@ Set current page
 
 #### Parameters
 
--   `page` **[object][4]** page to set
+-   `page` **[object][5]** page to set
 
 ### acceptPopup
 
 Accepts the active JavaScript native popup window, as created by window.alert|window.confirm|window.prompt.
 Don't confuse popups with modal windows, as created by [various
-libraries][5].
+libraries][6].
 
 ### amAcceptingPopups
 
@@ -494,7 +501,7 @@ I.dragSlider('#slider', -70);
 Executes async script on page.
 Provided function should execute a passed callback (as first argument) to signal it is finished.
 
-Example: In Vue.js to make components completely rendered we are waiting for [nextTick][6].
+Example: In Vue.js to make components completely rendered we are waiting for [nextTick][7].
 
 ```js
 I.executeAsyncScript(function(done) {
@@ -766,7 +773,7 @@ I.openNewTab();
 ### pressKey
 
 Presses a key on a focused element.
-Special keys like 'Enter', 'Control', [etc][7]
+Special keys like 'Enter', 'Control', [etc][8]
 will be replaced with corresponding unicode.
 If modifier key is used (Control, Command, Alt, Shift) in array, it will be released afterwards.
 
@@ -1385,10 +1392,12 @@ I.waitUrlEquals('http://127.0.0.1:8000/info');
 
 [3]: https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions
 
-[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[4]: https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target
+
+[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-[5]: http://jster.net/category/windows-modals-popups
+[6]: http://jster.net/category/windows-modals-popups
 
-[6]: https://vuejs.org/v2/api/#Vue-nextTick
+[7]: https://vuejs.org/v2/api/#Vue-nextTick
 
-[7]: https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/element/:id/value
+[8]: https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/element/:id/value

lib/helper/Puppeteer.js

@@ -22,6 +22,7 @@ const {
 } = require('../colorUtils');
 const path = require('path');
 const ElementNotFound = require('./errors/ElementNotFound');
+const RemoteBrowserConnectionRefused = require('./errors/RemoteBrowserConnectionRefused');
 const Popup = require('./extras/Popup');
 const Console = require('./extras/Console');
 
@@ -32,7 +33,7 @@ const consoleLogStore = new Console();
 
 /**
  * Uses [Google Chrome's Puppeteer](https://github.com/GoogleChrome/puppeteer) library to run tests inside headless Chrome.
- * Browser control is executed via DevTools without Selenium.
+ * Browser control is executed via DevTools Protocol (instead of Selenium).
  * This helper works with a browser out of the box with no additional tools required to install.
  *
  * Requires `puppeteer` package to be installed.
@@ -54,10 +55,9 @@ const consoleLogStore = new Console();
  * * `getPageTimeout` (optional, default: '0') config option to set maximum navigation time in milliseconds.
  * * `waitForTimeout`: (optional) default wait* timeout in ms. Default: 1000.
  * * `windowSize`: (optional) default window size. Set a dimension like `640x480`.
- * * `WSEndpoint`: (optional) Chrome websocket URL to use remote browser
  * * `userAgent`: (optional) user-agent string.
  * * `manualStart`: (optional, default: false) - do not start browser before a test, start it manually inside a helper with `this.helpers["Puppeteer"]._startBrowser()`.
- * * `chrome`: (optional) pass additional [Puppeteer run options](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions). Example
+ * * `chrome`: (optional) pass additional [Puppeteer run options](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions).
  *
  *
  * #### Example #1: Wait for 0 network connections.
@@ -103,14 +103,22 @@ const consoleLogStore = new Console();
  * }
  * ```
  *
- * #### Example #4: Using remote WS endpoint
+ * #### Example #4: Connect to remote browser by specifying [websocket endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target)
  *
- * ```js
- * "chrome": {
-  *   "executablePath" : "/path/to/Chrome",
-  *   "browserWSEndpoint": "ws://localhost:3000"
-  * }
-  * ```
+ * ```json
+ * {
+ *    "helpers": {
+ *      "Puppeteer" : {
+ *        "url": "http://localhost",
+ *        "chrome": {
+ *          "browserWSEndpoint": "ws://localhost:9222/devtools/browser/c5aa6160-b5bc-4d53-bb49-6ecb36cd2e0a"
+ *        }
+ *      }
+ *    }
+ * }
+ * ```
+ *
+ * Note: When connecting to remote browser `show` and specific `chrome` options (e.g. `headless` or `devtools`) are ignored.
  *
  * ## Access From Helpers
  *
@@ -132,7 +140,7 @@ class Puppeteer extends Helper {
     puppeteer = requireg('puppeteer');
 
     // set defaults
-
+    this.isRemoteBrowser = false;
     this.isRunning = false;
 
     // override defaults with config
@@ -162,6 +170,7 @@ class Puppeteer extends Helper {
   _setConfig(config) {
     this.options = this._validateConfig(config);
     this.puppeteerOptions = Object.assign({ headless: !this.options.show }, this.options.chrome);
+    this.isRemoteBrowser = !!this.puppeteerOptions.browserWSEndpoint;
     popupStore.defaultAction = this.options.defaultPopupAction;
   }
 
@@ -384,7 +393,23 @@ class Puppeteer extends Helper {
   }
 
   async _startBrowser() {
-    this.browser = this.puppeteerOptions.browserWSEndpoint ? await puppeteer.connect(this.puppeteerOptions) : await puppeteer.launch(this.puppeteerOptions);
+    if (this.isRemoteBrowser) {
+      try {
+        this.browser = await puppeteer.connect(this.puppeteerOptions);
+      } catch (err) {
+        if (err.toString().indexOf('ECONNREFUSED')) {
+          throw new RemoteBrowserConnectionRefused(err);
+        }
+        throw err;
+      }
+
+      // Clear any prior existing pages when connecting to remote websocket
+      await this.browser.newPage();
+      await this.closeOtherTabs();
+    } else {
+      this.browser = await puppeteer.launch(this.puppeteerOptions);
+    }
+
     this.browser.on('targetcreated', target => target.page().then(page => targetCreatedHandler.call(this, page)));
     this.browser.on('targetchanged', (target) => {
       this.debugSection('Url', target.url());
@@ -416,7 +441,11 @@ class Puppeteer extends Helper {
     this._setPage(null);
     this.context = null;
     popupStore.clear();
-    await this.browser.close();
+    if (this.isRemoteBrowser) {
+      await this.browser.disconnect();
+    } else {
+      await this.browser.close();
+    }
   }
 
   async _evaluateHandeInContext(...args) {

lib/helper/errors/RemoteBrowserConnectionRefused.js

@@ -0,0 +1,9 @@
+function RemoteBrowserConnectionRefused(err) {
+  this.message = 'Cannot connect to websocket endpoint.\n\n';
+  this.message += 'Please make sure remote browser is running and accessible.';
+  this.stack = err.error || err;
+}
+
+RemoteBrowserConnectionRefused.prototype = Object.create(Error.prototype);
+
+module.exports = RemoteBrowserConnectionRefused;

test/docker-compose.yml

@@ -9,6 +9,20 @@ services:
       - ..:/codecept
       - node_modules:/codecept/node_modules
 
+  test-helpers:
+    build: ..
+    entrypoint: /codecept/node_modules/.bin/mocha --invert --fgrep Appium
+    command: test/helper
+    working_dir: /codecept
+    env_file: .env
+    depends_on:
+      - selenium.chrome
+      - php
+      - json_server
+    volumes:
+      - ..:/codecept
+      - node_modules:/codecept/node_modules
+
   test-rest:
     build: ..
     entrypoint: /codecept/node_modules/.bin/mocha

test/helper/Puppeteer_test.js

@@ -1,5 +1,6 @@
 const TestHelper = require('../support/TestHelper');
 const Puppeteer = require('../../lib/helper/Puppeteer');
+const puppeteer = require('puppeteer');
 const should = require('chai').should();
 const assert = require('assert');
 const path = require('path');
@@ -558,3 +559,103 @@ describe('Puppeteer', function () {
     });
   });
 });
+
+let remoteBrowser;
+async function createRemoteBrowser() {
+  if (remoteBrowser) {
+    await remoteBrowser.close();
+  }
+  remoteBrowser = await puppeteer.launch({
+    args: ['--no-sandbox', '--disable-setuid-sandbox'],
+    headless: true,
+  });
+  remoteBrowser.on('disconnected', () => {
+    remoteBrowser = null;
+  });
+  return remoteBrowser;
+}
+
+const helperConfig = {
+  chrome: {
+    browserWSEndpoint: 'ws://localhost:9222/devtools/browser/<id>',
+    // Following options are ignored with remote browser
+    headless: false,
+    devtools: true,
+  },
+  // Important in order to handle remote browser state before starting/stopping browser
+  manualStart: true,
+  url: siteUrl,
+  waitForTimeout: 5000,
+  waitForAction: 500,
+  windowSize: '500x700',
+};
+
+describe('Puppeteer (remote browser)', function () {
+  this.timeout(35000);
+  this.retries(1);
+
+  before(() => {
+    global.codecept_dir = path.join(__dirname, '/../data');
+    I = new Puppeteer(helperConfig);
+    I._init();
+    return I._beforeSuite();
+  });
+
+  beforeEach(async () => {
+    // Mimick remote session by creating another browser instance
+    await createRemoteBrowser();
+    // Set websocket endpoint to other browser instance
+    helperConfig.chrome.browserWSEndpoint = await remoteBrowser.wsEndpoint();
+    I._setConfig(helperConfig);
+
+    return I._before();
+  });
+
+  afterEach(() => {
+    return I._after()
+      .then(() => {
+        remoteBrowser && remoteBrowser.close();
+      });
+  });
+
+  describe('#_startBrowser', () => {
+    it('should throw an exception when endpoint is unreachable', async () => {
+      helperConfig.chrome.browserWSEndpoint = 'ws://unreachable/';
+      I._setConfig(helperConfig);
+      try {
+        await I._startBrowser();
+        throw Error('It should never get this far');
+      } catch (e) {
+        e.message.should.include('Cannot connect to websocket endpoint.\n\nPlease make sure remote browser is running and accessible.');
+      }
+    });
+
+    it('should clear any prior existing pages on remote browser', async () => {
+      const remotePages = await remoteBrowser.pages();
+      assert.equal(remotePages.length, 1);
+      for (let p = 1; p < 5; p++) {
+        await remoteBrowser.newPage();
+      }
+      const existingPages = await remoteBrowser.pages();
+      assert.equal(existingPages.length, 5);
+
+      await I._startBrowser();
+      // Session was cleared
+      let currentPages = await remoteBrowser.pages();
+      assert.equal(currentPages.length, 1);
+
+      let numPages = await I.grabNumberOfOpenTabs();
+      assert.equal(numPages, 1);
+
+      await I.openNewTab();
+
+      numPages = await I.grabNumberOfOpenTabs();
+      assert.equal(numPages, 2);
+
+      await I._stopBrowser();
+
+      currentPages = await remoteBrowser.pages();
+      assert.equal(currentPages.length, 2);
+    });
+  });
+});