@eyeo/get-browser-binary 0.1.1

package/.eslintignore

@@ -0,0 +1,3 @@
+/node_modules/
+/browser-snapshots/
+/docs/

package/.eslintrc.json

@@ -0,0 +1,41 @@
+{
+  "extends": [
+    "eslint-config-eyeo"
+  ],
+  "root": true,
+  "env": {
+    "es2022": true,
+    "node": true
+  },
+  "rules": {
+    "brace-style": ["error", "stroustrup"],
+    "curly": [
+      "error",
+      "multi-or-nest",
+      "consistent"
+    ],
+    "max-len": [
+      "error",
+      {
+        "ignoreUrls": true,
+        "ignoreRegExpLiterals": true,
+        "ignoreTemplateLiterals": true
+      }
+    ],
+    "valid-jsdoc": 0
+  },
+  "parserOptions": {
+    "sourceType": "module",
+    "ecmaVersion": 2022
+  },
+  "overrides": [
+    {
+      "files": [
+        "background.js"
+      ],
+      "parserOptions": {
+        "sourceType": "script"
+      }
+    }
+  ]
+}

package/.gitlab-ci.yml

@@ -0,0 +1,75 @@
+default:
+  image: registry.gitlab.com/eyeo/docker/adblockplus-ci:node16-no-python
+  interruptible: true
+
+stages:
+  - test
+  - docs
+
+variables:
+  npm_config_audit: "false"
+  npm_config_fund: "false"
+  npm_config_prefer_offline: "true"
+
+cache:
+  - key:
+      prefix: $CI_JOB_IMAGE
+      files:
+      - package-lock.json
+    paths:
+    - node_modules/
+
+test:linux:
+  stage: test
+  before_script:
+    - apt-get update && apt-get install -y procps
+    - npm install
+    # https://www.how2shout.com/linux/install-microsoft-edge-on-linux/
+    - wget https://packages.microsoft.com/keys/microsoft.asc
+    - cat microsoft.asc | gpg --dearmor > microsoft.gpg
+    - install -o root -g root -m 644 microsoft.gpg /etc/apt/trusted.gpg.d/
+    - echo "deb [arch=amd64] https://packages.microsoft.com/repos/edge stable main" > /etc/apt/sources.list.d/microsoft-edge-dev.list
+    - rm microsoft.*
+    - apt-get update && apt-get install -y microsoft-edge-stable
+  script:
+    - npm run lint
+    - xvfb-run -a npm test -- -g "chromium (latest|beta)"
+    - xvfb-run -a npm test -- -g "chromium dev"
+    - xvfb-run -a npm test -- -g "chromium 77"
+    - xvfb-run -a npm test -- -g "(edge|firefox)"
+
+test:windows:
+  stage: test
+  variables:
+    CI_PROJECT_ID_MAINSTREAM: 36688302
+  before_script:
+    - Invoke-WebRequest
+        -Uri "${Env:CI_API_V4_URL}/projects/${Env:CI_PROJECT_ID_MAINSTREAM}/packages/generic/microsoft-edge/79.0.309/MicrosoftEdgeEnterpriseX64.msi"
+        -Headers @{'JOB-TOKEN' = $Env:CI_JOB_TOKEN}
+        -OutFile 'MicrosoftEdgeEnterpriseX64.msi'
+    - Start-Process msiexec
+        -ArgumentList "/i MicrosoftEdgeEnterpriseX64.msi /norestart /qn" -Wait
+    - choco upgrade -y nodejs --version 16.10.0
+    - npm install
+  script:
+    - npm test -- -g "chromium latest"
+    - npm test -- -g "chromium beta"
+    - npm test -- -g "chromium dev"
+    - npm test -- -g "chromium 77"
+    - npm test -- -g "edge"
+  tags:
+    - shared-windows
+    - windows
+    - windows-1809
+  cache: {}
+
+docs:
+  stage: docs
+  needs: []
+  before_script:
+    - npm install
+  script:
+    - npm run docs
+  artifacts:
+    paths:
+      - docs/

package/README.md

@@ -0,0 +1,65 @@
+# get-browser-binary
+
+Download specific browser versions for Chromium, Firefox and Edge, and their
+matching [selenium webdriver](https://www.selenium.dev/selenium/docs/api/javascript/index.html).
+
+Note: Edge download is not implemented, and it is assumed to be already
+installed on the running system. In that case, the matching `msedgedriver`
+will be downloaded accordingly.
+
+## Getting started
+
+The sample below shows how to download the latest Chromium and run it using
+selenium webdriver:
+
+```javascript
+import {BROWSERS} from "@eyeo/get-browser-binary";
+
+(async function example() {
+  let {chromium} = BROWSERS;
+
+  let {binary} = await chromium.downloadBinary();
+  console.log(`Chromium binary downloaded to ${binary}`);
+
+  let driver = await chromium.getDriver();
+  await driver.navigate().to("https://example.com/");
+  await driver.quit();
+})();
+
+```
+
+[test/runner.js](https://gitlab.com/eyeo/developer-experience/get-browser-binary/-/blob/main/test/runner.js)
+provides other usage examples of the library.
+
+For more information, please refer to the [API documention](https://gitlab.com/eyeo/developer-experience/get-browser-binary/-/jobs/artifacts/main/file/docs/index.html?job=docs).
+If you are already on the documentation page, you may find the API contents on
+the right side.
+
+## Development
+
+### Prerequisites
+
+- Node >= 16.10.0
+- npm >= 7
+
+### Installing/Updating dependencies
+
+```shell
+npm install
+```
+
+## Testing
+
+The `grep` option filters the tests to run with a regular expression. Example:
+
+```shell
+npm test -- -g "chromium latest"
+```
+
+Note: Running all Chromium tests at once is currently not working.
+
+## Building the documentation
+
+```shell
+npm run docs
+```

package/RELEASE_NOTES.md

@@ -0,0 +1,7 @@
+# 0.1.1
+
+Change project name to `get-browser-binary`.
+
+# 0.1.0
+
+Initial release.

package/index.js

@@ -0,0 +1,18 @@
+/*
+ * 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/>.
+ */
+
+export * from "./src/browsers.js";

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@eyeo/get-browser-binary",
+  "version": "0.1.1",
+  "description": "Download browser binaries and matching webdrivers",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/eyeo/developer-experience/get-browser-binary"
+  },
+  "author": "eyeo GmbH",
+  "license": "GPL-3.0",
+  "engines": {
+    "node": ">=16.10.0",
+    "npm": ">=7"
+  },
+  "type": "module",
+  "main": "index.js",
+  "dependencies": {
+    "chromedriver": "^90.0.1",
+    "dmg": "^0.1.0",
+    "extract-zip": "^2.0.1",
+    "fs-extra": "^10.0.0",
+    "geckodriver": "^2.0.4",
+    "got": "^11.8.2",
+    "msedgedriver": "^91.0.0",
+    "selenium-webdriver": "^4.2.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.17.0",
+    "eslint-config-eyeo": "^3.2.0",
+    "expect": "^25.5.0",
+    "jsdoc": "^3.6.10",
+    "mocha": "^10.0.0"
+  },
+  "scripts": {
+    "docs": "jsdoc --readme README.md --destination docs src/browsers.js",
+    "lint": "eslint --ext js .",
+    "test": "mocha test/runner.js --"
+  }
+}

package/src/browsers.js

@@ -0,0 +1,541 @@
+/*
+ * 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 path from "path";
+import {exec, execFile} from "child_process";
+import {promisify} from "util";
+import fs from "fs";
+
+import got from "got";
+import webdriver from "selenium-webdriver";
+import chrome from "selenium-webdriver/chrome.js";
+import firefox from "selenium-webdriver/firefox.js";
+import command from "selenium-webdriver/lib/command.js";
+import extractZip from "extract-zip";
+
+import {download, extractTar, extractDmg, runWinInstaller, getBrowserVersion}
+  from "./utils.js";
+
+/**
+ * Root folder where browser and webdriver binaries get downloaded.
+ * @type {string}
+ */
+export let snapshotsBaseDir = path.join(process.cwd(), "browser-snapshots");
+
+let {until, By} = webdriver;
+const ERROR_INCOGNITO_NOT_SUPPORTED = "Incognito mode is not supported";
+const ERROR_DOWNLOAD_NOT_SUPPORTED =
+  "Downloading this browser is not supported";
+
+/**
+ * Base class for browser download functionality. Please see subclasses for
+ * browser specific details.
+ * @hideconstructor
+ */
+class Browser {
+  /**
+   * @typedef {Object} BrowserBinary
+   * @property {string} binary - The path to the Chromium binary.
+   */
+
+  /**
+   * Downloads the browser binary file.
+   * @param {string} version - Either full version number or channel/release.
+   *   Please find examples on the subclasses.
+   * @return {BrowserBinary}
+   */
+  static async downloadBinary(version) {
+    throw new Error(ERROR_DOWNLOAD_NOT_SUPPORTED);
+  }
+
+  /**
+   * @typedef {Object} webdriver
+   * @see https://www.selenium.dev/selenium/docs/api/javascript/index.html
+   */
+
+  /**
+   * 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. On Edge this parameter has
+   *   no effect.
+   * @param {boolean?} headless - Run the browser in headless mode, or not.
+   * @param {Array.<string>?} extensionPaths - Loads extensions to the running
+   *   browser.
+   * @param {boolean?} incognito - Runs the browser in incognito mode, or not.
+   * @param {boolean?} insecure - Forces the browser to accept insecure
+       certificates, or not.
+   * @return {webdriver}
+   */
+  static async getDriver(version, headless = true, extensionPaths = [],
+                         incognito = false, insecure = false) {
+    // 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 extebsion to be enabled.
+   * @return {webdriver}
+   */
+  static async enableExtensionInIncognito(driver, extensionTitle) {
+    throw new Error(ERROR_INCOGNITO_NOT_SUPPORTED);
+  }
+}
+
+/**
+ * Download functionality for Chromium. This class can be used statically.
+ * @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 async #getLatestVersion(channel = "stable") {
+    let os = process.platform;
+    if (os == "win32")
+      os = process.arch == "x64" ? "win64" : "win";
+    else if (os == "darwin")
+      os = process.arch == "arm64" ? "mac_arm64" : "mac";
+
+    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, branch_base_position: base} = release;
+
+    if (release.true_branch && release.true_branch.includes("_")) {
+      // A wrong base may be caused by a mini-branch (patched) release
+      // In that case, the base is taken from the unpatched version
+      version = [...version.split(".").slice(0, 3), "0"].join(".");
+      base = await Chromium.#getBranchBasePosition(version);
+    }
+
+    return {version, base};
+  }
+
+  static #getChromiumBinary(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}`);
+    }
+  }
+
+  static async #downloadChromium(chromiumRevision) {
+    const MAX_VERSION_DECREMENTS = 50;
+
+    let revision = parseInt(chromiumRevision, 10);
+    let startingRevision = revision;
+    let platform = `${process.platform}-${process.arch}`;
+
+    let buildTypes = {
+      "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"]
+    };
+
+    let [platformDir, fileName] = buildTypes[platform];
+    let archive = null;
+    let browserDir = null;
+    let snapshotsDir = path.join(snapshotsBaseDir, "chromium");
+
+    while (true) {
+      browserDir = path.join(snapshotsDir, `chromium-${platform}-${revision}`);
+
+      try {
+        await fs.promises.access(browserDir);
+        return {binary: Chromium.#getChromiumBinary(browserDir), revision};
+      }
+      catch (e) {}
+
+      await fs.promises.mkdir(path.dirname(browserDir), {recursive: true});
+
+      archive = path.join(snapshotsDir, "cache", `${revision}-${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`,
+            archive);
+        }
+        break;
+      }
+      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}`);
+      }
+    }
+
+    await extractZip(archive, {dir: browserDir});
+    return {binary: Chromium.#getChromiumBinary(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) {
+    let base;
+    if (version && !(version == "beta" || version == "dev"))
+      base = await Chromium.#getBranchBasePosition(version);
+    else
+      ({version, base} = await Chromium.#getLatestVersion(version));
+
+    let {binary, revision} = await Chromium.#downloadChromium(base);
+    return {binary, downloadedVersion: version, revision};
+  }
+
+  static async #installDriver(revision, version) {
+    let platform = `${process.platform}-${process.arch}`;
+    let buildTypes = {
+      "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"]
+    };
+    let [dir, zip, driver] = buildTypes[platform];
+
+    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}`);
+
+    await download(`https://commondatastorage.googleapis.com/chromium-browser-snapshots/${dir}/${revision}/${zip}`,
+                   archive);
+    await extractZip(archive, {dir: cacheDir});
+    await fs.promises.mkdir(destinationDir, {recursive: true});
+    try {
+      await fs.promises.copyFile(path.join(cacheDir, zip.split(".")[0], driver),
+                                 path.join(destinationDir, driver));
+    }
+    catch (err) {
+      // https://gitlab.com/eyeo/developer-experience/get-browser-binary/-/issues/3
+      if (!err.toString().includes("copyfile"))
+        throw err;
+    }
+  }
+
+  /** @see Browser.getDriver */
+  static async getDriver(version, headless = true, extensionPaths = [],
+                         incognito = false, insecure = false) {
+    if (incognito)
+      throw new Error(ERROR_INCOGNITO_NOT_SUPPORTED);
+
+    let {binary, revision, downloadedVersion} =
+      await Chromium.downloadBinary(version);
+    await Chromium.#installDriver(revision, downloadedVersion);
+
+    let options = new chrome.Options().addArguments("no-sandbox");
+    if (extensionPaths.length > 0)
+      options.addArguments(`load-extension=${extensionPaths.join(",")}`);
+    if (headless)
+      options.headless();
+    if (insecure)
+      options.addArguments("ignore-certificate-errors");
+    options.setChromeBinaryPath(binary);
+
+    let builder = new webdriver.Builder();
+    builder.forBrowser("chrome");
+    builder.setChromeOptions(options);
+
+    return builder.build();
+  }
+}
+
+/**
+ * Download functionality for Firefox. This class can be used statically.
+ * @hideconstructor
+ * @extends Browser
+ */
+class Firefox {
+  static async #getLatestVersion(branch) {
+    let data = await got("https://product-details.mozilla.org/1.0/firefox_versions.json").json();
+    return branch == "beta" ?
+      data.LATEST_FIREFOX_DEVEL_VERSION : data.LATEST_FIREFOX_VERSION;
+  }
+
+  static #getFirefoxBinary(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}`);
+    }
+  }
+
+  static #extractFirefoxArchive(archive, dir) {
+    switch (process.platform) {
+      case "win32":
+        return runWinInstaller(archive, dir);
+      case "linux":
+        return extractTar(archive, dir);
+      case "darwin":
+        return extractDmg(archive, dir);
+      default:
+        throw new Error(`Unexpected platform: ${process.platform}`);
+    }
+  }
+
+  static async #downloadFirefox(version) {
+    let {platform} = process;
+    if (platform == "win32")
+      platform += "-" + process.arch;
+    let buildTypes = {
+      "win32-ia32": ["win32", `Firefox Setup ${version}.exe`],
+      "win32-x64": ["win64", `Firefox Setup ${version}.exe`],
+      "linux": ["linux-x86_64", `firefox-${version}.tar.bz2`],
+      "darwin": ["mac", `Firefox ${version}.dmg`]
+    };
+
+    let snapshotsDir = path.join(snapshotsBaseDir, "firefox");
+    let browserDir = path.join(snapshotsDir, `firefox-${platform}-${version}`);
+    try {
+      await fs.promises.access(browserDir);
+      return Firefox.#getFirefoxBinary(browserDir);
+    }
+    catch (e) {}
+
+    await fs.promises.mkdir(path.dirname(browserDir), {recursive: true});
+
+    let [buildPlatform, fileName] = buildTypes[platform];
+    let archive = path.join(snapshotsDir, "cache", fileName);
+
+    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);
+    }
+
+    await Firefox.#extractFirefoxArchive(archive, browserDir);
+    return Firefox.#getFirefoxBinary(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) {
+    if (!version || version == "beta")
+      version = await Firefox.#getLatestVersion(version);
+
+    let binary = await Firefox.#downloadFirefox(version);
+    return {binary};
+  }
+
+  /** @see Browser.getDriver */
+  static async getDriver(version, headless = true, extensionPaths = [],
+                         incognito = false, insecure = false) {
+    let {binary} = await Firefox.downloadBinary(version);
+
+    let options = new firefox.Options();
+    if (headless)
+      options.headless();
+    if (incognito)
+      options.addArguments("--private");
+    if (insecure)
+      options.set("acceptInsecureCerts", true);
+    options.setBinary(binary);
+
+    let driver = await new webdriver.Builder()
+      .forBrowser("firefox")
+      .setFirefoxOptions(options)
+      .build();
+
+    for (let extensionPath of extensionPaths) {
+      await driver.execute(
+        new command.Command("install addon")
+          .setParameter("path", extensionPath)
+          .setParameter("temporary", true)
+      );
+    }
+    return driver;
+  }
+
+  /** @see Browser.enableExtensionInIncognito */
+  static async enableExtensionInIncognito(driver, extensionTitle) {
+    // Allowing the extension in private browsing can't happen programmatically:
+    // https://bugzilla.mozilla.org/show_bug.cgi?id=1729315
+    // Therefore, that is done through the UI
+    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}`);
+    }
+
+    await driver.navigate().to("about:addons");
+    await driver.wait(until.elementLocated(By.name("extension")), 1000).click();
+
+    for (let elem of await driver.findElements(By.className("card addon"))) {
+      let text = await elem.getAttribute("innerHTML");
+      if (!text.includes(extensionTitle))
+        continue;
+
+      await elem.click();
+      return await driver.findElement(By.name("private-browsing")).click();
+    }
+    throw new Error(`Extension "${extensionTitle}" not found`);
+  }
+}
+
+/**
+ * Download functionality for Edge. This class can be used statically.
+ * @hideconstructor
+ * @extends Browser
+ */
+class Edge {
+  static #DRIVER = "msedgedriver";
+
+  static async #installDriver() {
+    let stdout;
+    if (process.platform == "win32") {
+      let cmd = "(Get-ItemProperty ${Env:ProgramFiles(x86)}\\Microsoft\\" +
+                "Edge\\Application\\msedge.exe).VersionInfo.ProductVersion";
+      ({stdout} = await promisify(exec)(cmd, {shell: "powershell.exe"}));
+    }
+    else if (process.platform == "darwin") {
+      ({stdout} = await promisify(execFile)(
+        "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+        ["--version"]
+      ));
+    }
+    else if (process.platform == "linux") {
+      ({stdout} = await promisify(execFile)("microsoft-edge", ["--version"]));
+    }
+
+    let version = stdout.trim().replace(/.*\s/, "");
+    if (!version)
+      throw new Error("Edge is not installed");
+
+    // Based on "node_modules/msedgedriver/install.js", adding a fallback
+    // mechanism when msedgedriver doesn't exist for the latest Edge version.
+    let platform = `${process.platform}-${process.arch}`;
+    let buildTypes = {
+      "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"]
+    };
+    let [zip, driver] = buildTypes[platform];
+    let cacheDir = path.join(snapshotsBaseDir, "edge", "cache");
+    let driverBinDir = path.join(process.cwd(), "node_modules", Edge.#DRIVER,
+                                 "bin");
+    let driverLibDir = path.join(process.cwd(), "node_modules", Edge.#DRIVER,
+                                 "lib", Edge.#DRIVER);
+    let archive = path.join(cacheDir, `${version}-${zip}`);
+
+    let vSplit = version.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 ${version}`);
+
+    await extractZip(archive, {dir: cacheDir});
+    for (let destinationDir of [driverBinDir, driverLibDir]) {
+      await fs.promises.mkdir(destinationDir, {recursive: true});
+      try {
+        await fs.promises.copyFile(path.join(cacheDir, driver),
+                                   path.join(destinationDir, driver));
+      }
+      catch (err) {
+        // https://gitlab.com/eyeo/developer-experience/get-browser-binary/-/issues/3
+        if (!err.toString().includes("copyfile"))
+          throw err;
+      }
+    }
+  }
+
+  /** @see Browser.getDriver */
+  static async getDriver(version, headless = true, extensionPaths = [],
+                         incognito = false, insecure = false) {
+    if (incognito)
+      throw new Error(ERROR_INCOGNITO_NOT_SUPPORTED);
+
+    await Edge.#installDriver();
+
+    let args = ["no-sandbox"];
+    if (headless)
+      args.push("headless");
+    if (extensionPaths.length > 0)
+      args.push(`load-extension=${extensionPaths.join(",")}`);
+
+    let builder = new webdriver.Builder();
+    builder.forBrowser("MicrosoftEdge");
+    builder.withCapabilities({
+      "browserName": "MicrosoftEdge",
+      "ms:edgeChromium": true,
+      "ms:edgeOptions": {args},
+      "acceptInsecureCerts": insecure
+    });
+
+    return builder.build();
+  }
+}
+
+
+/**
+ * @type {Object}
+ * @property {Chromium} chromium - Download functionality for Chromium.
+ * @property {Firefox} firefox - Download functionality for Firefox.
+ * @property {Edge} edge - Download functionality for Edge.
+ */
+export const BROWSERS = {
+  chromium: Chromium,
+  firefox: Firefox,
+  edge: Edge
+};

package/src/utils.js

@@ -0,0 +1,80 @@
+/*
+ * 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 fs from "fs";
+import path from "path";
+import {pipeline} from "stream";
+import {promisify} from "util";
+import {exec} from "child_process";
+
+import got from "got";
+import fsExtra from "fs-extra";
+import dmg from "dmg";
+
+export async function download(url, destFile) {
+  let cacheDir = path.dirname(destFile);
+
+  await fs.promises.mkdir(cacheDir, {recursive: true});
+
+  let tempDest = `${destFile}-${process.pid}`;
+  let writable = fs.createWriteStream(tempDest);
+
+  try {
+    await promisify(pipeline)(got.stream(url), writable);
+  }
+  catch (error) {
+    await fs.promises.rm(tempDest, {recursive: true});
+    throw error;
+  }
+
+  await fs.promises.rename(tempDest, destFile);
+}
+
+export async function extractTar(archive, dir) {
+  await fs.promises.mkdir(dir);
+  await promisify(exec)(["tar", "-jxf", archive, "-C", dir].join(" "));
+}
+
+export async function extractDmg(archive, dir) {
+  let mpath = await promisify(dmg.mount)(archive);
+  let files = await fs.promises.readdir(mpath);
+  let target = files.find(file => path.extname(file) == ".app");
+  let source = path.join(mpath, target);
+  await fs.promises.mkdir(dir);
+  try {
+    await fsExtra.copy(source, path.join(dir, target));
+  }
+  finally {
+    try {
+      await promisify(dmg.unmount)(mpath);
+    }
+    catch (err) {
+      console.error(`Error unmounting DMG: ${err}`);
+    }
+  }
+}
+
+export async function runWinInstaller(archive, dir) {
+  // Procedure inspired from mozinstall. Uninstaller will also need to be run.
+  // https://hg.mozilla.org/mozilla-central/file/tip/testing/mozbase/mozinstall/mozinstall/mozinstall.py
+  await promisify(exec)(`"${archive}" /extractdir=${dir}`);
+}
+
+export async function getBrowserVersion(driver) {
+  let version = (await driver.getCapabilities()).getBrowserVersion();
+  return parseInt(version.split(".")[0], 10);
+}

package/test/.eslintrc.json

@@ -0,0 +1,5 @@
+{
+  "env": {
+    "mocha": true
+  }
+}

package/test/extension/.eslintrc.json

@@ -0,0 +1,5 @@
+{
+  "env": {
+    "webextensions": true
+  }
+}

package/test/extension/background.js

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

package/test/extension/index.html

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

package/test/extension/manifest.json

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

package/test/runner.js

@@ -0,0 +1,172 @@
+/*
+ * 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 fs from "fs";
+import expect from "expect";
+import path from "path";
+import {exec} from "child_process";
+import {promisify} from "util";
+
+import {BROWSERS, snapshotsBaseDir} from "../src/browsers.js";
+
+// Required to start the driver on some platforms (e.g. Windows).
+import "chromedriver";
+import "geckodriver";
+import "msedgedriver";
+
+const VERSIONS = {
+  chromium: [void 0, "beta", "dev", "77.0.3865.0"],
+  firefox: [void 0, "beta", "68.0"],
+  edge: [void 0]
+};
+let extensionPaths = [path.resolve(process.cwd(), "test", "extension")];
+
+async function switchToHandle(driver, testFn) {
+  for (let handle of await driver.getAllWindowHandles()) {
+    let url;
+    try {
+      await driver.switchTo().window(handle);
+      url = await driver.getCurrentUrl();
+    }
+    catch (e) {
+      continue;
+    }
+
+    if (testFn(url))
+      return handle;
+  }
+}
+
+async function getHandle(driver, page) {
+  let url;
+  let handle = await driver.wait(() => switchToHandle(driver, handleUrl => {
+    if (!handleUrl)
+      return false;
+
+    url = new URL(handleUrl);
+    return url.pathname == page;
+  }), 8000, `${page} did not open`);
+
+  return handle;
+}
+
+async function killDriverProcess() {
+  for (let name of ["chromedriver", "msedgedriver"]) {
+    let stdout;
+    if (process.platform == "win32") {
+      try {
+        ({stdout} = await promisify(exec)(
+          `(Get-Process -Name ${name}).Id | Stop-Process`,
+          {shell: "powershell.exe"}
+        ));
+      }
+      catch (err) {
+        if (err.toString().includes("Command failed"))
+          continue; // Command will fail when driver process is not found
+
+        throw err;
+      }
+    }
+    else {
+      try {
+        ({stdout} =
+          await promisify(exec)(`ps -a | grep ${name} | grep -v grep`));
+      }
+      catch (err) {
+        if (err.toString().includes("Command failed"))
+          continue; // Command will fail when driver process is not found
+
+        throw err;
+      }
+      let pid = /\s*(\d*)/.exec(stdout)[1]; // first number after any spaces
+      await promisify(exec)(`kill ${pid}`);
+    }
+  }
+}
+
+for (let browser of Object.keys(BROWSERS)) {
+  for (let version of VERSIONS[browser]) {
+    describe(`Browser: ${browser} ${version || "latest"}`, function() {
+      this.timeout(15000);
+
+      before(async() => {
+        try {
+          await fs.promises.rm(snapshotsBaseDir, {recursive: true});
+        }
+        catch (e) {}
+      });
+
+      let driver = null;
+      afterEach(async() => {
+        if (!driver)
+          return;
+
+        await driver.quit();
+        driver = null;
+        // Some platforms don't immediately kill the webdriver process
+        await killDriverProcess();
+      });
+
+      it("downloads", async function() {
+        if (browser == "edge")
+          // Edge download is not implemented. It is assumed to be installed.
+          this.skip();
+
+        this.timeout(40000);
+        let {binary} = await BROWSERS[browser].downloadBinary(version);
+
+        await fs.promises.access(binary);
+        expect(binary).toEqual(
+          expect.stringContaining(path.join(snapshotsBaseDir, browser)));
+      });
+
+      it("runs", async() => {
+        let names = {
+          chromium: "chrome",
+          firefox: "firefox",
+          edge: /(MicrosoftEdge|msedge)/
+        };
+
+        driver = await BROWSERS[browser].getDriver(version);
+        await driver.navigate().to("about:blank");
+
+        expect((await driver.getCapabilities()).getBrowserName())
+          .toEqual(expect.stringMatching(names[browser]));
+      });
+
+      it("loads an extension", async() => {
+        let headless = browser == "firefox";
+
+        driver = await BROWSERS[browser].getDriver(version, headless,
+                                                   extensionPaths);
+        await getHandle(driver, "/index.html");
+      });
+
+      it("loads an extension in incognito mode", async function() {
+        if (browser != "firefox" || version == "68.0")
+          this.skip();
+
+        driver = await BROWSERS[browser].getDriver(version, false,
+                                                   extensionPaths, true);
+        await BROWSERS[browser].enableExtensionInIncognito(
+          driver, "Browser download test extension"
+        );
+        await getHandle(driver, "/index.html");
+      });
+    });
+  }
+}