Skip to main content

Driver Binaries

To run automation based on the WebDriver protocol you need to have browser drivers set up that translate the automation commands and are able to execute them in the browser.

Automated setup​

With WebdriverIO v8.14 and above there is no need to manually download and setup any browser drivers anymore as this is handled by WebdriverIO. All you have to do is specify the browser you want to test and WebdriverIO will do the rest.

Customizing the level of automation​

WebdriverIO's have three levels of automation:

1. Download and install the browser using @puppeteer/browsers.

If you specify a browserName/browserVersion combination in the capabilities configuration, WebdriverIO will download and install the requested combination, regardless of whether there's an existing installation on the machine. If you omit browserVersion, WebdriverIO will first try to locate and use an existing installation with locate-app, otherwise it will download and install the current stable browser release. For more details on browserVersion, see here.

caution

Automated browser setup does not support Microsoft Edge. Currently, only Chrome, Chromium and Firefox are supported.

If you have a browser installation on a location that cannot be auto-detected by WebdriverIO, you can specify the browser binary which will disable the automated download and installation.

{
    capabilities: [
        {
            browserName: 'chrome', // or 'firefox' or 'chromium'
            'goog:chromeOptions': { // or 'moz:firefoxOptions' or 'wdio:chromedriverOptions'
                binary: '/path/to/chrome'
            },
        }
    ]
}

2. Download and install the driver using Chromedriver, Edgedriver or Geckodriver.

WebdriverIO will always do this, unless driver binary is specified in the configuration:

{
    capabilities: [
        {
            browserName: 'chrome', // or 'firefox', 'msedge', 'safari', 'chromium'
            'wdio:chromedriverOptions': { // or 'wdio:geckodriverOptions', 'wdio:edgedriverOptions'
                binary: '/path/to/chromedriver' // or 'geckodriver', 'msedgedriver'
            }
        }
    ]
}
info

WebdriverIO won't automatically download Safari driver as it is already installed on macOS.

caution

Avoid specifying a binary for the browser and omitting the corresponding driver binary or vice-versa. If only one of the binary values is specified, WebdriverIO will try to use or download a browser/driver compatible with it. However, in some scenarios it may result in an incompatible combination. Therefore, it's recommended that you always specify both to avoid any problems caused by version incompatibilities.

3. Start/stop the driver.

By default, WebdriverIO will automatically start and stop the driver using an arbitrary unused port. Specifying any of the following configuration will disable this feature which means you'll need to manually start and stop the driver:

Manual setup​

The following describes how you can still set up each driver individually. You can find a list with all drivers in the awesome-selenium README.

tip

If you are looking to set up mobile and other UI platforms, have a look into our Appium Setup guide.

Chromedriver​

To automate Chrome you can download Chromedriver directly on the project website or through the NPM package:

npm install -g chromedriver

You can then start it via:

chromedriver --port=4444 --verbose

Geckodriver​

To automate Firefox download the latest version of geckodriver for your environment and unpack it in your project directory:

npm install geckodriver

Note: Other geckodriver releases are available here. After download you can start the driver via:

/path/to/binary/geckodriver --port 4444

Edgedriver​

You can download the driver for Microsoft Edge on the project website or as NPM package via:

npm install -g edgedriver
edgedriver --version # prints: Microsoft Edge WebDriver 115.0.1901.203 (a5a2b1779bcfe71f081bc9104cca968d420a89ac)

Safaridriver​

Safaridriver comes pre-installed on your MacOS and can be started directly via:

safaridriver -p 4444

Welcome! How can I help?

WebdriverIO AI Copilot