@eyeo/get-browser-binary 0.12.0 → 0.14.0

package/.gitlab-ci.yml

@@ -1,5 +1,5 @@
 default:
-  image: registry.gitlab.com/eyeo/docker/get-browser-binary:node16
+  image: registry.gitlab.com/eyeo/docker/get-browser-binary:node18
   interruptible: true
 
 stages:
@@ -48,7 +48,7 @@ test:browsers:windows:
         -OutFile 'MicrosoftEdgeEnterpriseX64.msi'
     - Start-Process msiexec
         -ArgumentList "/i MicrosoftEdgeEnterpriseX64.msi /norestart /qn" -Wait
-    - choco upgrade -y nodejs --version 16.10.0
+    - choco upgrade -y --no-progress nodejs --version 18.17.1
     - npm install
   script:
     # Running Edge tests only on the preinstalled version

package/README.md

@@ -30,20 +30,25 @@ the right side.
 
 ### Supported browser versions
 
-- Chromium >= 75
-- Firefox >= 60
+- Chromium >= 77 (Chromium ARM >= 92)
+- Firefox >= 68
 - Edge >= 95
 
 Note: Installing Edge is not supported on Windows. It is assumed to be installed
 because it is the default browser on that platform. On macOS, only the latest
 Edge version is supported.
 
+### Verbose logging
+
+Set the `VERBOSE` environment variable to `"true"` to get verbose logging on
+download requests.
+
 ## Development
 
 ### Prerequisites
 
-- Node >= 16.10.0
-- npm >= 7
+- Node >= 18
+- npm >= 9
 
 ### Installing/Updating dependencies
 
@@ -70,6 +75,8 @@ Running all tests:
 npm test
 ```
 
+### Options
+
 The `grep` option filters the tests to run with a regular expression. Example:
 
 ```shell
@@ -83,6 +90,29 @@ Increasing the timeout may be useful on slow connection environments:
 npm test -- --timeout <ms>
 ```
 
+By default, tests delete the `./browser-snapshots` before each `Browser` suite
+runs. To change that behavior you may set the `TEST_KEEP_SNAPSHOTS` environment
+variable to `true`. Example:
+
+```shell
+TEST_KEEP_SNAPSHOTS=true npm test
+```
+
+### Test server
+
+Tests use a local http server, which is managed by the `npm test` command. If
+needed, the test server can also run independently:
+
+```shell
+npm run test-server
+```
+
+Then tests may be executed on a separate session. Example:
+
+```shell
+npm run test-suite -- --grep "chromium.*latest"
+```
+
 ### Running tests on Docker
 
 Useful to reproduce the CI environment of the `test:browsers:linux` job.
@@ -101,32 +131,24 @@ parameter:
 docker run --shm-size=512m -e TEST_ARGS="--grep chromium.*latest --timeout 100000" -it browsers
 ```
 
-By default, tests delete the `./browser-snapshots` before each `Browser` suite
-runs. To change that behavior you may set the `TEST_KEEP_SNAPSHOTS` environment
-variable to `true`. Example:
-
-```shell
-TEST_KEEP_SNAPSHOTS=true npm test
-```
-
 #### ARM architecture (M1/M2 Apple Silicon)
 
-Chromium (ARM native):
-
 ```shell
 docker build -f test/docker/arm64.Dockerfile -t browsers-arm .
-docker run --shm-size=512m -e TEST_ARGS="--grep chromium.*latest" -it browsers-arm
+docker run --shm-size=512m -e TEST_ARGS="--grep (chromium|firefox).*latest" -it browsers-arm
 ```
 
-Firefox (AMD emulation):
+Only latest Chromium and latest Firefox ESR versions are supported. Edge is not
+supported.
+
+Regarding Firefox, it may be possible to run other versions using AMD emulation
+(unstable results):
 
 ```shell
 docker build -f test/docker/Dockerfile -t browsers-amd .
-docker run --platform linux/amd64 --shm-size=512m -e TEST_ARGS="--grep firefox.*latest" -it browsers-amd
+docker run --platform linux/amd64 --shm-size=512m -e TEST_ARGS="--grep firefox.*68.0" -it browsers-amd
 ```
 
-Edge: Not supported
-
 ## Building the documentation
 
 ```shell

package/RELEASE_NOTES.md

@@ -1,3 +1,43 @@
+# 0.14.0
+
+- Increases minimum supported browser versions (#64)
+- Sets a minimum supported version for Chromium ARM (#54)
+- Upgrades minimum node version to node 18 (#63)
+- Fixes an occasional issue where the latest Edge on Windows could not find its
+version on Chromium Dash (#61)
+- Enables `dom.promise_rejection_events.enabled` for Firefox 68 (#49)
+- Adds optional verbose logging on download requests (!79)
+- Refactors `src/browsers.js` file (#65)
+
+### Testing
+
+- Adds a local http server for tests (#50)
+- Allows running Firefox ARM in the Docker ARM image (!84)
+- Skip other browser tests when install fails (#58)
+- Fixes an issue where Linux Edge tests would fail when not following a very
+specific order (#57)
+- Reduces the size of the Windows CI log (#62)
+
+### Notes for integrators
+
+- The minimum broser versions are now Chromium >= 77 (Chromium ARM >= 92) and
+Firefox >= 68. Edge keeps the same version (>= 95)
+- The minimum required node version is now 18
+
+# 0.13.0
+
+- Fixes an issue that prevented the webdriver from locating the Edge binary on
+Linux (#60)
+- Uses headless new mode on Edge >= 116 (!74)
+- Replaces omahaproxy API (deprecated) with chromiumdash (!73)
+- Throws a `browser not installed` error when `customBinaryPath` doesn't exist
+(!72)
+
+### Testing
+
+- Changes the test extension in incognito mode from spanning to split (#59)
+- Runs Linux Edge tests in a different browser version order (!71)
+
 # 0.12.0
 
 - Adds a new field `customBrowserBinary` to `getDriver()` options parameter that

package/index.js

@@ -15,5 +15,22 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-export * from "./src/browsers.js";
-export {download, takeFullPageScreenshot} from "./src/utils.js";
+import {Chromium} from "./src/chromium.js";
+import {Firefox} from "./src/firefox.js";
+import {Edge} from "./src/edge.js";
+
+export {download, takeFullPageScreenshot, snapshotsBaseDir}
+  from "./src/utils.js";
+
+/**
+ * @type {Object}
+ * @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.
+ */
+export const BROWSERS = {
+  chromium: Chromium,
+  firefox: Firefox,
+  edge: Edge
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eyeo/get-browser-binary",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Install browser binaries and matching webdrivers",
   "repository": {
     "type": "git",
@@ -9,8 +9,8 @@
   "author": "eyeo GmbH",
   "license": "GPL-3.0",
   "engines": {
-    "node": ">=16.10.0",
-    "npm": ">=7"
+    "node": ">=18",
+    "npm": ">=9"
   },
   "type": "module",
   "main": "index.js",
@@ -39,12 +39,15 @@
     "eslint": "^8.33.0",
     "eslint-config-eyeo": "^3.2.0",
     "expect": "^29.4.2",
+    "express": "^4.18.2",
     "jsdoc": "^4.0.0",
     "mocha": "^10.2.0"
   },
   "scripts": {
     "docs": "jsdoc --readme README.md --destination docs src/*.js",
     "lint": "eslint --ext js .",
-    "test": "mocha test/*.js --"
+    "test": "node test/runner.js --",
+    "test-suite": "mocha --exclude test/start-server.js --exclude test/test-server.js --exclude test/runner.js --",
+    "test-server": "node test/start-server.js"
   }
 }

package/src/browser.js

@@ -0,0 +1,134 @@
+/*
+ * Copyright (c) 2006-present eyeo GmbH
+ *
+ * This module is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+import {exec, execFile} from "child_process";
+import {promisify} from "util";
+
+import {errMsg} from "./utils.js";
+
+/**
+ * Base class for browser and webdriver functionality. Please see subclasses for
+ *   browser specific details. All classes can be used statically.
+ * @hideconstructor
+ */
+export class Browser {
+  /**
+   * @typedef {Object} BrowserBinary
+   * @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=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.
+   */
+  static async installBrowser(version, downloadTimeout = 0) {
+    // to be implemented by the subclass
+  }
+
+  /**
+   * Gets the installed version returned by the browser binary.
+   * @param {string} binary The path to the browser binary.
+   * @return {string} Installed browser version.
+   * @throws {Error} Browser is not installed.
+   */
+  static async getInstalledVersion(binary) {
+    try {
+      let stdout;
+      let stderr;
+      if (process.platform == "win32") {
+        ({stdout, stderr} = await promisify(exec)(
+          `(Get-ItemProperty ${binary}).VersionInfo.ProductVersion`,
+          {shell: "powershell.exe"})
+        );
+      }
+      else {
+        ({stdout, stderr} = await promisify(execFile)(binary, ["--version"]));
+      }
+      if (stderr)
+        throw new Error(stderr);
+
+      return stdout.trim();
+    }
+    catch (err) {
+      throw new Error(`${errMsg.browserNotInstalled}.\nBinary path: ${binary}\n${err}`);
+    }
+  }
+
+  /**
+   * @typedef {Object} webdriver
+   * @see https://www.selenium.dev/selenium/docs/api/javascript/index.html
+   */
+
+  /**
+   * @typedef {Object} driverOptions
+   * @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,
+   *   or not.
+   * @property {boolean} [insecure=false] Forces the browser to accept insecure
+   *   certificates, or not.
+   * @property {Array.<string>} [extraArgs=[]] Additional arguments to start
+   *   the browser with.
+   * @property {string} [customBrowserBinary] Path to the browser binary to be
+   *   used, instead of the browser installed by installBrowser(). This option
+   *   overrides the version parameter in getDriver().
+   */
+
+  /**
+   * Installs the webdriver matching the browser version and runs the
+   * browser. If needed, the browser binary is also installed.
+   * @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.
+   * @return {webdriver}
+   * @throws {Error} Unsupported browser version, Unsupported platform, Browser
+   *   download failed, Driver download failed, Unable to start driver.
+   */
+  static async getDriver(version, options = {}, downloadTimeout = 0) {
+    // to be implemented by the subclass
+  }
+
+  /**
+   * 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 extension to be enabled.
+   * @return {webdriver}
+   * @throws {Error} Unsupported browser version, Extension not found, HTML
+   *   element not found.
+   */
+  static async enableExtensionInIncognito(driver, extensionTitle) {
+    // Allowing the extension in incognito mode can't happen programmatically:
+    // https://stackoverflow.com/questions/57419654
+    // https://bugzilla.mozilla.org/show_bug.cgi?id=1729315
+    // That is done through the UI, to be implemented by the subclass
+  }
+}