@eyeo/get-browser-binary 0.6.0 → 0.8.0

package/.gitlab-ci.yml

@@ -55,10 +55,11 @@ test:browsers:windows:
   script:
     # 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.*latest.*downloads"
+    - 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:

package/.mocharc.json

@@ -0,0 +1,3 @@
+{
+  "timeout": 50000
+}

package/README.md

@@ -1,19 +1,19 @@
 # get-browser-binary
 
-Download specific browser versions for Chromium, Firefox and Edge, and their
+Install specific browser versions for Chromium, Firefox and Edge, and their
 matching [selenium webdriver](https://www.selenium.dev/selenium/docs/api/javascript/index.html).
 
 ## Getting started
 
-The sample below shows how to download the latest Chromium and run it using
+The sample below shows how to install the latest Chromium and run it using
 selenium webdriver:
 
 ```javascript
 import {BROWSERS} from "@eyeo/get-browser-binary";
 
 (async function example() {
-  let {binary} = await BROWSERS.chromium.downloadBinary("latest");
-  console.log(`Chromium binary downloaded to ${binary}`);
+  let {binary} = await BROWSERS.chromium.installBrowser("latest");
+  console.log(`Chromium executable location: ${binary}`);
 
   let driver = await BROWSERS.chromium.getDriver("latest");
   await driver.navigate().to("https://example.com/");
@@ -34,7 +34,7 @@ the right side.
 - Firefox >= 60
 - Edge >= 95
 
-Note: Edge download is not supported on Windows. It is assumed to be installed
+Note: Installing Edge is not supported on Windows. It is assumed to be installed
 because it is the default browser on that platform.
 
 ## Development
@@ -52,7 +52,7 @@ npm install
 
 ### Folders to ignore / cache
 
-All browser and webdriver files will be downloaded to the `./browser-snapshots`
+All browser and webdriver files will be extracted to the `./browser-snapshots`
 folder, which probably makes sense to be ignored (for instance, by adding it to
 `.gitignore`).
 
@@ -75,6 +75,13 @@ The `grep` option filters the tests to run with a regular expression. Example:
 npm test -- --grep "chromium.*latest"
 ```
 
+The `timeout` option overrides the timeout defined by `.mocharc.json`.
+Increasing the timeout may be useful on slow connection environments:
+
+```shell
+npm test -- --timeout <ms>
+```
+
 ### Running tests on Docker
 
 Useful to reproduce the CI environment of the `test:browsers:linux` job:
@@ -84,10 +91,19 @@ docker build -f test/docker/Dockerfile -t browsers .
 docker run --shm-size=256m -it browsers
 ```
 
-The `grep` option can also be used on Docker via the `TEST_ARGS` parameter:
+The `grep` and `timeout` options can also be used on Docker via the `TEST_ARGS`
+parameter:
+
+```shell
+docker run --shm-size=256m -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
-docker run --shm-size=256m -e TEST_ARGS="--grep chromium.*latest" -it browsers
+TEST_KEEP_SNAPSHOTS=true npm test
 ```
 
 ## Building the documentation

package/RELEASE_NOTES.md

@@ -1,3 +1,36 @@
+# 0.8.0
+
+- Move `takeFullPageScreenshot` to the utils module (#38)
+- Add keywords to package.json (#36)
+
+### Testing
+
+- Log the running browser version on test suites (#37)
+
+### Notes for integrators
+
+- `takeFullPageScreenshot()` has been moved from the browsers module to the
+utils module (!46).
+
+# 0.7.0
+
+- Implement takeFullPageScreenshot (#32)
+- Unify error messages (#22)
+- Document when a browser binary is downloaded or installed (#30)
+- Use cached driver binary if it already exists (#20)
+- Remove chromedriver dependency (#33)
+- Fallback mechanism on minor browser versions (Edge) (#27)
+
+### Testing
+
+- Use a manifest V3 extension on latest chromium-based browsers tests (#31)
+- Allow test run to not delete browser snapshots (#28)
+- Add a timeout option to run the tests (#24)
+
+### Notes for integrators
+
+- The `downloadBinary` function has been renamed to `installBrowser` (!38).
+
 # 0.6.0
 
 - Removes Opera support (#26)

package/index.js

@@ -16,4 +16,4 @@
  */
 
 export * from "./src/browsers.js";
-export {download} from "./src/utils.js";
+export {download, takeFullPageScreenshot} from "./src/utils.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@eyeo/get-browser-binary",
-  "version": "0.6.0",
-  "description": "Download browser binaries and matching webdrivers",
+  "version": "0.8.0",
+  "description": "Install browser binaries and matching webdrivers",
   "repository": {
     "type": "git",
     "url": "https://gitlab.com/eyeo/developer-experience/get-browser-binary"
@@ -14,13 +14,26 @@
   },
   "type": "module",
   "main": "index.js",
+  "keywords": [
+    "browser",
+    "chromium",
+    "chrome",
+    "firefox",
+    "msedge",
+    "chromedriver",
+    "geckodriver",
+    "msedgedriver",
+    "selenium",
+    "webdriver",
+    "selenium-webdriver"
+  ],
   "dependencies": {
-    "chromedriver": "^90.0.1",
     "dmg": "^0.1.0",
     "extract-zip": "^2.0.1",
     "geckodriver": "^3.0.2",
     "got": "^11.8.2",
-    "selenium-webdriver": "^4.6.1"
+    "jimp": "^0.16.2",
+    "selenium-webdriver": "^4.7.1"
   },
   "devDependencies": {
     "eslint": "^8.17.0",

package/src/browsers.js

@@ -28,30 +28,45 @@ import edge from "selenium-webdriver/edge.js";
 import command from "selenium-webdriver/lib/command.js";
 import extractZip from "extract-zip";
 
-import {download, extractTar, extractDmg, getBrowserVersion, killDriverProcess,
-        wait} from "./utils.js";
+import {download, extractTar, extractDmg, killDriverProcess, wait}
+  from "./utils.js";
 
 /**
- * Root folder where browser and webdriver binaries get downloaded.
+ * Root folder where browser and webdriver files get downloaded and extracted.
  * @type {string}
  */
 export let snapshotsBaseDir = path.join(process.cwd(), "browser-snapshots");
 
 let {until, By} = webdriver;
-let platform = `${process.platform}-${process.arch}`;
-
-function checkVersion(version, minVersion, channels) {
+let {platform, arch} = process;
+let platformArch = `${platform}-${arch}`;
+
+const UNSUPPORTED_VERSION_ERROR = "Unsupported browser version";
+const UNSUPPORTED_PLATFORM_ERROR = "Unsupported platform";
+const DRIVER_DOWNLOAD_ERROR = "Driver download failed";
+const DRIVER_START_ERROR = "Unable to start driver";
+const EXTENSION_NOT_FOUND_ERROR = "Extension not found";
+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 checkVersion(version, minVersion, channels = []) {
   if (channels.includes(version))
     return;
 
   let mainVersion = parseInt(version && version.split(".")[0], 10);
   if (isNaN(mainVersion) || mainVersion < minVersion)
-    throw new Error(`Unsupported browser version: ${version}`);
+    throw new Error(`${UNSUPPORTED_VERSION_ERROR}: ${version}`);
+}
+
+function checkPlatform() {
+  if (!["win32", "linux", "darwin"].includes(platform))
+    throw new Error(`${UNSUPPORTED_PLATFORM_ERROR}: ${platform}`);
 }
 
 /**
- * Base class for browser download functionality. Please see subclasses for
- * browser specific details.
+ * Base class for browser and webdriver functionality. Please see subclasses for
+ *   browser specific details. All classes can be used statically.
  * @hideconstructor
  */
 class Browser {
@@ -63,13 +78,15 @@ class Browser {
    */
 
   /**
-   * Downloads the browser binary file.
+   * 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.
    * @return {BrowserBinary}
-   * @throws {Error} Unsupported browser version.
+   * @throws {Error} Unsupported browser version, Unsupported platform, Browser
+   *   download failed.
    */
-  static async downloadBinary(version) {
+  static async installBrowser(version) {
     // to be implemented by the subclass
   }
 
@@ -80,7 +97,7 @@ class Browser {
    */
   static async getInstalledVersion(binary) {
     let stdout;
-    if (process.platform == "win32") {
+    if (platform == "win32") {
       ({stdout} = await promisify(exec)(
         `(Get-ItemProperty ${binary}).VersionInfo.ProductVersion`,
         {shell: "powershell.exe"})
@@ -118,7 +135,8 @@ class Browser {
    *   Please find examples on the subclasses.
    * @param {driverOptions?} options - Options to start the browser with.
    * @return {webdriver}
-   * @throws {Error} Unsupported browser version.
+   * @throws {Error} Unsupported browser version, Unsupported platform, Browser
+   *   download failed, Driver download failed, Unable to start driver.
    */
   static async getDriver(version, options = {}) {
     // to be implemented by the subclass
@@ -130,7 +148,8 @@ class Browser {
    * @param {webdriver} driver - The driver controlling the browser.
    * @param {string} extensionTitle - Title of the extebsion to be enabled.
    * @return {webdriver}
-   * @throws {Error} Unsupported browser version.
+   * @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:
@@ -141,19 +160,17 @@ class Browser {
 }
 
 /**
- * Download functionality for Chromium. This class can be used statically.
+ * Browser and webdriver functionality for Chromium.
  * @hideconstructor
  * @extends Browser
  */
 class Chromium extends Browser {
-  static #DRIVER = "chromedriver";
-
-  static async #getBranchBasePosition(version) {
-    let data = await got(`https://omahaproxy.appspot.com/deps.json?version=${version}`).json();
-    return data.chromium_base_position;
-  }
+  static #CHANNELS = ["latest", "beta", "dev"];
 
   static async #getVersionForChannel(channel) {
+    if (!Chromium.#CHANNELS.includes(channel))
+      return channel;
+
     if (channel == "latest")
       channel = "stable";
 
@@ -163,7 +180,7 @@ class Chromium extends Browser {
       "linux-x64": "linux",
       "darwin-x64": "mac",
       "dawrin-arm64": "mac_arm64"
-    }[platform];
+    }[platformArch];
     let data = await got(`https://omahaproxy.appspot.com/all.json?os=${os}`).json();
     let release = data[0].versions.find(ver => ver.channel == channel);
     let {current_version: version} = release;
@@ -177,55 +194,67 @@ class Chromium extends Browser {
   }
 
   static #getBinaryPath(dir) {
-    switch (process.platform) {
-      case "win32":
-        return path.join(dir, "chrome-win", "chrome.exe");
-      case "linux":
-        return path.join(dir, "chrome-linux", "chrome");
-      case "darwin":
-        return path.join(dir, "chrome-mac", "Chromium.app", "Contents", "MacOS",
-                         "Chromium");
-      default:
-        throw new Error(`Unexpected platform: ${process.platform}`);
-    }
+    checkPlatform();
+    return {
+      win32: path.join(dir, "chrome-win", "chrome.exe"),
+      linux: path.join(dir, "chrome-linux", "chrome"),
+      darwin: path.join(dir, "chrome-mac", "Chromium.app", "Contents", "MacOS",
+                        "Chromium")
+    }[platform];
   }
 
-  static async #downloadChromium(chromiumRevision) {
-    const MAX_VERSION_DECREMENTS = 50;
+  /**
+   * 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".
+   * @return {BrowserBinary}
+   * @throws {Error} Unsupported browser version, Unsupported platform, Browser
+   *   download failed.
+   */
+  static async installBrowser(version = "latest") {
+    const MIN_VERSION = 75;
+    const MAX_VERSION_DECREMENTS = 80;
+
+    checkVersion(version, MIN_VERSION, Chromium.#CHANNELS);
+    let versionNumber = await Chromium.#getVersionForChannel(version);
 
-    let revision = parseInt(chromiumRevision, 10);
-    let startingRevision = revision;
+    let {chromium_base_position: chromiumBase} =
+      await got(`https://omahaproxy.appspot.com/deps.json?version=${versionNumber}`).json();
+    let base = parseInt(chromiumBase, 10);
+    let startBase = base;
     let [platformDir, fileName] = {
       "win32-ia32": ["Win", "chrome-win.zip"],
       "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"]
-    }[platform];
-    let archive = null;
-    let browserDir = null;
+    }[platformArch];
+    let archive;
+    let browserDir;
     let snapshotsDir = path.join(snapshotsBaseDir, "chromium");
+    let binary;
 
     while (true) {
-      browserDir = path.join(snapshotsDir, `chromium-${platform}-${revision}`);
+      browserDir = path.join(snapshotsDir, `chromium-${platformArch}-${base}`);
+      binary = Chromium.#getBinaryPath(browserDir);
 
       try {
         await fs.promises.access(browserDir);
-        return {binary: Chromium.#getBinaryPath(browserDir), revision};
+        return {binary, versionNumber, base};
       }
       catch (e) {}
 
       await fs.promises.mkdir(path.dirname(browserDir), {recursive: true});
 
-      archive = path.join(snapshotsDir, "cache", `${revision}-${fileName}`);
-
+      archive = path.join(snapshotsDir, "cache", `${base}-${fileName}`);
       try {
         try {
           await fs.promises.access(archive);
         }
         catch (e) {
           await download(
-            `https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/${platformDir}%2F${revision}%2F${fileName}?alt=media`,
+            `https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/${platformDir}%2F${base}%2F${fileName}?alt=media`,
             archive);
         }
         break;
@@ -233,58 +262,53 @@ class Chromium extends Browser {
       catch (e) {
         // Chromium advises decrementing the branch_base_position when no
         // matching build was found. See https://www.chromium.org/getting-involved/download-chromium
-        revision--;
-        if (revision <= startingRevision - MAX_VERSION_DECREMENTS)
-          throw new Error(`No Chromium package found for ${startingRevision}`);
+        base--;
+        if (base <= startBase - MAX_VERSION_DECREMENTS)
+          throw new Error(`${BROWSER_DOWNLOAD_ERROR}: Chromium base ${startBase}`);
       }
     }
-
     await extractZip(archive, {dir: browserDir});
-    return {binary: Chromium.#getBinaryPath(browserDir), revision};
-  }
-
-  /**
-   * Downloads the browser binary file.
-   * @param {string} version - Either "latest", "beta", "dev" or a full version
-   *   number (i.e. "77.0.3865.0"). Defaults to "latest".
-   * @return {BrowserBinary}
-   */
-  static async downloadBinary(version = "latest") {
-    const MIN_VERSION = 75;
-    const CHANNELS = ["latest", "beta", "dev"];
-
-    checkVersion(version, MIN_VERSION, CHANNELS);
-
-    let versionNumber = CHANNELS.includes(version) ?
-      await Chromium.#getVersionForChannel(version) : version;
-
-    let base = await Chromium.#getBranchBasePosition(versionNumber);
 
-    let {binary, revision} = await Chromium.#downloadChromium(base);
-    return {binary, versionNumber, revision};
+    return {binary, versionNumber, base};
   }
 
-  static async #installDriver(revision, version) {
-    let [dir, zip, driver] = {
+  static async #installDriver(base, versionNumber) {
+    let [dir, zip, driverBinary] = {
       "win32-ia32": ["Win", "chromedriver_win32.zip", "chromedriver.exe"],
       "win32-x64": ["Win_x64", "chromedriver_win32.zip", "chromedriver.exe"],
       "linux-x64": ["Linux_x64", "chromedriver_linux64.zip", "chromedriver"],
       "darwin-x64": ["Mac", "chromedriver_mac64.zip", "chromedriver"],
       "darwin-arm64": ["Mac_Arm", "chromedriver_mac64.zip", "chromedriver"]
-    }[platform];
+    }[platformArch];
 
-    let cacheDir = path.join(snapshotsBaseDir, "chromium", "cache", version);
-    let destinationDir = path.join(process.cwd(), "node_modules",
-                                   Chromium.#DRIVER, "lib", Chromium.#DRIVER);
-    let archive = path.join(cacheDir, `${revision}-${zip}`);
+    let cacheDir = path.join(snapshotsBaseDir, "chromium", "cache",
+                             versionNumber);
+    let archive = path.join(cacheDir, `${base}-${zip}`);
 
-    await download(`https://commondatastorage.googleapis.com/chromium-browser-snapshots/${dir}/${revision}/${zip}`,
-                   archive);
+    try {
+      await fs.promises.access(archive);
+      await extractZip(archive, {dir: cacheDir});
+    }
+    catch (e) { // zip file is either not cached or corrupted
+      let url = `https://commondatastorage.googleapis.com/chromium-browser-snapshots/${dir}/${base}/${zip}`;
+      try {
+        await download(url, archive);
+      }
+      catch (err) {
+        throw new Error(`${DRIVER_DOWNLOAD_ERROR}: ${url}\n${err}`);
+      }
+      await extractZip(archive, {dir: cacheDir});
+    }
+
+    await killDriverProcess("chromedriver");
+    let driverPath = path.join(cacheDir, zip.split(".")[0], driverBinary);
+    try {
+      await fs.promises.rm(driverPath, {recursive: true});
+    }
+    catch (e) {} // file does not exist
     await extractZip(archive, {dir: cacheDir});
-    await killDriverProcess(Chromium.#DRIVER);
-    await fs.promises.mkdir(destinationDir, {recursive: true});
-    await fs.promises.copyFile(path.join(cacheDir, zip.split(".")[0], driver),
-                               path.join(destinationDir, driver));
+
+    return driverPath;
   }
 
   /** @see Browser.getDriver */
@@ -292,10 +316,9 @@ class Chromium extends Browser {
     headless = true, extensionPaths = [], incognito = false, insecure = false,
     extraArgs = []
   } = {}) {
-    let {binary, revision, versionNumber} =
-      await Chromium.downloadBinary(version);
-    await Chromium.#installDriver(revision, versionNumber);
-
+    let {binary, versionNumber, base} = await Chromium.installBrowser(version);
+    let driverPath = await Chromium.#installDriver(base, versionNumber);
+    let serviceBuilder = new chrome.ServiceBuilder(driverPath);
     let options = new chrome.Options().addArguments("no-sandbox", ...extraArgs);
     if (extensionPaths.length > 0)
       options.addArguments(`load-extension=${extensionPaths.join(",")}`);
@@ -310,6 +333,7 @@ class Chromium extends Browser {
     let builder = new webdriver.Builder();
     builder.forBrowser("chrome");
     builder.setChromeOptions(options);
+    builder.setChromeService(serviceBuilder);
 
     return builder.build();
   }
@@ -334,106 +358,106 @@ class Chromium extends Browser {
             continue;
 
           extensionDetails = shadowRoot.getElementById("detailsButton");
+          break;
         }
-
         if (!extensionDetails)
-          reject("Extension was not found");
+          reject(`${args[1]}: ${args[0]}`);
 
         extensionDetails.click();
         setTimeout(() => resolve(enable()), 100);
       });
-    }, extensionTitle);
+    }, extensionTitle, EXTENSION_NOT_FOUND_ERROR);
   }
 }
 
 /**
- * Download functionality for Firefox. This class can be used statically.
+ * Browser and webdriver functionality for Firefox.
  * @hideconstructor
  * @extends Browser
  */
 class Firefox extends Browser {
-  static async #getVersionForChannel(branch) {
+  static #CHANNELS = ["latest", "beta"];
+
+  static async #getVersionForChannel(channel) {
+    if (!Firefox.#CHANNELS.includes(channel))
+      return channel;
+
     let data = await got("https://product-details.mozilla.org/1.0/firefox_versions.json").json();
-    return branch == "beta" ?
+    return channel == "beta" ?
       data.LATEST_FIREFOX_DEVEL_VERSION : data.LATEST_FIREFOX_VERSION;
   }
 
   static #getBinaryPath(dir) {
-    switch (process.platform) {
-      case "win32":
-        return path.join(dir, "core", "firefox.exe");
-      case "linux":
-        return path.join(dir, "firefox", "firefox");
-      case "darwin":
-        return path.join(dir, "Firefox.app", "Contents", "MacOS", "firefox");
-      default:
-        throw new Error(`Unexpected platform: ${process.platform}`);
-    }
+    checkPlatform();
+    return {
+      win32: path.join(dir, "core", "firefox.exe"),
+      linux: path.join(dir, "firefox", "firefox"),
+      darwin: path.join(dir, "Firefox.app", "Contents", "MacOS", "firefox")
+    }[platform];
   }
 
   static #extractFirefoxArchive(archive, dir) {
-    switch (process.platform) {
+    switch (platform) {
       case "win32":
-        // Procedure inspired from mozinstall:
-        // https://hg.mozilla.org/mozilla-central/file/tip/testing/mozbase/mozinstall/mozinstall/mozinstall.py
         return promisify(exec)(`"${archive}" /extractdir=${dir}`);
       case "linux":
         return extractTar(archive, dir);
       case "darwin":
         return extractDmg(archive, dir);
       default:
-        throw new Error(`Unexpected platform: ${process.platform}`);
+        checkPlatform();
     }
   }
 
-  static async #downloadFirefox(version) {
+  /**
+   * 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".
+   * @return {BrowserBinary}
+   * @throws {Error} Unsupported browser version, Unsupported platform, Browser
+   *   download failed.
+   */
+  static async installBrowser(version = "latest") {
+    const MIN_VERSION = 60;
+
+    checkVersion(version, MIN_VERSION, Firefox.#CHANNELS);
+    let versionNumber = await Firefox.#getVersionForChannel(version);
+
     let [buildPlatform, fileName] = {
-      "win32-ia32": ["win32", `Firefox Setup ${version}.exe`],
-      "win32-x64": ["win64", `Firefox Setup ${version}.exe`],
-      "linux-x64": ["linux-x86_64", `firefox-${version}.tar.bz2`],
-      "darwin-x64": ["mac", `Firefox ${version}.dmg`],
-      "darwin-arm64": ["mac", `Firefox ${version}.dmg`]
-    }[platform];
+      "win32-ia32": ["win32", `Firefox Setup ${versionNumber}.exe`],
+      "win32-x64": ["win64", `Firefox Setup ${versionNumber}.exe`],
+      "linux-x64": ["linux-x86_64", `firefox-${versionNumber}.tar.bz2`],
+      "darwin-x64": ["mac", `Firefox ${versionNumber}.dmg`],
+      "darwin-arm64": ["mac", `Firefox ${versionNumber}.dmg`]
+    }[platformArch];
 
     let snapshotsDir = path.join(snapshotsBaseDir, "firefox");
-    let browserDir = path.join(snapshotsDir, `firefox-${platform}-${version}`);
-    let archive = path.join(snapshotsDir, "cache", fileName);
-
+    let browserDir = path.join(snapshotsDir,
+                               `firefox-${platformArch}-${versionNumber}`);
+    let binary = Firefox.#getBinaryPath(browserDir);
     try {
       await fs.promises.access(browserDir);
-      return Firefox.#getBinaryPath(browserDir);
+      return {binary, versionNumber};
     }
     catch (e) {}
 
+    let archive = path.join(snapshotsDir, "cache", fileName);
     await fs.promises.mkdir(path.dirname(browserDir), {recursive: true});
     try {
       await fs.promises.access(archive);
     }
     catch (e) {
-      let url = `https://archive.mozilla.org/pub/firefox/releases/${version}/${buildPlatform}/en-US/${fileName}`;
-      await download(url, archive);
+      let url = `https://archive.mozilla.org/pub/firefox/releases/${versionNumber}/${buildPlatform}/en-US/${fileName}`;
+      try {
+        await download(url, archive);
+      }
+      catch (err) {
+        throw new Error(`${BROWSER_DOWNLOAD_ERROR}: ${url}\n${err}`);
+      }
     }
-
     await Firefox.#extractFirefoxArchive(archive, browserDir);
-    return Firefox.#getBinaryPath(browserDir);
-  }
 
-  /**
-   * Downloads the browser binary file
-   * @param {string} version - Either "latest", "beta" or a full version
-   *   number (i.e. "68.0"). Defaults to "latest".
-   * @return {BrowserBinary}
-   */
-  static async downloadBinary(version = "latest") {
-    const MIN_VERSION = 60;
-    const CHANNELS = ["latest", "beta"];
-
-    checkVersion(version, MIN_VERSION, CHANNELS);
-
-    let versionNumber = CHANNELS.includes(version) ?
-      await Firefox.#getVersionForChannel(version) : version;
-
-    let binary = await Firefox.#downloadFirefox(versionNumber);
     return {binary, versionNumber};
   }
 
@@ -442,7 +466,7 @@ class Firefox extends Browser {
     headless = true, extensionPaths = [], incognito = false, insecure = false,
     extraArgs = []
   } = {}) {
-    let {binary} = await Firefox.downloadBinary(version);
+    let {binary} = await Firefox.installBrowser(version);
 
     let options = new firefox.Options();
     if (headless)
@@ -471,7 +495,7 @@ class Firefox extends Browser {
           throw err;
         await killDriverProcess("geckodriver");
       }
-    }, 30000, "geckodriver didn't start, likely due to low OS resources", 1000);
+    }, 30000, `${DRIVER_START_ERROR}: geckodriver`, 1000);
 
     for (let extensionPath of extensionPaths) {
       await driver.execute(
@@ -485,10 +509,9 @@ class Firefox extends Browser {
 
   /** @see Browser.enableExtensionInIncognito */
   static async enableExtensionInIncognito(driver, extensionTitle) {
-    let version = await getBrowserVersion(driver);
-    if (version < 87)
-      // The UI workaround assumes web elements only present on Firefox >= 87
-      throw new Error(`Only supported on Firefox >= 87. Current version: ${version}`);
+    let version = (await driver.getCapabilities()).getBrowserVersion();
+    // The UI workaround assumes web elements only present on Firefox >= 87
+    checkVersion(version, 87);
 
     await driver.navigate().to("about:addons");
     await driver.wait(until.elementLocated(By.name("extension")), 1000).click();
@@ -501,33 +524,50 @@ class Firefox extends Browser {
       await elem.click();
       return await driver.findElement(By.name("private-browsing")).click();
     }
-    throw new Error(`Extension "${extensionTitle}" not found`);
+    throw new Error(`${EXTENSION_NOT_FOUND_ERROR}: ${extensionTitle}`);
   }
 }
 
 /**
- * Download functionality for Edge. This class can be used statically.
+ * Browser and webdriver functionality for Edge.
  * @hideconstructor
  * @extends Browser
  */
 class Edge extends Browser {
-  static #DRIVER = "msedgedriver";
+  static #CHANNELS = ["latest", "beta", "dev"];
 
   static async #getVersionForChannel(version) {
-    if (!["latest", "beta", "dev"].includes(version))
-      return {versionNumber: version, channel: "stable"};
+    let channel = "stable";
+    if (Edge.#CHANNELS.includes(version) && version != "latest")
+      channel = version;
 
-    let channel = version == "latest" ? "stable" : version;
     let {body} = await got(`https://packages.microsoft.com/repos/edge/pool/main/m/microsoft-edge-${channel}/`);
-    let regex = /href="microsoft-edge-(stable|beta|dev)_(.*?)-1_/gm;
-    let matches;
-    let versionNumbers = [];
-    while ((matches = regex.exec(body)) !== null)
-      versionNumbers.push(matches[2]);
-
-    let compareVersions = (v1, v2) =>
-      parseInt(v1.split(".")[0], 10) < parseInt(v2.split(".")[0], 10) ? 1 : -1;
-    let versionNumber = versionNumbers.sort(compareVersions)[0];
+    let versionNumber;
+    if (Edge.#CHANNELS.includes(version)) {
+      let regex = /href="microsoft-edge-(stable|beta|dev)_(.*?)-1_/gm;
+      let matches;
+      let versionNumbers = [];
+      while ((matches = regex.exec(body)) !== null)
+        versionNumbers.push(matches[2]);
+
+      let compareVersions = (v1, v2) =>
+        parseInt(v1.split(".")[0], 10) < parseInt(v2.split(".")[0], 10) ?
+          1 : -1;
+      versionNumber = versionNumbers.sort(compareVersions)[0];
+    }
+    else {
+      let split = version.split(".");
+      let minorVersion = split.length == 4 ? parseInt(split.pop(), 10) : -1;
+      let majorVersion = split.join(".");
+      let found;
+      while (!found && minorVersion >= 0) {
+        versionNumber = `${majorVersion}.${minorVersion}`;
+        found = body.includes(versionNumber);
+        minorVersion--;
+      }
+      if (!found)
+        throw new Error(`${UNSUPPORTED_VERSION_ERROR}: ${version}`);
+    }
 
     return {versionNumber, channel};
   }
@@ -539,7 +579,7 @@ class Edge extends Browser {
   }
 
   static #getBinaryPath(channel = "stable") {
-    switch (process.platform) {
+    switch (platform) {
       case "win32":
         let programFiles = process.env["ProgramFiles(x86)"] ?
           "${Env:ProgramFiles(x86)}" : "${Env:ProgramFiles}";
@@ -551,26 +591,28 @@ class Edge extends Browser {
         let appName = Edge.#getDarwinAppName(channel);
         return `${process.env.HOME}/Applications/${appName}.app/Contents/MacOS/${appName}`;
       default:
-        throw new Error(`Unexpected platform: ${process.platform}`);
+        checkPlatform();
     }
   }
 
   /**
-   * Downloads the browser binary file.
+   * 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.53"). Defaults to "latest". This is only
-   *   available on Linux.
+   *   number (i.e. "95.0.1020.40"). Defaults to "latest".
    * @return {BrowserBinary}
+   * @throws {Error} Unsupported browser version, Unsupported platform, Browser
+   *   download failed.
    */
-  static async downloadBinary(version = "latest") {
-    if (process.platform == "win32")
+  static async installBrowser(version = "latest") {
+    if (platform == "win32")
       // Edge is mandatory on Windows, can't be uninstalled or downgraded
       // https://support.microsoft.com/en-us/microsoft-edge/why-can-t-i-uninstall-microsoft-edge-ee150b3b-7d7a-9984-6d83-eb36683d526d
-      throw new Error("Edge download is not supported in Windows");
+      throw new Error(`${UNSUPPORTED_PLATFORM_ERROR}: ${platform}`);
 
     const MIN_VERSION = 95;
-    const CHANNELS = ["latest", "beta", "dev"];
-    checkVersion(version, MIN_VERSION, CHANNELS);
+    checkVersion(version, MIN_VERSION, Edge.#CHANNELS);
     let {versionNumber, channel} = await Edge.#getVersionForChannel(version);
 
     let darwinName = {
@@ -581,14 +623,14 @@ class Edge extends Browser {
     let filename = {
       linux: `microsoft-edge-${channel}_${versionNumber}-1_amd64.deb`,
       darwin: `${darwinName}-${versionNumber}.pkg`
-    }[process.platform];
+    }[platform];
     let darwinArch = process.arch == "arm64" ?
       "03adf619-38c6-4249-95ff-4a01c0ffc962" :
       "C1297A47-86C4-4C1F-97FA-950631F94777";
-    let downloadUrl = {
+    let url = {
       linux: `https://packages.microsoft.com/repos/edge/pool/main/m/microsoft-edge-${channel}/${filename}`,
       darwin: `https://officecdnmac.microsoft.com/pr/${darwinArch}/MacAutoupdate/${filename}`
-    }[process.platform];
+    }[platform];
 
     let snapshotsDir = path.join(snapshotsBaseDir, "edge");
     let archive = path.join(snapshotsDir, "cache", filename);
@@ -600,16 +642,16 @@ class Edge extends Browser {
     catch (e) {}
 
     try {
-      await download(downloadUrl, archive);
+      await download(url, archive);
     }
     catch (err) {
-      throw new Error(`Edge download failed at ${downloadUrl}\n${err}`);
+      throw new Error(`${BROWSER_DOWNLOAD_ERROR}: ${url}\n${err}`);
     }
 
-    if (process.platform == "linux") {
+    if (platform == "linux") {
       await promisify(exec)(`dpkg -i ${archive}`);
     }
-    else if (process.platform == "darwin") {
+    else if (platform == "darwin") {
       let appName = Edge.#getDarwinAppName(channel);
       try {
         await fs.promises.rm(`${process.env.HOME}/Applications/${appName}.app`, {recursive: true});
@@ -629,47 +671,55 @@ class Edge extends Browser {
   }
 
   static async #installDriver() {
+    async function extractEdgeZip(archive, cacheDir, driverPath) {
+      await killDriverProcess("msedgedriver");
+      try {
+        await fs.promises.rm(driverPath, {recursive: true});
+      }
+      catch (e) {} // file does not exist
+      await extractZip(archive, {dir: cacheDir});
+    }
+
     let binary = Edge.#getBinaryPath();
     let versionNumber = await Edge.#getInstalledVersionNumber(binary);
     if (!versionNumber)
-      throw new Error("Edge is not installed");
+      throw new Error(`${BROWSER_NOT_INSTALLED_ERROR}: Edge`);
 
-    let [zip, driver] = {
+    let [zip, driverBinary] = {
       "win32-ia32": ["edgedriver_win32.zip", "msedgedriver.exe"],
       "win32-x64": ["edgedriver_win64.zip", "msedgedriver.exe"],
       "linux-x64": ["edgedriver_linux64.zip", "msedgedriver"],
       "darwin-x64": ["edgedriver_mac64.zip", "msedgedriver"],
       "darwin-arm64": ["edgedriver_arm64.zip", "msedgedriver"]
-    }[platform];
+    }[platformArch];
     let cacheDir = path.join(snapshotsBaseDir, "edge", "cache",
                              `edgedriver-${versionNumber}`);
     let archive = path.join(cacheDir, `${versionNumber}-${zip}`);
+    let driverPath = path.join(cacheDir, driverBinary);
 
-    let vSplit = versionNumber.split(".");
-    let lastNum = parseInt(vSplit[3], 10);
-    while (lastNum >= 0) {
-      try {
-        let attempt = `${vSplit[0]}.${vSplit[1]}.${vSplit[2]}.${lastNum}`;
-        await download(`https://msedgedriver.azureedge.net/${attempt}/${zip}`,
-                       archive);
-        break;
-      }
-      catch (e) {
-        lastNum--;
-      }
-    }
-
-    if (lastNum < 0)
-      throw new Error(`msedgedriver was not found for Edge ${versionNumber}`);
-
-    await killDriverProcess(Edge.#DRIVER);
-    let driverPath = path.join(cacheDir, driver);
     try {
-      await fs.promises.rm(driverPath, {recursive: true});
+      await fs.promises.access(archive);
+      await extractEdgeZip(archive, cacheDir, driverPath);
     }
-    catch (e) {} // file does not exist
-    await extractZip(archive, {dir: cacheDir});
+    catch (e) { // zip file is either not cached or corrupted
+      let vSplit = versionNumber.split(".");
+      let lastNum = parseInt(vSplit[3], 10);
+      while (lastNum >= 0) {
+        try {
+          let attempt = `${vSplit[0]}.${vSplit[1]}.${vSplit[2]}.${lastNum}`;
+          await download(`https://msedgedriver.azureedge.net/${attempt}/${zip}`,
+                         archive);
+          break;
+        }
+        catch (e2) {
+          lastNum--;
+        }
+      }
+      if (lastNum < 0)
+        throw new Error(`${DRIVER_DOWNLOAD_ERROR}: Edge ${versionNumber}`);
 
+      await extractEdgeZip(archive, cacheDir, driverPath);
+    }
     return driverPath;
   }
 
@@ -678,8 +728,8 @@ class Edge extends Browser {
     headless = true, extensionPaths = [], incognito = false, insecure = false,
     extraArgs = []
   } = {}) {
-    if (process.platform == "linux" || process.platform == "darwin")
-      await Edge.downloadBinary(version);
+    if (platform == "linux" || platform == "darwin")
+      await Edge.installBrowser(version);
 
     let driverPath = await Edge.#installDriver();
     let serviceBuilder = new edge.ServiceBuilder(driverPath);
@@ -718,17 +768,19 @@ class Edge extends Browser {
         await button.click();
         return await driver.findElement(By.id("itemAllowIncognito")).click();
       }
-      throw new Error("Details button not found");
+      throw new Error(`${ELEMENT_NOT_FOUND_ERROR}: Details button`);
     }
-    throw new Error(`Extension "${extensionTitle}" not found`);
+    throw new Error(`${EXTENSION_NOT_FOUND_ERROR}: ${extensionTitle}`);
   }
 }
 
 /**
  * @type {Object}
- * @property {Chromium} chromium - Download functionality for Chromium.
- * @property {Firefox} firefox - Download functionality for Firefox.
- * @property {Edge} edge - Download functionality for Edge.
+ * @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,

package/src/utils.js

@@ -23,6 +23,7 @@ import {exec} from "child_process";
 
 import got from "got";
 import dmg from "dmg";
+import Jimp from "jimp";
 
 /**
  * Downloads url resources.
@@ -77,11 +78,6 @@ export async function extractDmg(archive, dir) {
   }
 }
 
-export async function getBrowserVersion(driver) {
-  let version = (await driver.getCapabilities()).getBrowserVersion();
-  return version ? parseInt(version.split(".")[0], 10) : null;
-}
-
 // Useful to unlock the driver file before replacing it or executing it
 export async function killDriverProcess(driverName) {
   let cmd = `kill $(pgrep ${driverName})`;
@@ -148,3 +144,62 @@ export function wait(condition, timeout = 0, message, pollTimeout = 100) {
 
   return result;
 }
+
+/**
+ * @typedef {Object} Jimp
+ * @see https://github.com/oliver-moran/jimp/tree/master/packages/jimp
+ */
+
+/**
+ * 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.
+ * @return {Jimp} A Jimp image object containing the screenshot.
+ * @example
+ * // Getting a base-64 encoded PNG from the returned Jimp image
+ * let image = await takeFullPageScreenshot(driver);
+ * let encodedPNG = await image.getBase64Async("image/png");
+ */
+export async function takeFullPageScreenshot(driver, hideScrollbars = true) {
+  // On macOS scrollbars appear and disappear overlapping the content as
+  // scrolling occurs. Hiding the scrollbars helps getting reproducible
+  // screenshots.
+  if (hideScrollbars) {
+    await driver.executeScript(() => {
+      if (!document.head)
+        return;
+      let style = document.createElement("style");
+      style.textContent = "html { overflow-y: scroll; }";
+      document.head.appendChild(style);
+      if (document.documentElement.clientWidth == window.innerWidth)
+        style.textContent = "html::-webkit-scrollbar { display: none; }";
+      else
+        document.head.removeChild(style);
+    });
+  }
+
+  let fullScreenshot = new Jimp(0, 0);
+  while (true) {
+    let [width, height, offset] = await driver.executeScript((...args) => {
+      window.scrollTo(0, args[0]);
+      // Math.ceil rounds up potential decimal values on window.scrollY,
+      // ensuring the loop will not hang due to never reaching enough
+      // fullScreenshot's height.
+      return [document.documentElement.clientWidth,
+              document.documentElement.scrollHeight,
+              Math.ceil(window.scrollY)];
+    }, fullScreenshot.bitmap.height);
+    let data = await driver.takeScreenshot();
+    let partialScreenshot = await Jimp.read(Buffer.from(data, "base64"));
+    let combinedScreenshot =
+      new Jimp(width, offset + partialScreenshot.bitmap.height);
+    combinedScreenshot.composite(fullScreenshot, 0, 0);
+    combinedScreenshot.composite(partialScreenshot, 0, offset);
+    fullScreenshot = combinedScreenshot;
+    if (fullScreenshot.bitmap.height >= height)
+      break;
+  }
+
+  return fullScreenshot;
+}

package/test/browsers.js

@@ -19,12 +19,11 @@ import fs from "fs";
 import expect from "expect";
 import path from "path";
 
-import {BROWSERS, snapshotsBaseDir} from "../index.js";
+import {BROWSERS, snapshotsBaseDir, takeFullPageScreenshot} from "../index.js";
 import {killDriverProcess} from "../src/utils.js";
+import Jimp from "jimp";
 
-// Required to set the driver path on Windows
-import "chromedriver";
-import "geckodriver";
+import "geckodriver"; // Required to set the driver path on Windows
 
 const VERSIONS = {
   chromium: ["latest", "75.0.3770.0", "beta", "dev"],
@@ -32,7 +31,7 @@ const VERSIONS = {
   edge: ["latest", "95.0.1020.40", "beta", "dev"]
 };
 const TEST_URL = "https://gitlab.com/eyeo/developer-experience/get-browser-binary";
-let extensionPaths = [path.resolve(process.cwd(), "test", "extension")];
+const TEST_URL_LONG_PAGE = "https://abptestpages.org/";
 
 async function switchToHandle(driver, testFn) {
   for (let handle of await driver.getAllWindowHandles()) {
@@ -44,7 +43,6 @@ async function switchToHandle(driver, testFn) {
     catch (e) {
       continue;
     }
-
     if (testFn(url))
       return handle;
   }
@@ -90,11 +88,28 @@ expect.extend({
   }
 });
 
-for (let browser of Object.keys(BROWSERS)) {
-  describe(`Browser: ${browser}`, function() {
-    this.timeout(150000);
+function getExtension(browser, version) {
+  let manifest = "mv2";
+  // The latest Edge installed on the Gitlab Windows Shared Runners is Edge 79,
+  // which does not support manifest v3. More info:
+  // https://gitlab.com/eyeo/developer-experience/get-browser-binary/-/issues/29
+  let windowsSharedRunners =
+    browser == "edge" && process.platform == "win32" && process.env.CI_JOB_ID;
+  if (["chromium", "edge"].includes(browser) &&
+      ["latest", "beta", "dev"].includes(version) && !windowsSharedRunners)
+    manifest = "mv3";
+
+  let extensionPaths =
+    [path.resolve(process.cwd(), "test", "extension", manifest)];
+  return {extensionPaths, manifest};
+}
 
+for (let browser of Object.keys(BROWSERS)) {
+  describe(`Browser: ${browser}`, () => {
     before(async() => {
+      if (process.env.TEST_KEEP_SNAPSHOTS == "true")
+        return;
+
       try {
         await fs.promises.rm(snapshotsBaseDir, {recursive: true});
       }
@@ -120,12 +135,12 @@ for (let browser of Object.keys(BROWSERS)) {
 
         afterEach(quitDriver);
 
-        it("downloads", async function() {
+        it("installs", async function() {
           if (browser == "edge" && process.platform == "win32")
             this.skip();
 
           let {binary, versionNumber} =
-            await BROWSERS[browser].downloadBinary(version);
+            await BROWSERS[browser].installBrowser(version);
           let browserName = browser == "edge" ? /(edge|Edge)/ : browser;
           expect(binary).toEqual(expect.stringMatching(browserName));
 
@@ -133,6 +148,9 @@ for (let browser of Object.keys(BROWSERS)) {
             await BROWSERS[browser].getInstalledVersion(binary);
           expect(installedVersion).toEqual(
             expect.stringContaining(normalize(versionNumber)));
+
+          // Adding the version number to the test title for logging purposes
+          this.test.title = `${this.test.title} [v${versionNumber}]`;
         });
 
         it("runs", async() => {
@@ -167,8 +185,22 @@ for (let browser of Object.keys(BROWSERS)) {
           expect(sizeDevToolsOpen).toMeasureLessThan(sizeDevToolsClosed);
         });
 
+        it("takes a full page screenshot", async() => {
+          driver = await BROWSERS[browser].getDriver(version);
+          await driver.navigate().to(TEST_URL_LONG_PAGE);
+
+          let fullImg = await takeFullPageScreenshot(driver);
+          // Taking a regular webdriver screenshot, which should be shorter
+          let data = await driver.takeScreenshot();
+          let partImg = await Jimp.read(Buffer.from(data, "base64"));
+
+          expect(fullImg.bitmap.width).toBeGreaterThan(0);
+          expect(fullImg.bitmap.height).toBeGreaterThan(partImg.bitmap.height);
+        });
+
         it("loads an extension", async() => {
           let headless = browser == "firefox";
+          let {extensionPaths} = getExtension(browser, version);
 
           driver = await BROWSERS[browser].getDriver(
             version, {headless, extensionPaths});
@@ -179,22 +211,23 @@ for (let browser of Object.keys(BROWSERS)) {
           if (browser == "firefox" && version == "60.0")
             this.skip();
 
+          let {extensionPaths, manifest} = getExtension(browser, version);
           driver = await BROWSERS[browser].getDriver(
             version, {headless: false, extensionPaths, incognito: true});
           await BROWSERS[browser].enableExtensionInIncognito(
-            driver, "Browser download test extension"
+            driver, `Browser test extension - ${manifest}`
           );
           await getHandle(driver, "/index.html");
         });
       });
     }
 
-    it("does not download unsupported versions", async function() {
+    it("does not install unsupported versions", async function() {
       if (browser == "edge" && process.platform == "win32")
         this.skip();
 
       for (let unsupported of ["0.0", "invalid"]) {
-        await expect(BROWSERS[browser].downloadBinary(unsupported))
+        await expect(BROWSERS[browser].installBrowser(unsupported))
           .rejects.toThrow(`Unsupported browser version: ${unsupported}`);
       }
     });

package/test/extension/mv2/index.html

@@ -0,0 +1 @@
+<h1>Browser test extension - mv2</h1>

package/test/extension/{manifest.json → mv2/manifest.json}

@@ -1,7 +1,6 @@
 {
-  "name": "Browser download test extension",
+  "name": "Browser test extension - mv2",
   "version": "0.1",
-  "description": "Browser download test extension",
   "manifest_version": 2,
   "background": {
     "scripts": ["background.js"]

package/test/extension/mv3/background.js

@@ -0,0 +1,3 @@
+"use strict";
+
+chrome.tabs.create({url: "index.html"});

package/test/extension/mv3/index.html

@@ -0,0 +1 @@
+<h1>Browser test extension - mv3</h1>

package/test/extension/mv3/manifest.json

@@ -0,0 +1,8 @@
+{
+  "name": "Browser test extension - mv3",
+  "version": "0.1",
+  "manifest_version": 3,
+  "background": {
+    "service_worker": "background.js"
+  }
+}

package/test/extension/index.html

@@ -1 +0,0 @@
-<h1>Browser download test extension</h1>