get-browser-binary

Install specific browser versions for Chromium, Chrome for Testing, Firefox and Edge, and their matching selenium webdriver.

Getting started

The sample below shows how to install the latest Chromium and run it using selenium webdriver:

import { BROWSERS } from "@eyeo/get-browser-binary";

(async function example() {
  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/");
  await driver.quit();
})();

test/browsers.js provides other usage examples of the library.

For more information, please refer to the API documention. If you are already on the documentation page, you may find the API contents on the right side.

Supported browser versions

• Chromium >= 127
• Chrome for Testing >= 127
• Firefox >= 128
• Edge >= 127 (Linux), Edge >= latest (MacOS, Windows)

These follow the browser versions supported by the eyeo extensions. Versions are dropped in line with the extensions' browser deprecation policy.

Chromium vs. Chrome for Testing

Both are Chromium-based, but they come from different distribution pipelines:

Chromium is built from the open-source Chromium project. Snapshot builds are identified by their commit rather than a stable version string, and chromedriver must be sourced separately and kept in sync manually. Snapshot availability is not guaranteed, as older builds can disappear from the CDN.

Chromium supports both MV2 and MV3.

Chrome for Testing (CfT) is an official Google distribution introduced specifically for automated testing. Key differences:

• Each release is identified by a stable Chrome version string (e.g. 113.0.5672.0) and ships with a matching chromedriver, eliminating version mismatch issues.
• Releases are permanently archived, so pinned versions remain reproducible.
• Available through the Chrome for Testing availability dashboard.
• Supports MV3 only.

For CI pipelines, Chrome for Testing is preferable because the versioned, paired chromedriver distribution makes builds more reproducible.

Chromium snapshots remain useful when MV2 support is required.

Verbose logging

Set the VERBOSE environment variable to "true" to get verbose logging on download requests.

Offline execution

It is possible to run browsers offline as long as they have been previously installed. Example:

// Online
let { binary } = await BROWSERS[browser].installBrowser(version);
console.log(binary); // keep the browser binary location to use it offline
let driver = await BROWSERS[browser].getDriver(version); // let the driver binary download

// Offline
let customBrowserBinary = "<browser binary location>";
let driver = await BROWSERS[browser].getDriver(version, {
  customBrowserBinary,
});

Development

Prerequisites

• Node >= 18
• npm >= 9
• unzip on Linux and macOS, needed to install Chromium and Chrome for Testing (Windows uses the built-in tar.exe)

Installing/Updating dependencies

npm install

Folders to ignore / cache

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).

On the other hand, ./browser-snapshots/<browser_name>/cache will hold all the downloaded installation files required by <browser_name>. Therefore, it may be useful to add ./browser-snapshots/*/cache to the list of cached folders in your CI pipeline configuration.

Linting and formatting

npm run lint         # ESLint + Prettier check
npm run lint-fix     # auto-fix ESLint issues and reformat with Prettier

Testing

Running all tests:

npm test

Options

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:

npm test -- --timeout <ms>

By default, tests delete the ./browser-snapshots before each Browser suite runs. To change that behavior you may set the TEST_KEEP_SNAPSHOTS environment variable to true. Example:

TEST_KEEP_SNAPSHOTS=true npm test

Test server

Tests use a local http server, which is managed by the npm test command. If needed, the test server can also run independently:

npm run test-server

Then tests may be executed on a separate session. Example:

npm run test-suite -- --grep "chromium.*latest"

Running tests on Docker

Useful to reproduce the CI environment of the test:browsers:linux job.

Intel/AMD architecture

docker build -f test/docker/Dockerfile -t browsers .
docker run --shm-size=512m -it browsers

The grep and timeout options can also be used on Docker via the TEST_ARGS parameter:

docker run --shm-size=512m -e TEST_ARGS="--grep chromium.*latest --timeout 100000" -it browsers

ARM architecture (M1/M2 Apple Silicon)

The run is done emulating the AMD architecture. Requirements:

• macOS >= 13 (Ventura)
• Rosetta
• The feature "Use Rosetta for x86/amd64 emulation on Apple Silicon" enabled in Docker

The --platform option should be used when running the image:

docker run --platform linux/amd64 --shm-size=512m -e TEST_ARGS="--grep chromium.*latest" -it browsers

Loading extensions in macOS

macOS TCC (Transparency, Consent, and Control) adds extra protection to the following folders:

• Documents
• Downloads
• Desktop

If extensions happen to be located within TCC folders, when Chrome attempts to load them, macOS denies them access.

What usually follows is a permission dialog. However in headless mode no permission dialog is shown, and extensions silently fail to load.

Errors following that may be very different. Here's one example:

         updates an extension:
     TimeoutError: /index.html did not open
Wait timed out after 8008ms

To avoid such problems, move the extension folder outside of TCC-protected directories (e.g. directly under your home directory).

Building the documentation

npm run docs

Release instructions

Release instructions are maintained in the GitLab wiki.

Repos that depend on get-browser-binary (e.g. Extensions and testpages.adblockplus.org) need to be updated to consume the new version after a release.

Code of Conduct

All contributors to this project are required to read and follow our code of conduct.