WebDrivercapabilities are used to communicate the features supported by asession. A client may also use capabilities to define which features it requires the driver to satisfy whencreating a new session.

When a WebDriver session is created it returns a set of capabilities describing the negotiated, effective capabilities of the session. Some of the capabilities included in this set arestandard and shared between all browsers, but the set may also containbrowser-specific capabilities and these are always prefixed.

Capabilities negotiation

Capabilities can be used to require a driver that supports a certain subset of features. This can be used to require certain browser features, such as theability to resize the window dimensions, but is also used in distributed environments to select a particular browser configuration from a matrix of choices.

Selecting a particular web browser or platform only makes sense when you use a remote WebDriver. In this case the client makes contact with WebDriver through one or more intermediary nodes which negotiates which driver to return to you based on the capabilities it receives.

The capabilities object is a selection mechanism that limits which driver configurations the server will return. If you request a Firefox instance usingbrowserName and Firefox is not installed on the remote, or macOS from a remote that only supports Linux, you may be out of luck. But occasionally you may not care which specific operating system or web browser your session has: you just want a session that has somecapability.

The selection process, or thecapabilities negotiation, is done throughalwaysMatch andfirstMatch.

alwaysMatch

As the name suggests, capabilities described inside thealwaysMatch capabilities object are features yourequire the session to have. If the server can not provide what features you require, it will fail.

If for example you ask for Firefox version 62 on a system that only has 60 installed, the session creation will fail:

{  "capabilities": {    "alwaysMatch": {      "browserName": "firefox",      "browserVersion": "60"    }  }}

firstMatch

ThefirstMatch field acceptsan array of capabilities objects which will be matched in turn until one matches what the server can provide, or it will fail.

This can be useful when you want a driver that runs on macOS or Linux, but not Windows:

{  "capabilities": {    "firstMatch": [{ "platformName": "macos" }, { "platformName": "linux" }]  }}

CombiningalwaysMatch andfirstMatch

firstMatch can of course be combined withalwaysMatch to narrow down the selection. If for example you a driver that runs on macOS or Linux but ithas to be Firefox:

{  "capabilities": {    "alwaysMatch": {      "browserName": "firefox"    },    "firstMatch": [{ "platformName": "macos" }, { "platformName": "linux" }]  }}

The previous example is exactly equivalent to putting the Firefox requirement in eachfirstMatch arm:

{  "capabilities": {    "firstMatch": [      { "browserName": "firefox", "platformName": "macos" },      { "browserName": "firefox", "platformName": "linux" }    ]  }}

Which you choose of the two preceding examples is not important, but it can matter when pass along browser configuration. To avoid unnecessarily repeating data, such as profiles, it is advisable to make use ofalwaysMatch so that this data is only transmitted across the wire once:

{  "capabilities": {    "alwaysMatch": {      "browserName": "firefox",      "moz:firefoxOptions": {        "profile": "<base64 encoded profile>",        "args": ["-headless"],        "prefs": { "dom.ipc.processCount": 8 },        "log": { "level": "trace" }      }    },    "firstMatch": [{ "platformName": "macos" }, { "platformName": "linux" }]  }}

List of capabilities

• browserName
• browserVersion
• platformName
• acceptInsecureCerts: This capability communicates whether expired or invalidTLS certificates are checked whennavigating. If the capability is false, aninsecure certificate error will be returned as navigation encounters domains with certificate problems. Otherwise, self-signed or otherwise invalid certificates will be implicitly trusted by the browser on navigation. The capability has effect for the lifetime of the session.
• pageLoadStrategy
• proxy
• setWindowRect
• timeouts
• unhandledPromptBehavior
• webSocketUrl

Vendor-specific capabilities

In addition to thestandard capabilities WebDriver allows third-parties toextend the set of capabilities to match their needs. Browser vendors and suppliers of drivers typically use extension capabilities to provide configuration to the browser, but they can also be used by intermediaries for arbitrary blobs of information.

• Firefox capabilities (moz:firefoxOptions)
• Chrome capabilities (goog:chromeOptions)

Legacy capabilities

The majority of Selenium clients usedesiredCapabilities andrequiredCapabilities to configure the new session. These are very similar tofirstMatch andalwaysMatch described above. Some drivers support these legacy capabilities, but they are deprecated and should be avoided.

Converting a legacy capabilities object into the new style is easy. The first thing you need to know is thatalwaysMatch/firstMatch isalways wrapped inside acapabilities JSON Object, whereasdesiredCapabilities/requiredCapabilities exists at the top level. Generally speaking, anything that has previously gone indesiredCapabilities should go in afirstMatch branch arm to achieve the same effect.

Take this deprecated capabilities object:

{ "desiredCapabilities": { "browserName": "firefox" } }

This would be functionally equivalent in the new style:

{ "capabilities": { "firstMatch": [{ "browserName": "firefox" }] } }

But because there is only onefirstMatch arm, and we know that session creation will fail if the server doesn't have a Firefox installed, it is also equivalent to this:

{ "capabilities": { "alwaysMatch": { "browserName": "firefox" } } }

See also

• New Session command
• Delete Session command