chromedriver

What is chromedriver?

The chromedriver npm package provides a way to manage and control the ChromeDriver, which is a standalone server that implements the WebDriver protocol for Chrome. It is used for automating web applications for testing purposes, enabling you to interact with web pages and perform various browser automation tasks.

What are chromedriver's main functionalities?

Browser Automation

This code sample demonstrates how to use the chromedriver package with Selenium WebDriver to automate a simple browser task. It opens Google, searches for 'webdriver', and waits for the search results page to load.

const { Builder, By, Key, until } = require('selenium-webdriver');
const chrome = require('selenium-webdriver/chrome');
const chromedriver = require('chromedriver');

chrome.setDefaultService(new chrome.ServiceBuilder(chromedriver.path).build());

(async function example() {
  let driver = await new Builder().forBrowser('chrome').build();
  try {
    await driver.get('http://www.google.com/ncr');
    await driver.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN);
    await driver.wait(until.titleIs('webdriver - Google Search'), 1000);
  } finally {
    await driver.quit();
  }
})();

Headless Browser Testing

This code sample shows how to run Chrome in headless mode using the chromedriver package. Headless mode is useful for running tests in environments without a graphical user interface.

const { Builder, By, Key, until } = require('selenium-webdriver');
const chrome = require('selenium-webdriver/chrome');
const chromedriver = require('chromedriver');

chrome.setDefaultService(new chrome.ServiceBuilder(chromedriver.path).build());

(async function example() {
  let options = new chrome.Options();
  options.addArguments('headless');
  let driver = await new Builder().forBrowser('chrome').setChromeOptions(options).build();
  try {
    await driver.get('http://www.google.com/ncr');
    await driver.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN);
    await driver.wait(until.titleIs('webdriver - Google Search'), 1000);
  } finally {
    await driver.quit();
  }
})();

Taking Screenshots

This code sample demonstrates how to take a screenshot of the current browser window using the chromedriver package. The screenshot is saved as a PNG file.

const { Builder, By, Key, until } = require('selenium-webdriver');
const chrome = require('selenium-webdriver/chrome');
const chromedriver = require('chromedriver');

chrome.setDefaultService(new chrome.ServiceBuilder(chromedriver.path).build());

(async function example() {
  let driver = await new Builder().forBrowser('chrome').build();
  try {
    await driver.get('http://www.google.com/ncr');
    await driver.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN);
    await driver.wait(until.titleIs('webdriver - Google Search'), 1000);
    let screenshot = await driver.takeScreenshot();
    require('fs').writeFileSync('screenshot.png', screenshot, 'base64');
  } finally {
    await driver.quit();
  }
})();

Other packages similar to chromedriver

geckodriver

The geckodriver package provides a way to manage and control the GeckoDriver, which is a WebDriver implementation for Firefox. It is similar to chromedriver but is specifically designed for automating Firefox browser tasks.

edgedriver

The edgedriver package provides a way to manage and control the EdgeDriver, which is a WebDriver implementation for Microsoft Edge. It offers similar functionalities to chromedriver but is tailored for automating tasks in the Edge browser.

selenium-webdriver

The selenium-webdriver package is a JavaScript implementation of the WebDriver API, which allows you to write tests that interact with various browsers, including Chrome, Firefox, and Edge. It provides a higher-level API compared to chromedriver and can be used with different browser drivers.

README

ChromeDriver

An NPM wrapper for Selenium ChromeDriver.

Building and Installing

npm install chromedriver

Or grab the source and

node ./install.js

What this is really doing is just grabbing a particular "blessed" (by this module) version of ChromeDriver. As new versions are released and vetted, this module will be updated accordingly.

The package has been set up to fetch and run ChromeDriver for MacOS (darwin), Linux based platforms (as identified by Node.js), and Windows. If you spot any platform weirdness, let us know or send a patch.

Force download

By default this package, when installed, will search for an existing Chromedriver binary in your configured temp directory. If found, and it is the correct version, it will simply copy it to your node_modules directory. You can force it always download by configuring it:

npm install chromedriver --chromedriver-force-download

Or add property to your .npmrc file.

chromedriver_force_download=true

Another option is to use PATH variable CHROMEDRIVER_FORCE_DOWNLOAD.

CHROMEDRIVER_FORCE_DOWNLOAD=true npm install chromedriver

Custom binaries url

This allows you to use your own endpoints for metadata and binaries. It is useful in air gapped scenarios or if you have download restrictions, such as firewalls.

This was changed for version 115 and greater (see details), but implemented in this package starting with version 114.0.2. To see the configuration to prior versions check out this README.md at the latest tag where it was using the legacy urls (114.0.1).

For versions >= 115

There are two urls that need to be configured, one for metadata and one for binaries. The one for metadata is the "CDN url", and the one for binaries is the "CDN binaries url". See Chrome for Testing to understand how these urls work.

Npm config:

For metadata use chromedriver_cdnurl. The default is https://googlechromelabs.github.io. You need to either supply the binary download endpoint, or the binaries url config, see bellow.

For binaries use chromedriver_cdnbinariesurl. The default is to search for the download url using $chromedriver_cdnurl/chrome-for-testing/[version].json, which forms a URL like: https://googlechromelabs.github.io/chrome-for-testing/122.0.6261.57.json.

The resulting url will be something like: https://storage.googleapis.com/chrome-for-testing-public/122.0.6261.57/linux64/chromedriver-linux64.zip.

Keep in mind that this last url is just an example and it might change (as it has happened in the past).

npm install chromedriver --chromedriver_cdnurl=https://npmmirror.com/metadata --chromedriver_cdnbinariesurl=https://npmmirror.com/binaries

Or add these properties to your .npmrc file:

chromedriver_cdnurl=https://npmmirror.com/metadata
chromedriver_cdnbinariesurl=https://npmmirror.com/binaries

Another option is to use the environment variables CHROMEDRIVER_CDNURL and CHROMEDRIVER_CDNBINARIESURL.

CHROMEDRIVER_CDNURL=https://npmmirror.com/metadata CHROMEDRIVER_CDNBINARIESURL=https://npmmirror.com/binaries npm install chromedriver

For versions < 115

There is one url to both metadata and binaries.

To use a mirror of the ChromeDriver binaries use npm config property chromedriver_legacy_cdnurl. Default is https://chromedriver.storage.googleapis.com.

npm install chromedriver --chromedriver_legacy_cdnurl=https://npmmirror.com/mirrors/chromedriver --chromedriver_version=LATEST_114

Or add a property to your .npmrc file:

chromedriver_legacy_cdnurl=https://npmmirror.com/mirrors/chromedriver

Another option is to use the environment variable CHROMEDRIVER_LEGACY_CDNURL.

CHROMEDRIVER_LEGACY_CDNURL=https://npmmirror.com/mirrors/chromedriver npm install chromedriver --chromedriver_version=LATEST_114

Custom binaries file

To get the chromedriver from the filesystem instead of a web request use the npm config property chromedriver_filepath.

npm install chromedriver --chromedriver_filepath=/path/to/chromedriver_mac64.zip

Or add property to your .npmrc file.

chromedriver_filepath=/path/to/chromedriver_mac64.zip

Another option is to use the PATH variable CHROMEDRIVER_FILEPATH

CHROMEDRIVER_FILEPATH=/path/to/chromedriver_mac64.zip

This variable can be used to set either a .zip file or the binary itself, eg:

CHROMEDRIVER_FILEPATH=/bin/chromedriver

Custom download options

Install through a proxy.

npm config set proxy http://[user:pwd]@domain.tld:port
npm config set https-proxy http://[user:pwd]@domain.tld:port

Use different User-Agent.

npm config set user-agent "Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Firefox/52.0"

Skipping chromedriver download

You may wish to skip the downloading of the chromedriver binary file, for example if you know for certain that it is already there or if you want to use a system binary and just use this module as an interface to interact with it.

To achieve this you can use the npm config property chromedriver_skip_download.

npm install chromedriver --chromedriver_skip_download=true

Or add property to your .npmrc file.

chromedriver_skip_download=true

Another option is to use the PATH variable CHROMEDRIVER_SKIP_DOWNLOAD

CHROMEDRIVER_SKIP_DOWNLOAD=true

Running

bin/chromedriver [arguments]

And npm will install a link to the binary in node_modules/.bin as it is wont to do.

Running with Selenium WebDriver

require('chromedriver');
var webdriver = require('selenium-webdriver');
var driver = new webdriver.Builder()
  .forBrowser('chrome')
  .build();

(Tested for selenium-webdriver version 2.48.2)

The path will be added to the process automatically, you don't need to configure it. But you can get it from require('chromedriver').path if you want it.

Running via node

The package exports a path string that contains the path to the chromedriver binary/executable.

Below is an example of using this package via node.

var childProcess = require('child_process');
var chromedriver = require('chromedriver');
var binPath = chromedriver.path;

var childArgs = [
  'some argument'
];

childProcess.execFile(binPath, childArgs, function(err, stdout, stderr) {
  // handle results
});

You can also use the start and stop methods:

var chromedriver = require('chromedriver');

args = [
 // optional arguments
];
chromedriver.start(args);
// run your tests
chromedriver.stop();

With the latest version, you can optionally receive a Promise from the chromedriver.start function:

var returnPromise = true;
chromedriver
  .start(args, returnPromise)
  .then(() => {
    console.log('chromedriver is ready');
  });

Note: if your tests are ran asynchronously, chromedriver.stop() will have to be executed as a callback at the end of your tests

Versioning

The NPM package version tracks the version of chromedriver that will be installed, with an additional build number that is used for revisions to the installer. You can use the package version number to install a specific version, or use the setting to a specific version. If there is a new Chromedriver version available which is not yet available as a version of node-chromedriver, the npm command npm run update-chromedriver in this repository can be used to make the required updates to this module, please submit the change as a PR. To always install the latest version of Chromedriver, use LATEST as the version number:

npm install chromedriver --chromedriver_version=LATEST

Or add property to your .npmrc file.

chromedriver_version=LATEST

Another option is to use env variable CHROMEDRIVER_VERSION.

CHROMEDRIVER_VERSION=LATEST npm install chromedriver

You can force the latest release for a specific major version by specifying LATEST_{VERSION_NUMBER}:

CHROMEDRIVER_VERSION=LATEST_80 npm install chromedriver

You can also force a different version of chromedriver by replacing LATEST with a version number:

CHROMEDRIVER_VERSION=75.0.3770.140 npm install chromedriver

Detect ChromeDriver Version

The NPM package version may not be always compatible to your Chrome version. To get the chromedriver that corresponds to the version of Chrome installed, you can use the npm config property detect_chromedriver_version.

npm install chromedriver --detect_chromedriver_version

Or add property to your .npmrc file.

detect_chromedriver_version=true

Another option is to use environment variable DETECT_CHROMEDRIVER_VERSION.

DETECT_CHROMEDRIVER_VERSION=true npm install chromedriver

Note: When the property detect_chromedriver_version is provided, chromedriver_version and chromedriver_filepath properties are ignored.

Include Chromium

If you don't have Chrome installed, you can check for Chromium version instead by setting the argument include_chromium to true.

npm install chromedriver --include_chromium

Or add property to your .npmrc file.

include_chromium=true

Another option is to use environment variable INCLUDE_CHROMIUM.

INCLUDE_CHROMIUM=true npm install chromedriver

Note: The property INCLUDE_CHROMIUM is ignored if the property DETECT_CHROMEDRIVER_VERSION is not used.

A Note on chromedriver

Chromedriver is not a library for NodeJS.

This is an NPM wrapper and can be used to conveniently make ChromeDriver available. It is not a Node.js wrapper.

Supported Node.js versions

We will do our best to support every supported Node.js versions. See nodejs/Release for the current supported versions. You can also view our build scripts and check the versions there.

Contributing

Questions, comments, bug reports, and pull requests are all welcome. Submit them at the project on GitHub.

Bug reports that include steps-to-reproduce (including code) are the best. Even better, make them in the form of pull requests.

We have added VS Code Remote support with containers. If you are on Windows, set git config core.autocrlf input so you don't get git errors.

Author

Giovanni Bassi, with collaboration from lots of good people.

Thanks for Obvious and their PhantomJS project for heavy inspiration! Check their project on Github.

License

Licensed under the Apache License, Version 2.0.