@eyeo/get-browser-binary

get-browser-binary

Install specific browser versions for Chromium, 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 >= 77 (Chromium ARM >= 92)
• Firefox >= 68
• Edge >= 95 (Windows Edge >= 79)

Note: Installing Edge is not supported on Windows. It is assumed to be installed because it is the default browser on that platform. On macOS, only the latest Edge version is supported.

Verbose logging

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

Development

Prerequisites

• Node >= 18
• npm >= 9

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.

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

Building the documentation

npm run docs

Code of Conduct

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

Changelog

0.16.0

0.16.0

• Starts using selenium's automated driver management. That means additional chromedriver and msedgedriver packages are no longer needed (#67)
• Loads the extension in Firefox by local path instead of being copied to a temporary folder (!104)
• Checks if extensions can be loaded beforehand, by ensuring they contain a manifest.json file. If not, a new Extension manifest file not found error will be thrown (#71)
• Refactors headless runs by not using webdriver's deprecated headless() method (#72)

Testing

• Fixes an issue with npm test which would fail when the grep option would include parenthesis (#69)
• Adds the browser version information in the "runs" test (#74)

Notes for integrators

• Please make sure that your selenium-webdriver package version is at least 4.15.0 (the one used in this release). Also make sure that you are not using the chromedriver nor msedgedriver packages, otherwise the automated driver management may not work as expected (#67)
• If you experience chromedriver issues, try deleting the /browser-snapshots cache folder.