Session Capabilities

Capabilities are the core parameters used to start an Appium session. They describe various features that you want your session to have, for example, a certain mobile operating system or a certain version of a device. Capabilities are represented as key-value pairs, with values allowed to be any valid JSON type, including other objects. Most importantly, they cannot be changed during the lifecycle of the session.

The capabilities used in Appium follow the W3C WebDriver specification of the same name. The WebDriver spec defines a small set of standard capabilities, including the following:

Capability Name	Type	Description
`browserName`	`string`	The name of the browser to launch and automate
`browserVersion`	`string`	The specific version of the browser
`platformName`	`string`	The type of platform hosting the browser

While the above capabilities are commonly used by Appium drivers, they are not sufficient for describing Appium-specific features, such as the name of the driver to use, or the name of the app to launch. In order to achieve this, Appium defines its own extension capabilities.

Common Appium Capabilities¶

According to the WebDriver spec, extension capabilities must include a namespace prefix (signifying the vendor introducing the capability), and the namespace must end a colon (:). Appium's vendor prefix is appium:, and so any Appium-specific capabilities must include this prefix. Depending on your Appium client, the prefix may be added automatically or in conjunction with certain interfaces, but it is always a good practice to explicitly include it for clarity.

Here are a few commonly (but not universally!) used Appium-specific capabilities:

Capability Name	Type	Description
`appium:automationName`	`string`	The name of the Appium driver to use
`appium:udid`	`string`	The unique device identifier of a particular device to automate
`appium:app`	`string`	The path to an installable application

All capabilities recognized by the Appium base driver (inherited by all drivers) can be found in the Capabilities Reference document. While this common capability set is fairly small, it can be greatly extended by Appium drivers and plugins, who can (and should) define their own capabilities. Make sure to reference their documentation to learn more about the capabilities they support. You can find a list of known drivers in the Ecosystem Drivers document.

Drivers are also able to place more complex constraints on capabilities as a group. For example, the XCUITest driver recommends that at least one of browserName, appium:app, or appium:bundleId is included in the capabilities, otherwise it will not be able to auto-install or auto-launch any application. Each driver will document how it interprets these capabilities and any other platform-specific requirements.

The way to construct capabilities and start a session will likely differ depending on your Appium client. For examples of doing this in each client library, head to the Ecosystem Clients page and click through to the appropriate client documentation.

Note

Once your capabilities are sent to the server and the session is started, they cannot be changed. If a driver supports updating its behaviour during a session, it will use the Settings API for this purpose.

BiDi Protocol Support¶

In addition to the standard WebDriver protocol (now known as WebDriver Classic), Appium supports the WebDriver BiDi protocol. Support for this protocol is opt-in, and requires the use of the standard webSocketUrl capability.

Capability Name	Type	Description
`webSocketUrl`	`boolean`	Whether BiDi protocol is enabled in the session

All BiDi commands supported by the Appium base driver (inherited by all drivers) can be found in the BiDi Protocol API Reference document. Similarly to WebDriver Classic commands, individual Appium drivers and plugins can define their own supported standard and custom BiDi commands, so make sure to reference their documentation.

Using `appium:options` to Group Capabilities¶

If you use a lot of appium: capabilities in your tests, it can get a little repetitive. You can combine all capabilities as an object value of a single appium:options capability instead, in which case you don't need to use prefixes on the capabilities inside the object. For example:

{
    "platformName": "iOS",
    "appium:options": {
        "automationName": "XCUITest",
        "platformVersion": "16.0",
        "app": "/path/to/your.app",
        "deviceName": "iPhone 12",
        "noReset": true
    }
}

Note that constructing a capability value which is itself an object differs by language; refer to your client documentation for further examples on how to achieve this.

Warning

If you include the same capabilities both inside and outside of appium:options, the values inside of appium:options take precedence.

Always-Match and First-Match Capabilities¶

The W3C spec allows clients to give the Appium server some flexibility in the kind of session it creates in response to a new session request. This is through the concept of "always-match" and "first-match" capabilities:

Always-match capabilities consist of a single set of capabilities, every member of which must be satisfied by the server in order for the new session request to proceed.
First-match capabilities consist of an array of capability sets. Each set is merged with the always-match capabilities, and the first set that the server knows how to handle will be the set that is used to start the session.

Note

Check out the spec itself for a more in-depth description of how capabilities are processed.

In practice, use of first-match capabilities is not necessary or recommended for use with Appium. Instead, we recommend that you define the explicit set of capabilities you want the Appium server to handle. These will be encoded as the always-match capabilities, and the array of first-match capabilities will be empty.

That being said, Appium does understand always-match and first-match capabilities as defined in the W3C spec, so if you use these features, Appium will work as expected. The process of defining always-match and first-match capabilities is unique to each client library, so refer to the documentation for your client library to see examples of how it works.

Special Notes for Cloud Providers¶

Warning

This section is not intended for end-users of Appium; it is intended for developers building Appium-compatible cloud services.

When managing an Appium cloud, your users may wish to target various independent versions of Appium drivers and plugins. It is of course up to each service provider how they wish to implement the discovery, installation, and availability of any official or third party drivers or plugins. But the Appium team does provide several suggestions, for consistency across the industry. These are recommendations only, and not a standard, but adopting it will help users to navigate the increased complexity that working with Appium in a cloud environment may bring.

Suggested capabilities¶

In addition to the standard platformName, appium:deviceName, appium:automationName, and appium:platformVersion, we recommend adopting the capability $cloud:appiumOptions, where the label $cloud is not meant to be interpreted literally but instead should be replaced by your vendor prefix (so for HeadSpin it would be headspin, Sauce Labs it would be sauce, and BrowserStack it would be browserstack, to name just a few examples). The $cloud:appiumOptions capability would itself be a JSON object, with the following internal keys:

Capability	Usage	Example
`version`	The version of the Appium server that is used to host and manage drivers. If omitted, the behavior is left up to the provider, but the recommendation would be to provide the latest official version.	`2.0.0`
`automationVersion`	The version of the driver (as specified by `appium:automationName`) that should be used.	`1.55.2`
`automation`	The name of a custom driver to use (see below for more info). This would override `appium:automationName` and `$cloud:automationVersion`.	`{"name": "@org/custom-driver", "source": "github", "package": "custom-driver"}`
`plugins`	The list of plugins (and potentially versions of plugins) that should be activated (see below for more info).	`["images", "universal-xml"]`

Basic example¶

Appium extensions (drivers and plugins) have a set of properties that specify where they can be installed from. Cloud providers are obviously under no obligation to provide support for arbitrarily specified extensions, seeing as these may represent untrusted code running in a managed environment. In the case where arbitrary extensions are not supported, the appium:automationName, $cloud:automationVersion, and $cloud:appiumPlugins capabilities should be sufficient. See the following JSON object representing capabilities for a session:

{
  "platformName": "iOS",
  "appium:platformVersion": "14.4",
  "appium:deviceName": "iPhone 11",
  "appium:app": "Some-App.app.zip",
  "appium:automationName": "XCUITest",
  "$cloud:appiumOptions": {
    "version": "2.0.0",
    "automationVersion": "3.52.0",
    "plugins": ["images"]
  }
}

This set of capabilities requests an Appium 2+ server supporting the XCUITest driver at version 3.52.0, and the images plugin active. This set is easy for a cloud provider to verify. The cloud provider can obviously do anything it wants in response to these capabilities, including downloading Appium and driver and plugin packages on the fly, or erroring out if the versions requested are not in a supported set, or if the plugin is not supported, etc...

Basic example with `appium:options`¶

The previous example still looks a bit disorganized, so of course we also recommend that cloud providers support the appium:options capability as detailed above, which could turn the previous set of capabilities into the following:

{
  "platformName": "iOS",
  "appium:options": {
    "platformVersion": "14.4",
    "deviceName": "iPhone 11",
    "app": "Some-App.app.zip",
    "automationName": "XCUITest"
  },
  "$cloud:appiumOptions": {
    "version": "2.0.0",
    "automationVersion": "3.52.0",
    "plugins": ["images"]
  }
}

Extension objects¶

Some service providers may wish to dynamically allow access to all of the features of the Appium 2 CLI, including downloading arbitrary drivers and plugins. To represent these extensions, we can define special JSON "extension objects", with the following keys:

name: the name of the extension. This would be an npm package name (if downloading from npm), or a git or GitHub spec (if downloading from a git server or GitHub).
version: the version of the extension, e.g., the npm package version or git SHA.
(optional) source: a denotation of where the extension can be downloaded from. It is recommended to support the following values: appium, npm, git, github. Here, appium means "Appium's own official list", and should be the default value if this key is not included.
(optional) package: when downloading extensions from git or GitHub, the npm package name of the extension must also be provided. This is optional for non-git sources.

Since each session is handled by a single driver, the $cloud:appiumOptions/$automation capability could be used with an extension object value to denote this driver, for example:

{
    "$cloud:appiumOptions": {
        "automation": {
            "name": "git+https://some-git-host.com/custom-driver-project.git",
            "version": "some-git-sha",
            "source": "git",
            "package": "driver-npm-package-name"
        }
    }
}

And since sessions can handle multiple plugins, each value in the list of $cloud:appiumPlugins could also be an extension object rather than a string, so that specific versions could be requested:

{
    "$cloud:appiumOptions": {
        "plugins": [{
            "name": "images",
            "version": "1.1.0"
        }, {
            "name": "my-github-org/my-custom-plugin",
            "version": "a83f2e",
            "source": "github",
            "package": "custom-plugin"
        }]
    }
}

These serve as illustrative examples for the recommendations here. Of course, it is up to the service providers to implement the handling of these capabilities at their front end / load balancer, to perform any error checking, or to actually run any of the appium driver or appium plugin CLI commands that support the end user's request. This section is merely a suggestion as to how service providers might design their user-facing capabilities API in a way which in principle supports all of the capabilities that Appium itself would provide to the end user if they were running Appium on their own.