@eyeo/get-browser-binary 0.13.0 → 0.14.0

package/src/edge.js

@@ -0,0 +1,308 @@
+/*
+ * 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} from "child_process";
+import {promisify} from "util";
+import fs from "fs";
+
+import got from "got";
+import webdriver from "selenium-webdriver";
+import edge from "selenium-webdriver/edge.js";
+import extractZip from "extract-zip";
+
+import {Browser} from "./browser.js";
+import {download, killDriverProcess, wait, getMajorVersion, checkVersion,
+        checkPlatform, errMsg, snapshotsBaseDir, platformArch}
+  from "./utils.js";
+
+let {By} = webdriver;
+let {platform} = process;
+
+/**
+ * Browser and webdriver functionality for Edge.
+ * @hideconstructor
+ * @extends Browser
+ */
+export class Edge extends Browser {
+  static #CHANNELS = ["latest", "beta", "dev"];
+
+  static async #getVersionForChannel(version) {
+    let channel = "stable";
+    if (Edge.#CHANNELS.includes(version) && version != "latest")
+      channel = version;
+
+    let url = `https://packages.microsoft.com/repos/edge/pool/main/m/microsoft-edge-${channel}/`;
+    let body;
+    try {
+      ({body} = await got(url));
+    }
+    catch (err) {
+      throw new Error(`${errMsg.browserVersionCheck}: ${url}\n${err}`);
+    }
+    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) =>
+        getMajorVersion(v1) < getMajorVersion(v2) ? 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(`${errMsg.unsupportedVersion}: ${version}`);
+    }
+
+    return {versionNumber, channel};
+  }
+
+  static #darwinApp = "Microsoft Edge";
+
+  static #getBinaryPath(channel = "stable") {
+    switch (platform) {
+      case "win32":
+        let programFiles = process.env["ProgramFiles(x86)"] ?
+          "${Env:ProgramFiles(x86)}" : "${Env:ProgramFiles}";
+        return `${programFiles}\\Microsoft\\Edge\\Application\\msedge.exe`;
+      case "linux":
+        return channel == "stable" ?
+          "microsoft-edge" : `microsoft-edge-${channel}`;
+      case "darwin":
+        return `${process.env.HOME}/Applications/${Edge.#darwinApp}.app/Contents/MacOS/${Edge.#darwinApp}`;
+      default:
+        checkPlatform();
+    }
+  }
+
+  /**
+   * 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=latest] Either "latest", "beta", "dev" or a full
+   *   version number (i.e. "95.0.1020.40").
+   * @param {number} [downloadTimeout=0] Allowed time in ms for the download of
+   *   install files to complete. When set to 0 there is no time limit.
+   * @return {BrowserBinary}
+   * @throws {Error} Unsupported browser version, Unsupported platform, Browser
+   *   download failed.
+   */
+  static async installBrowser(version = "latest", downloadTimeout = 0) {
+    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(`${errMsg.unsupportedPlatform}: ${platform}`);
+
+    if (platform == "darwin" && version != "latest")
+      // Only latest Edge is supported on macOS
+      throw new Error(`${errMsg.unsupportedVersion}: ${version}. Only "latest" is supported`);
+
+    const MIN_VERSION = 95;
+    checkVersion(version, MIN_VERSION, Edge.#CHANNELS);
+    let {versionNumber, channel} = await Edge.#getVersionForChannel(version);
+
+    let filename = {
+      linux: `microsoft-edge-${channel}_${versionNumber}-1_amd64.deb`,
+      darwin: `MicrosoftEdge-${versionNumber}.pkg`
+    }[platform];
+
+    let snapshotsDir = path.join(snapshotsBaseDir, "edge");
+    let archive = path.join(snapshotsDir, "cache", filename);
+    let binary = Edge.#getBinaryPath(channel);
+    try {
+      if (await Edge.#getInstalledVersionNumber(binary) == versionNumber)
+        return {binary, versionNumber};
+    }
+    catch (e) {}
+
+    let url = `https://packages.microsoft.com/repos/edge/pool/main/m/microsoft-edge-${channel}/${filename}`;
+    try {
+      if (platform == "darwin") {
+        let caskUrl = "https://formulae.brew.sh/api/cask/microsoft-edge.json";
+        let caskJson;
+        try {
+          caskJson = await got(caskUrl).json();
+        }
+        catch (err) {
+          throw new Error(`${errMsg.browserVersionCheck}: ${caskUrl}\n${err}`);
+        }
+        ({url} = process.arch == "arm64" ?
+          caskJson.variations.arm64_ventura : caskJson);
+      }
+      await download(url, archive, downloadTimeout);
+    }
+    catch (err) {
+      throw new Error(`${errMsg.browserDownload}: ${url}\n${err}`);
+    }
+
+    if (platform == "linux") {
+      await promisify(exec)(`dpkg -i ${archive}`);
+    }
+    else if (platform == "darwin") {
+      await fs.promises.rm(`${process.env.HOME}/Applications/${Edge.#darwinApp}.app`, {force: true, recursive: true});
+      await promisify(exec)(`installer -pkg ${archive} -target CurrentUserHomeDirectory`);
+    }
+
+    return {binary, versionNumber};
+  }
+
+  static async #getInstalledVersionNumber(binary) {
+    let installedVersion = await Edge.getInstalledVersion(binary);
+    for (let word of ["beta", "dev", "Beta", "Dev"])
+      installedVersion = installedVersion.replace(word, "");
+    return installedVersion.trim().replace(/.*\s/, "");
+  }
+
+  static async #installDriver(binary) {
+    async function extractEdgeZip(archive, cacheDir, driverPath) {
+      await killDriverProcess("msedgedriver");
+      await fs.promises.rm(driverPath, {force: true});
+      await extractZip(archive, {dir: cacheDir});
+    }
+
+    let binaryPath = binary || Edge.#getBinaryPath();
+    let versionNumber = await Edge.#getInstalledVersionNumber(binaryPath);
+    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_mac64_m1.zip", "msedgedriver"]
+    }[platformArch];
+    let cacheDir = path.join(snapshotsBaseDir, "edge", "cache",
+                             `edgedriver-${versionNumber}`);
+    let archive = path.join(cacheDir, `${versionNumber}-${zip}`);
+    let driverPath = path.join(cacheDir, driverBinary);
+
+    try {
+      await fs.promises.access(archive);
+      await extractEdgeZip(archive, cacheDir, driverPath);
+    }
+    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(`${errMsg.driverDownload}: Edge ${versionNumber}`);
+
+      await extractEdgeZip(archive, cacheDir, driverPath);
+    }
+    return driverPath;
+  }
+
+  /** @see Browser.getDriver */
+  static async getDriver(version = "latest", {
+    headless = true, extensionPaths = [], incognito = false, insecure = false,
+    extraArgs = [], customBrowserBinary
+  } = {}, downloadTimeout = 0) {
+    let binary;
+    let versionNumber;
+    if (!customBrowserBinary && (platform == "linux" || platform == "darwin")) {
+      ({binary, versionNumber} =
+        await Edge.installBrowser(version, downloadTimeout));
+    }
+    else {
+      binary = customBrowserBinary || Edge.#getBinaryPath();
+      versionNumber =
+        await Edge.#getInstalledVersionNumber(binary);
+    }
+
+    let driverPath = await Edge.#installDriver(binary);
+    let serviceBuilder = new edge.ServiceBuilder(driverPath);
+
+    let options = new edge.Options().addArguments("no-sandbox", ...extraArgs);
+    if (headless) {
+      if (versionNumber && getMajorVersion(versionNumber) >= 114)
+        options.addArguments("headless=new");
+      else
+        options.headless();
+    }
+    if (extensionPaths.length > 0)
+      options.addArguments(`load-extension=${extensionPaths.join(",")}`);
+    if (incognito)
+      options.addArguments("inprivate");
+    if (insecure)
+      options.addArguments("ignore-certificate-errors");
+    if (platform == "linux")
+      options.setEdgeChromiumBinaryPath(`/usr/bin/${binary}`);
+
+    let builder = new webdriver.Builder();
+    builder.forBrowser("MicrosoftEdge");
+    builder.setEdgeOptions(options);
+    builder.setEdgeService(serviceBuilder);
+
+    let driver;
+    // On Windows CI, occasionally a SessionNotCreatedError is thrown, likely
+    // due to low OS resources, that's why building the driver is retried
+    await wait(async() => {
+      try {
+        driver = await builder.build();
+        return true;
+      }
+      catch (err) {
+        if (err.name != "SessionNotCreatedError")
+          throw err;
+        await killDriverProcess("msedgedriver");
+      }
+    }, 30000, `${errMsg.driverStart}: msedgedriver`, 1000);
+
+    return driver;
+  }
+
+  /** @see Browser.enableExtensionInIncognito */
+  static async enableExtensionInIncognito(driver, extensionTitle) {
+    await driver.navigate().to("edge://extensions/");
+    for (let elem of await driver.findElements(By.css("[role=listitem]"))) {
+      let text = await elem.getAttribute("innerHTML");
+      if (!text.includes(extensionTitle))
+        continue;
+
+      for (let button of await elem.findElements(By.css("button"))) {
+        text = await elem.getAttribute("innerHTML");
+        if (!text.includes("Details"))
+          continue;
+
+        await button.click();
+        return await driver.findElement(By.id("itemAllowIncognito")).click();
+      }
+      throw new Error(`${errMsg.elemNotFound}: Details button`);
+    }
+    throw new Error(`${errMsg.extensionNotFound}: ${extensionTitle}`);
+  }
+}

package/src/firefox.js

@@ -0,0 +1,216 @@
+/*
+ * 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} from "child_process";
+import {promisify} from "util";
+import fs from "fs";
+
+import got from "got";
+import webdriver from "selenium-webdriver";
+import firefox from "selenium-webdriver/firefox.js";
+
+import {Browser} from "./browser.js";
+import {download, extractTar, extractDmg, killDriverProcess, wait,
+        getMajorVersion, checkVersion, checkPlatform, errMsg, snapshotsBaseDir,
+        platformArch} from "./utils.js";
+
+let {until, By} = webdriver;
+
+/**
+ * Browser and webdriver functionality for Firefox.
+ * @hideconstructor
+ * @extends Browser
+ */
+export class Firefox extends Browser {
+  static #CHANNELS = ["latest", "beta"];
+
+  static async #getVersionForChannel(channel) {
+    if (!Firefox.#CHANNELS.includes(channel))
+      return channel;
+
+    let url = "https://product-details.mozilla.org/1.0/firefox_versions.json";
+    let data;
+    try {
+      data = await got(url).json();
+    }
+    catch (err) {
+      throw new Error(`${errMsg.browserVersionCheck}: ${url}\n${err}`);
+    }
+    return channel == "beta" ?
+      data.LATEST_FIREFOX_DEVEL_VERSION : data.LATEST_FIREFOX_VERSION;
+  }
+
+  static #getBinaryPath(dir) {
+    checkPlatform();
+    return {
+      win32: path.join(dir, "core", "firefox.exe"),
+      linux: path.join(dir, "firefox", "firefox"),
+      darwin: path.join(dir, "Firefox.app", "Contents", "MacOS", "firefox")
+    }[process.platform];
+  }
+
+  static #extractFirefoxArchive(archive, dir) {
+    switch (process.platform) {
+      case "win32":
+        return promisify(exec)(`"${archive}" /extractdir=${dir}`);
+      case "linux":
+        return extractTar(archive, dir);
+      case "darwin":
+        return extractDmg(archive, dir);
+      default:
+        checkPlatform();
+    }
+  }
+
+  static async #getInstalledBrowserInfo(binary) {
+    let installedVersion = await Firefox.getInstalledVersion(binary);
+    // Linux example: "Mozilla Firefox 102.15.0esr"
+    let versionNumber = installedVersion.split(" ")[2] || installedVersion;
+    return {binary, versionNumber};
+  }
+
+  /**
+   * Installs the browser. The Firefox executable gets extracted in the
+   *   {@link snapshotsBaseDir} folder, ready to go.
+   * @param {string} [version=latest] Either "latest", "beta" or a full version
+   *   number (i.e. "68.0").
+   * @param {number} [downloadTimeout=0] Allowed time in ms for the download of
+   *   install files to complete. When set to 0 there is no time limit.
+   * @return {BrowserBinary}
+   * @throws {Error} Unsupported browser version, Unsupported platform, Browser
+   *   download failed.
+   */
+  static async installBrowser(version = "latest", downloadTimeout = 0) {
+    const MIN_VERSION = 68;
+
+    // https://gitlab.com/eyeo/developer-experience/get-browser-binary/-/issues/46
+    if (platformArch == "linux-arm64")
+      return await Firefox.#getInstalledBrowserInfo("/usr/bin/firefox");
+
+    checkVersion(version, MIN_VERSION, Firefox.#CHANNELS);
+    let versionNumber = await Firefox.#getVersionForChannel(version);
+
+    let [buildPlatform, fileName] = {
+      "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-${platformArch}-${versionNumber}`);
+    let binary = Firefox.#getBinaryPath(browserDir);
+    try {
+      await fs.promises.access(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/${versionNumber}/${buildPlatform}/en-US/${fileName}`;
+      try {
+        await download(url, archive, downloadTimeout);
+      }
+      catch (err) {
+        throw new Error(`${errMsg.browserDownload}: ${url}\n${err}`);
+      }
+    }
+    await Firefox.#extractFirefoxArchive(archive, browserDir);
+
+    return {binary, versionNumber};
+  }
+
+  /** @see Browser.getDriver */
+  static async getDriver(version = "latest", {
+    headless = true, extensionPaths = [], incognito = false, insecure = false,
+    extraArgs = [], customBrowserBinary
+  } = {}, downloadTimeout = 0) {
+    let binary;
+    let versionNumber;
+    if (!customBrowserBinary) {
+      ({binary, versionNumber} =
+        await Firefox.installBrowser(version, downloadTimeout));
+    }
+
+    let options = new firefox.Options();
+    if (headless)
+      options.headless();
+    if (incognito)
+      options.addArguments("--private");
+    if (insecure)
+      options.set("acceptInsecureCerts", true);
+    if (extraArgs.length > 0)
+      options.addArguments(...extraArgs);
+    // Enabled by default on Firefox > 68
+    if (versionNumber && getMajorVersion(versionNumber) == 68)
+      options.setPreference("dom.promise_rejection_events.enabled", true);
+
+    options.setBinary(customBrowserBinary || binary);
+
+    let driver;
+    // The OS may be low on resources, that's why building the driver is retried
+    // https://github.com/mozilla/geckodriver/issues/1560
+    await wait(async() => {
+      try {
+        driver = await new webdriver.Builder()
+          .forBrowser("firefox")
+          .setFirefoxOptions(options)
+          .build();
+        return true;
+      }
+      catch (err) {
+        if (err.message != "Failed to decode response from marionette")
+          throw err;
+        await killDriverProcess("geckodriver");
+      }
+    }, 30000, `${errMsg.driverStart}: geckodriver`, 1000);
+
+    for (let extensionPath of extensionPaths) {
+      let temporary = true; // Parameter not documented on the webdriver docs
+      await driver.installAddon(extensionPath, temporary);
+    }
+    return driver;
+  }
+
+  /** @see Browser.enableExtensionInIncognito */
+  static async enableExtensionInIncognito(driver, extensionTitle) {
+    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();
+
+    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(`${errMsg.extensionNotFound}: ${extensionTitle}`);
+  }
+}

package/src/utils.js

@@ -25,6 +25,24 @@ import got from "got";
 import dmg from "dmg";
 import Jimp from "jimp";
 
+export const errMsg = {
+  unsupportedVersion: "Unsupported browser version",
+  unsupportedPlatform: "Unsupported platform",
+  driverDownload: "Driver download failed",
+  driverStart: "Unable to start driver",
+  extensionNotFound: "Extension not found",
+  browserDownload: "Browser download failed",
+  browserNotInstalled: "Browser is not installed",
+  browserVersionCheck: "Checking the browser version failed",
+  elemNotFound: "HTML element not found"
+};
+export const platformArch = `${process.platform}-${process.arch}`;
+
+/**
+ * Root folder where browser and webdriver files get downloaded and extracted.
+ * @type {string}
+ */
+export let snapshotsBaseDir = path.join(process.cwd(), "browser-snapshots");
 
 /**
  * Downloads url resources.
@@ -35,6 +53,10 @@ import Jimp from "jimp";
  * @throws {TypeError} Invalid URL, Download timeout.
  */
 export async function download(url, destFile, timeout = 0) {
+  if (process.env.VERBOSE == "true")
+    // eslint-disable-next-line no-console
+    console.log(`Downloading from ${url} ...`);
+
   let cacheDir = path.dirname(destFile);
   await fs.promises.mkdir(cacheDir, {recursive: true});
 
@@ -215,3 +237,24 @@ export async function takeFullPageScreenshot(driver, hideScrollbars = true) {
 
   return fullScreenshot;
 }
+
+export function getMajorVersion(versionNumber) {
+  let majorVersion = parseInt(versionNumber && versionNumber.split(".")[0], 10);
+  if (isNaN(majorVersion))
+    throw new Error(`${errMsg.unsupportedVersion}: ${versionNumber}`);
+
+  return majorVersion;
+}
+
+export function checkVersion(version, minVersion, channels = []) {
+  if (channels.includes(version))
+    return;
+
+  if (getMajorVersion(version) < minVersion)
+    throw new Error(`${errMsg.unsupportedVersion}: ${version}`);
+}
+
+export function checkPlatform() {
+  if (!["win32", "linux", "darwin"].includes(process.platform))
+    throw new Error(`${errMsg.unsupportedPlatform}: ${process.platform}`);
+}