# Capabilities

A capability is a definition for a remote interface. It helps WebdriverIO to understand in which browser or mobile environment you like to run your tests on. Capabilities are less crucial when developing tests locally as you run it on one remote interface most of the time but becomes more important when running a large set of integration tests in CI/CD.

info

The format of a capability object is well defined by the [WebDriver specification](https://w3c.github.io/webdriver/#capabilities). The WebdriverIO testrunner will fail early if user defined capabilities do not adhere to that specification.

## Custom Capabilities[​](#custom-capabilities "Direct link to Custom Capabilities")

While the amount of fixed defined capabilities is very low, everyone can provide and accept custom capabilities that are specific to the automation driver or remote interface:

### Browser Specific Capability Extensions[​](#browser-specific-capability-extensions "Direct link to Browser Specific Capability Extensions")

* `goog:chromeOptions`: [Chromedriver](https://chromedriver.chromium.org/capabilities) extensions, only applicable for testing in Chrome
* `moz:firefoxOptions`: [Geckodriver](https://firefox-source-docs.mozilla.org/testing/geckodriver/Capabilities.html) extensions, only applicable for testing in Firefox
* `ms:edgeOptions`: [EdgeOptions](https://learn.microsoft.com/en-us/microsoft-edge/webdriver-chromium/capabilities-edge-options) for specifying the environment when using EdgeDriver for testing Chromium Edge

### Cloud Vendor Capability Extensions[​](#cloud-vendor-capability-extensions "Direct link to Cloud Vendor Capability Extensions")

* `sauce:options`: [Sauce Labs](https://docs.saucelabs.com/dev/test-configuration-options/#w3c-webdriver-browser-capabilities--optional)
* `bstack:options`: [BrowserStack](https://www.browserstack.com/docs/automate/selenium/organize-tests)
* `tb:options`: [TestingBot](https://testingbot.com/support/other/test-options)
* `LT:Options`: [LambdaTest](https://www.lambdatest.com/support/docs/webdriverio-with-selenium-running-webdriverio-automation-scripts-on-lambdatest-selenium-grid/)
* and many more...

### Automation Engine Capability Extensions[​](#automation-engine-capability-extensions "Direct link to Automation Engine Capability Extensions")

* `appium:xxx`: [Appium](https://appium.io/docs/en/latest/guides/caps/)
* `selenoid:xxx`: [Selenoid](https://github.com/aerokube/selenoid/blob/master/docs/special-capabilities.adoc)
* and many more...

### WebdriverIO Capabilities to manage browser driver options[​](#webdriverio-capabilities-to-manage-browser-driver-options "Direct link to WebdriverIO Capabilities to manage browser driver options")

WebdriverIO manages installing and running browser driver for you. WebdriverIO uses a custom capability that allows you to pass in parameters to the driver.

#### `wdio:chromedriverOptions`[​](#wdiochromedriveroptions "Direct link to wdiochromedriveroptions")

Specific options passed into Chromedriver when starting it.

#### `wdio:geckodriverOptions`[​](#wdiogeckodriveroptions "Direct link to wdiogeckodriveroptions")

Specific options passed into Geckodriver when starting it.

#### `wdio:edgedriverOptions`[​](#wdioedgedriveroptions "Direct link to wdioedgedriveroptions")

Specific options passed into Edgedriver when starting it.

#### `wdio:safaridriverOptions`[​](#wdiosafaridriveroptions "Direct link to wdiosafaridriveroptions")

Specific options passed into Safari when starting it.

#### `wdio:maxInstances`[​](#wdiomaxinstances "Direct link to wdiomaxinstances")

Maximum number of total parallel running workers for the specific browser/capability. Takes precedence over [maxInstances](#configuration#maxInstances) and [maxInstancesPerCapability](/docs/configuration.md#maxinstancespercapability).

Type: `number`

#### `wdio:specs`[​](#wdiospecs "Direct link to wdiospecs")

Define specs for test execution for that browser/capability. Same as the [regular `specs` configuration option](/docs/configuration.md#specs), but specific to the browser/capability. Takes precedence over `specs`.

Type: `(String | String[])[]`

#### `wdio:exclude`[​](#wdioexclude "Direct link to wdioexclude")

Exclude specs from test execution for that browser/capability. Same as the [regular `exclude` configuration option](/docs/configuration.md#exclude), but specific to the browser/capability. Excludes after the global `exclude` configuration option is applied.

Type: `String[]`

#### `wdio:enforceWebDriverClassic`[​](#wdioenforcewebdriverclassic "Direct link to wdioenforcewebdriverclassic")

By default, WebdriverIO attempts to establish a WebDriver Bidi session. If you don't prefer that, you can set this flag to disable this behavior.

Type: `boolean`

#### Common Driver Options[​](#common-driver-options "Direct link to Common Driver Options")

While all driver offer different parameters for configuration, there are some common ones that WebdriverIO understand and uses for setting up your driver or browser:

##### `cacheDir`[​](#cachedir "Direct link to cachedir")

The path to the root of the cache directory. This directory is used to store all drivers that are downloaded when attempting to start a session.

Type: `string`<br />Default: `process.env.WEBDRIVER_CACHE_DIR || os.tmpdir()`

##### `binary`[​](#binary "Direct link to binary")

Path to a custom driver binary. If set WebdriverIO won't attempt to download a driver but will use the one provided by this path. Make sure the driver is compatible with the browser you are using.

You can provide this path via `CHROMEDRIVER_PATH`, `GECKODRIVER_PATH` or `EDGEDRIVER_PATH` environment variables.

Type: `string`

caution

If the driver `binary` is set, WebdriverIO won't attempt to download a driver but will use the one provided by this path. Make sure the driver is compatible with the browser you are using.

#### Custom Driver Download Host[​](#custom-driver-download-host "Direct link to Custom Driver Download Host")

If the public driver CDNs are not reachable from your environment, e.g. because you run your tests behind a corporate proxy or mirror the drivers in an internal artifact registry, you can point the download to a custom host using the following environment variables:

* Chrome: `CHROMEDRIVER_CDNURL`, defaults to `https://storage.googleapis.com/chrome-for-testing-public`
* Microsoft Edge: `EDGEDRIVER_CDNURL`, defaults to `https://msedgedriver.microsoft.com`

The mirror is expected to serve the driver archives under the same paths as the original CDN, e.g. for Chrome:

```
CHROMEDRIVER_CDNURL=https://artifactory.company.com/chrome-for-testing npx wdio run wdio.conf.js
```

which resolves the driver to `https://artifactory.company.com/chrome-for-testing/<buildId>/<platform>/chromedriver-<platform>.zip`, where `<platform>` is one of `linux64`, `mac-x64`, `mac-arm64`, `win32` or `win64`, e.g. `.../140.0.7339.207/mac-arm64/chromedriver-mac-arm64.zip`.

Fully offline environments

These variables redirect the driver download only. To keep WebdriverIO from reaching the public internet at all, three more conditions have to be met:

* **A browser has to be available locally.** If WebdriverIO can't find an installed Chrome or Firefox it downloads the browser too, and that download does not honor these variables. Either install the browser on the machine or point WebdriverIO at it via `goog:chromeOptions.binary` / `moz:firefoxOptions.binary`.
* **Use a full version number.** If `browserVersion` is omitted, WebdriverIO reads the exact version from the local browser and no version lookup is needed. If you do set it, use the complete four part version, e.g. `140.0.7339.207`. A release channel (`stable`), a milestone (`140`) or a partial version (`140.0.7339`) requires a version lookup against a public Google endpoint that can't be redirected.
* **Make sure the mirror actually has the version you need.** If the driver can't be fetched from your host — because the version isn't mirrored, but equally because the url is wrong or the credentials were rejected — WebdriverIO logs a warning and then looks up the closest known good version, which again queries the public endpoint. Check the warning for the host it tried if a run unexpectedly reaches the internet or picks a version you didn't ask for.

#### Browser Specific Driver Options[​](#browser-specific-driver-options "Direct link to Browser Specific Driver Options")

In order to propagate options to the driver you can use the following custom capabilities:

* Chrome or Chromium: `wdio:chromedriverOptions`
* Firefox: `wdio:geckodriverOptions`
* Microsoft Egde: `wdio:edgedriverOptions`
* Safari: `wdio:safaridriverOptions`

- wdio:chromedriverOptions
- wdio:geckodriverOptions
- wdio:edgedriverOptions
- wdio:safaridriverOptions

##### adbPort[​](#adbport "Direct link to adbPort")

The port on which the ADB driver should run.

Example: `9515`

Type: `number`

##### urlBase[​](#urlbase "Direct link to urlBase")

Base URL path prefix for commands, e.g. `wd/url`.

Example: `/`

Type: `string`

##### logPath[​](#logpath "Direct link to logPath")

Write server log to file instead of stderr, increases log level to `INFO`

Type: `string`

##### logLevel[​](#loglevel "Direct link to logLevel")

Set log level. Possible options `ALL`, `DEBUG`, `INFO`, `WARNING`, `SEVERE`, `OFF`.

Type: `string`

##### verbose[​](#verbose "Direct link to verbose")

Log verbosely (equivalent to `--log-level=ALL`)

Type: `boolean`

##### silent[​](#silent "Direct link to silent")

Log nothing (equivalent to `--log-level=OFF`)

Type: `boolean`

##### appendLog[​](#appendlog "Direct link to appendLog")

Append log file instead of rewriting.

Type: `boolean`

##### replayable[​](#replayable "Direct link to replayable")

Log verbosely and don't truncate long strings so that the log can be replayed (experimental).

Type: `boolean`

##### readableTimestamp[​](#readabletimestamp "Direct link to readableTimestamp")

Add readable timestamps to log.

Type: `boolean`

##### enableChromeLogs[​](#enablechromelogs "Direct link to enableChromeLogs")

Show logs from the browser (overrides other logging options).

Type: `boolean`

##### bidiMapperPath[​](#bidimapperpath "Direct link to bidiMapperPath")

Custom bidi mapper path.

Type: `string`

##### allowedIps[​](#allowedips "Direct link to allowedIps")

Comma-separated allowlist of remote IP addresses which are allowed to connect to EdgeDriver.

Type: `string[]`<br />Default: `['']`

##### allowedOrigins[​](#allowedorigins "Direct link to allowedOrigins")

Comma-separated allowlist of request origins which are allowed to connect to EdgeDriver. Using `*` to allow any host origin is dangerous!

Type: `string[]`<br />Default: `['*']`

##### spawnOpts[​](#spawnopts "Direct link to spawnOpts")

Options to be passed into the driver process.

Type: `SpawnOptionsWithoutStdio | SpawnOptionsWithStdioTuple<StdioOption, StdioOption, StdioOption>`<br />Default: `undefined`

See all Geckodriver options in the official [driver package](https://github.com/webdriverio-community/node-geckodriver#options).

See all Edgedriver options in the official [driver package](https://github.com/webdriverio-community/node-edgedriver#options).

See all Safaridriver options in the official [driver package](https://github.com/webdriverio-community/node-safaridriver#options).

## Special Capabilities for Specific Use Cases[​](#special-capabilities-for-specific-use-cases "Direct link to Special Capabilities for Specific Use Cases")

This is a list of examples showing which capabilities need to be applied to achieve a certain use case.

### Run Browser Headless[​](#run-browser-headless "Direct link to Run Browser Headless")

Running a headless browser means to run a browser instance without window or UI. This is mostly used within CI/CD environments where no display is used. To run a browser in headless mode, apply the following capabilities:

* Chrome
* Firefox
* Microsoft Edge
* Safari

```
{
    browserName: 'chrome',   // or 'chromium'
    'goog:chromeOptions': {
        args: ['headless', 'disable-gpu']
    }
}
```

```
    browserName: 'firefox',
    'moz:firefoxOptions': {
        args: ['-headless']
    }
```

```
    browserName: 'msedge',
    'ms:edgeOptions': {
        args: ['--headless']
    }
```

It seems that Safari [doesn't support](https://discussions.apple.com/thread/251837694) running in headless mode.

### Automate Different Browser Channels[​](#automate-different-browser-channels "Direct link to Automate Different Browser Channels")

If you like to test a browser version that is not yet released as stable, e.g. Chrome Canary, you can do so by setting capabilities and pointing to the browser you like to start, e.g.:

* Chrome
* Firefox
* Microsoft Edge
* Safari

When testing on Chrome, WebdriverIO will automatically download the desired browser version and driver for you based on the defined `browserVersion`, e.g.:

```
{
    browserName: 'chrome', // or 'chromium'
    browserVersion: '116' // or '116.0.5845.96', 'stable', 'dev', 'canary', 'beta' or 'latest' (same as 'canary')
}
```

If you like to test a manually downloaded browser, you can provide a binary path to the browser via:

```
{
    browserName: 'chrome',  // or 'chromium'
    'goog:chromeOptions': {
        binary: '/Applications/Google\ Chrome\ Canary.app/Contents/MacOS/Google\ Chrome\ Canary'
    }
}
```

Additionally, if you like to use a manually downloaded driver, you can provide a binary path to the driver via:

```
{
    browserName: 'chrome', // or 'chromium'
    'wdio:chromedriverOptions': {
        binary: '/path/to/chromdriver'
    }
}
```

When testing on Firefox, WebdriverIO will automatically download the desired browser version and driver for you based on the defined `browserVersion`, e.g.:

```
{
    browserName: 'firefox',
    browserVersion: '119.0a1' // or 'latest'
}
```

If you like to test a manually downloaded version you can provide a binary path to the browser via:

```
{
    browserName: 'firefox',
    'moz:firefoxOptions': {
        binary: '/Applications/Firefox\ Nightly.app/Contents/MacOS/firefox'
    }
}
```

Additionally, if you like to use a manually downloaded driver, you can provide a binary path to the driver via:

```
{
    browserName: 'firefox',
    'wdio:geckodriverOptions': {
        binary: '/path/to/geckodriver'
    }
}
```

When testing on Microsoft Edge, make sure you have the desired browser version installed on your machine. You can point WebdriverIO to the browser to execute via:

```
{
    browserName: 'msedge',
    'ms:edgeOptions': {
        binary: '/Applications/Microsoft\ Edge\ Canary.app/Contents/MacOS/Microsoft\ Edge\ Canary'
    }
}
```

WebdriverIO will automatically download the desired driver version for you based on the defined `browserVersion`, e.g.:

```
{
    browserName: 'msedge',
    browserVersion: '109' // or '109.0.1467.0', 'stable', 'dev', 'canary', 'beta'
}
```

Additionally, if you like to use a manually downloaded driver, you can provide a binary path to the driver via:

```
{
    browserName: 'msedge',
    'wdio:edgedriverOptions': {
        binary: '/path/to/msedgedriver'
    }
}
```

When testing on Safari, make sure you have the [Safari Technology Preview](https://developer.apple.com/safari/technology-preview/) installed on your machine. You can point WebdriverIO to that version via:

```
{
    browserName: 'safari technology preview'
}
```

## Extend Custom Capabilities[​](#extend-custom-capabilities "Direct link to Extend Custom Capabilities")

If you like to define your own set of capabilities in order to e.g. store arbitrary data to be used within the tests for that specific capability, you can do so by e.g. setting:

```
export const config = {
    // ...
    capabilities: [{
        browserName: 'chrome',
        'custom:caps': {
            // custom configurations
        }
    }]
}
```

It is advised to follow the [W3C protocol](https://w3c.github.io/webdriver/#dfn-extension-capability) when it comes to capability naming which requires a `:` (colon) character, denoting an implementation specific namespace. Within your tests you can access your custom capability through, e.g.:

```
browser.capabilities['custom:caps']
```

In order to ensure type safety you can extend WebdriverIOs capability interface via:

```
declare global {
    namespace WebdriverIO {
        interface Capabilities {
            'custom:caps': {
                // ...
            }
        }
    }
}
```