@eyeo/get-browser-binary 0.9.0 → 0.10.0

package/.gitlab-ci.yml

@@ -51,15 +51,13 @@ test:browsers:windows:
     - choco upgrade -y nodejs --version 16.10.0
     - npm install
   script:
+    # Running Edge tests only on the preinstalled version
+    # https://gitlab.com/eyeo/developer-experience/get-browser-binary/-/issues/29
+    - npm test -- --grep "edge.*latest"
+    - npm test -- --grep "chromium"
     # Running only a subset of Firefox tests to avoid low OS resources error
     # https://gitlab.com/eyeo/developer-experience/get-browser-binary/-/issues/2
     - npm test -- --grep "firefox.*installs"
-    # Running npm v8 on powershell has issues when the grep value contains the
-    # pipe (|) literal. Storing that string as a verbatim string (single quotes)
-    # and then sorrounding it with four double quotes does the trick.
-    # https://gitlab.com/eyeo/developer-experience/get-browser-binary/-/issues/29
-    - $full_tests = '(chromium|edge.*latest)'
-    - npm test -- --grep """"$full_tests""""
   tags:
     - shared-windows
     - windows

package/RELEASE_NOTES.md

@@ -1,3 +1,13 @@
+# 0.10.0
+
+- Added handling of the new headless mode in Chromium (#45)
+- Fixed an issue that prevented Chromium to be installed on macOS ARM processors
+(!59)
+- Changed documentation nullable parameters to optional parameters (#41)
+- Increased the npm geckodriver version to 3.1.0 (!57)
+- Fixed an issue with Windows Edge and msedgedriver, which occasionally failed
+when building the driver (!56)
+
 # 0.9.0
 
 - Fixed a Chromium install issue by increasing the value of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eyeo/get-browser-binary",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Install browser binaries and matching webdrivers",
   "repository": {
     "type": "git",
@@ -30,17 +30,17 @@
   "dependencies": {
     "dmg": "^0.1.0",
     "extract-zip": "^2.0.1",
-    "geckodriver": "^3.0.2",
-    "got": "^11.8.2",
-    "jimp": "^0.16.2",
-    "selenium-webdriver": "^4.7.1"
+    "geckodriver": "3.1.0",
+    "got": "^12.5.3",
+    "jimp": "^0.22.4",
+    "selenium-webdriver": "^4.8.0"
   },
   "devDependencies": {
-    "eslint": "^8.17.0",
+    "eslint": "^8.33.0",
     "eslint-config-eyeo": "^3.2.0",
-    "expect": "^25.5.0",
-    "jsdoc": "^3.6.10",
-    "mocha": "^10.0.0"
+    "expect": "^29.4.2",
+    "jsdoc": "^4.0.0",
+    "mocha": "^10.2.0"
   },
   "scripts": {
     "docs": "jsdoc --readme README.md --destination docs src/*.js",

package/src/browsers.js

@@ -25,7 +25,6 @@ import webdriver from "selenium-webdriver";
 import chrome from "selenium-webdriver/chrome.js";
 import firefox from "selenium-webdriver/firefox.js";
 import edge from "selenium-webdriver/edge.js";
-import command from "selenium-webdriver/lib/command.js";
 import extractZip from "extract-zip";
 
 import {download, extractTar, extractDmg, killDriverProcess, wait}
@@ -50,12 +49,19 @@ const BROWSER_DOWNLOAD_ERROR = "Browser download failed";
 const BROWSER_NOT_INSTALLED_ERROR = "Browser is not installed";
 const ELEMENT_NOT_FOUND_ERROR = "HTML element not found";
 
+function getMajorVersion(versionNumber) {
+  let majorVersion = parseInt(versionNumber && versionNumber.split(".")[0], 10);
+  if (isNaN(majorVersion))
+    throw new Error(`${UNSUPPORTED_VERSION_ERROR}: ${versionNumber}`);
+
+  return majorVersion;
+}
+
 function checkVersion(version, minVersion, channels = []) {
   if (channels.includes(version))
     return;
 
-  let mainVersion = parseInt(version && version.split(".")[0], 10);
-  if (isNaN(mainVersion) || mainVersion < minVersion)
+  if (getMajorVersion(version) < minVersion)
     throw new Error(`${UNSUPPORTED_VERSION_ERROR}: ${version}`);
 }
 
@@ -72,19 +78,17 @@ function checkPlatform() {
 class Browser {
   /**
    * @typedef {Object} BrowserBinary
-   * @property {string} binary - The path to the browser binary.
-   * @property {string} versionNumber - The version number of the browser
-   *   binary.
+   * @property {string} binary The path to the browser binary.
+   * @property {string} versionNumber The version number of the browser binary.
    */
 
   /**
    * Installs the browser. The installation process is detailed on the
    *   subclasses.
-   * @param {string} version - Either full version number or channel/release.
-   *   Please find examples on the subclasses.
-   * @param {number?} downloadTimeout - Allowed time in ms for the download of
-   *   install files to complete. When set to 0 there is no time limit. Defaults
-   *   to 0.
+   * @param {string} [version=latest] Either full version number or
+   *   channel/release. Please find examples on the subclasses.
+   * @param {number} [downloadTimeout=0] Allowed time in ms for the download of
+   *   install files to complete. When set to 0 there is no time limit.
    * @return {BrowserBinary}
    * @throws {Error} Unsupported browser version, Unsupported platform, Browser
    *   download failed.
@@ -95,7 +99,7 @@ class Browser {
 
   /**
    * Gets the installed version returned by the browser binary.
-   * @param {string} binary - The path to the browser binary.
+   * @param {string} binary The path to the browser binary.
    * @return {string} Installed browser version.
    */
   static async getInstalledVersion(binary) {
@@ -119,27 +123,28 @@ class Browser {
 
   /**
    * @typedef {Object} driverOptions
-   * @property {boolean} headless=true - Run the browser in headless mode,
-   *   or not.
-   * @property {Array.<string>} [extensionPaths=[]] - Loads extensions to the
+   * @property {boolean} [headless=true] Run the browser in headless mode,
+   *   or not. In Chromium >= 111, the
+   *   {@link https://developer.chrome.com/articles/new-headless/ new headless mode}
+   *   is used.
+   * @property {Array.<string>} [extensionPaths=[]] Loads extensions to the
    *   browser.
-   * @property {boolean} incognito=false - Runs the browser in incognito mode,
+   * @property {boolean} [incognito=false] Runs the browser in incognito mode,
    *   or not.
-   * @property {boolean} insecure=false - Forces the browser to accept insecure
+   * @property {boolean} [insecure=false] Forces the browser to accept insecure
    *   certificates, or not.
-   * @property {Array.<string>} [extraArgs=[]] - Additional arguments to start
+   * @property {Array.<string>} [extraArgs=[]] Additional arguments to start
    *   the browser with.
    */
 
   /**
    * Installs the webdriver matching the browser version and runs the
    * browser. If needed, the browser binary is also installed.
-   * @param {string} version - Either full version number or channel/release.
-   *   Please find examples on the subclasses.
-   * @param {driverOptions?} options - Options to start the browser with.
-   * @param {number?} downloadTimeout - Allowed time in ms for the download of
+   * @param {string} [version=latest] Either full version number or
+   *   channel/release. Please find examples on the subclasses.
+   * @param {driverOptions} [options={}] Options to start the browser with.
+   * @param {number} [downloadTimeout=0] Allowed time in ms for the download of
    *   browser install files to complete. When set to 0 there is no time limit.
-   *   Defaults to 0.
    * @return {webdriver}
    * @throws {Error} Unsupported browser version, Unsupported platform, Browser
    *   download failed, Driver download failed, Unable to start driver.
@@ -151,8 +156,8 @@ class Browser {
   /**
    * By default, extensions are disabled in incognito mode. This function
    * enables the extension when loaded in incognito.
-   * @param {webdriver} driver - The driver controlling the browser.
-   * @param {string} extensionTitle - Title of the extebsion to be enabled.
+   * @param {webdriver} driver The driver controlling the browser.
+   * @param {string} extensionTitle Title of the extension to be enabled.
    * @return {webdriver}
    * @throws {Error} Unsupported browser version, Extension not found, HTML
    *   element not found.
@@ -185,7 +190,7 @@ class Chromium extends Browser {
       "win32-x64": "win64",
       "linux-x64": "linux",
       "darwin-x64": "mac",
-      "dawrin-arm64": "mac_arm64"
+      "darwin-arm64": "mac_arm64"
     }[platformArch];
     let data = await got(`https://omahaproxy.appspot.com/all.json?os=${os}`).json();
     let release = data[0].versions.find(ver => ver.channel == channel);
@@ -212,11 +217,10 @@ class Chromium extends Browser {
   /**
    * Installs the browser. The Chromium executable gets extracted in the
    *   {@link snapshotsBaseDir} folder, ready to go.
-   * @param {string} version - Either "latest", "beta", "dev" or a full version
-   *   number (i.e. "77.0.3865.0"). Defaults to "latest".
-   * @param {number?} downloadTimeout - Allowed time in ms for the download of
-   *   install files to complete. When set to 0 there is no time limit. Defaults
-   *   to 0.
+   * @param {string} [version=latest] Either "latest", "beta", "dev" or a full
+   *   version number (i.e. "77.0.3865.0").
+   * @param {number} [downloadTimeout=0] Allowed time in ms for the download of
+   *   install files to complete. When set to 0 there is no time limit.
    * @return {BrowserBinary}
    * @throws {Error} Unsupported browser version, Unsupported platform, Browser
    *   download failed.
@@ -237,7 +241,7 @@ class Chromium extends Browser {
       "win32-x64": ["Win_x64", "chrome-win.zip"],
       "linux-x64": ["Linux_x64", "chrome-linux.zip"],
       "darwin-x64": ["Mac", "chrome-mac.zip"],
-      "dawrin-arm64": ["Mac_Arm", "chrome-mac.zip"]
+      "darwin-arm64": ["Mac_Arm", "chrome-mac.zip"]
     }[platformArch];
     let archive;
     let browserDir;
@@ -333,8 +337,14 @@ class Chromium extends Browser {
     let options = new chrome.Options().addArguments("no-sandbox", ...extraArgs);
     if (extensionPaths.length > 0)
       options.addArguments(`load-extension=${extensionPaths.join(",")}`);
-    if (headless)
-      options.headless();
+    if (headless) {
+      // New headless mode introduced in Chrome 111
+      // https://developer.chrome.com/articles/new-headless/
+      if (getMajorVersion(versionNumber) >= 111)
+        options.addArguments("headless=new");
+      else
+        options.headless();
+    }
     if (insecure)
       options.addArguments("ignore-certificate-errors");
     if (incognito)
@@ -423,11 +433,10 @@ class Firefox extends Browser {
   /**
    * Installs the browser. The Firefox executable gets extracted in the
    *   {@link snapshotsBaseDir} folder, ready to go.
-   * @param {string} version - Either "latest", "beta" or a full version
-   *   number (i.e. "68.0"). Defaults to "latest".
-   * @param {number?} downloadTimeout - Allowed time in ms for the download of
-   *   install files to complete. When set to 0 there is no time limit. Defaults
-   *   to 0.
+   * @param {string} [version=latest] Either "latest", "beta" or a full version
+   *   number (i.e. "68.0").
+   * @param {number} [downloadTimeout=0] Allowed time in ms for the download of
+   *   install files to complete. When set to 0 there is no time limit.
    * @return {BrowserBinary}
    * @throws {Error} Unsupported browser version, Unsupported platform, Browser
    *   download failed.
@@ -512,11 +521,8 @@ class Firefox extends Browser {
     }, 30000, `${DRIVER_START_ERROR}: geckodriver`, 1000);
 
     for (let extensionPath of extensionPaths) {
-      await driver.execute(
-        new command.Command("install addon")
-          .setParameter("path", extensionPath)
-          .setParameter("temporary", true)
-      );
+      let temporary = true; // Parameter not documented on the webdriver docs
+      await driver.installAddon(extensionPath, temporary);
     }
     return driver;
   }
@@ -565,8 +571,7 @@ class Edge extends Browser {
         versionNumbers.push(matches[2]);
 
       let compareVersions = (v1, v2) =>
-        parseInt(v1.split(".")[0], 10) < parseInt(v2.split(".")[0], 10) ?
-          1 : -1;
+        getMajorVersion(v1) < getMajorVersion(v2) ? 1 : -1;
       versionNumber = versionNumbers.sort(compareVersions)[0];
     }
     else {
@@ -613,11 +618,10 @@ class Edge extends Browser {
    * Installs the browser. On Linux, Edge is installed as a system package,
    *   which requires root permissions. On MacOS, Edge is installed as a user
    *   app (not as a system app). Installing Edge on Windows is not supported.
-   * @param {string} version - Either "latest", "beta", "dev" or a full version
-   *   number (i.e. "95.0.1020.40"). Defaults to "latest".
-   * @param {number?} downloadTimeout - Allowed time in ms for the download of
-   *   install files to complete. When set to 0 there is no time limit. Defaults
-   *   to 0.
+   * @param {string} [version=latest] Either "latest", "beta", "dev" or a full
+   *   version number (i.e. "95.0.1020.40").
+   * @param {number} [downloadTimeout=0] Allowed time in ms for the download of
+   *   install files to complete. When set to 0 there is no time limit.
    * @return {BrowserBinary}
    * @throws {Error} Unsupported browser version, Unsupported platform, Browser
    *   download failed.
@@ -760,7 +764,22 @@ class Edge extends Browser {
     builder.setEdgeOptions(options);
     builder.setEdgeService(serviceBuilder);
 
-    return builder.build();
+    let driver;
+    // On Windows CI, occasionally a SessionNotCreatedError is thrown, likely
+    // due to low OS resources, that's why building the driver is retried
+    await wait(async() => {
+      try {
+        driver = await builder.build();
+        return true;
+      }
+      catch (err) {
+        if (err.name != "SessionNotCreatedError")
+          throw err;
+        await killDriverProcess("msedgedriver");
+      }
+    }, 30000, `${DRIVER_START_ERROR}: msedgedriver`, 1000);
+
+    return driver;
   }
 
   /** @see Browser.enableExtensionInIncognito */
@@ -787,11 +806,10 @@ class Edge extends Browser {
 
 /**
  * @type {Object}
- * @property {Chromium} chromium - Browser and webdriver functionality for
+ * @property {Chromium} chromium Browser and webdriver functionality for
  *   Chromium.
- * @property {Firefox} firefox - Browser and webdriver functionality for
- *   Firefox.
- * @property {Edge} edge - Browser and webdriver functionality for Edge.
+ * @property {Firefox} firefox Browser and webdriver functionality for Firefox.
+ * @property {Edge} edge Browser and webdriver functionality for Edge.
  */
 export const BROWSERS = {
   chromium: Chromium,

package/src/utils.js

@@ -28,10 +28,10 @@ import Jimp from "jimp";
 
 /**
  * Downloads url resources.
- * @param {string} url - The url of the resource to be downloaded.
- * @param {string} destFile - The destination file path.
- * @param {number?} timeout - Allowed time in ms for the download to complete.
- *   When set to 0 there is no time limit. Defaults to 0.
+ * @param {string} url The url of the resource to be downloaded.
+ * @param {string} destFile The destination file path.
+ * @param {number} [timeout=0] Allowed time in ms for the download to complete.
+ *   When set to 0 there is no time limit.
  * @throws {TypeError} Invalid URL, Download timeout.
  */
 export async function download(url, destFile, timeout = 0) {
@@ -164,9 +164,9 @@ export function wait(condition, timeout = 0, message, pollTimeout = 100) {
 
 /**
  * Takes a screenshot of the full page by scrolling from top to bottom.
- * @param {webdriver} driver - The driver controlling the browser.
- * @property {boolean} hideScrollbars=true - Hides any scrollbars before
- *   taking the screenshot, or not.
+ * @param {webdriver} driver The driver controlling the browser.
+ * @param {boolean} [hideScrollbars=true] Hides any scrollbars before taking
+ *   the screenshot, or not.
  * @return {Jimp} A Jimp image object containing the screenshot.
  * @example
  * // Getting a base-64 encoded PNG from the returned Jimp image

package/test/browsers.js

@@ -16,7 +16,7 @@
  */
 
 import fs from "fs";
-import expect from "expect";
+import {expect} from "expect";
 import path from "path";
 
 import {BROWSERS, snapshotsBaseDir, takeFullPageScreenshot} from "../index.js";
@@ -242,7 +242,9 @@ for (let browser of Object.keys(BROWSERS)) {
         });
 
         it("loads an extension", async() => {
-          let headless = browser == "firefox";
+          // Chromium's old headless mode doesn't support loading extensions
+          let headless = browser == "firefox" || (browser == "chromium" &&
+            ["latest", "beta", "dev"].includes(version));
           let {extensionPaths} = getExtension(browser, version);
 
           driver = await BROWSERS[browser].getDriver(

package/test/utils.js

@@ -16,7 +16,7 @@
  */
 
 import fs from "fs";
-import expect from "expect";
+import {expect} from "expect";
 import path from "path";
 
 import {snapshotsBaseDir, download} from "../index.js";