Desired Capabilities

Last modified on October 13, 2021

Desired capabilities are a set of keys and values sent to the Appium server to tell the server what kind of automation session should be started. There are various capabilities to modify the behavior of the server during the automation. For example, the platformName capability can be set to iOS to tell Appium an iOS session is needed, rather than an Android one. Or, the safariAllowPopups capability can be set to true to ensure that, during a Safari automation session, JavaScript is allowed to open up new windows.

An Appium test is very similar to a Selenium test: both use the same WebDriver, and DesiredCapabilities is used the same way.

Some desired capabilities can be used as environment variables. For example, the API key can be fetched from your local environment and doesn’t need to be replicated in the test script:

String bitbar_apiKey = env.get("BITBAR_APIKEY");

BitBar desired capabilities

Optional. In order to take advantage of BitBar infrastructure, devices, and testing capabilities, additional desired capabilities have been introduced. When running your Appium tests from the client side, some of these desired capabilities are mandatory while others are optional.


Optional. The email registered at BitBar. You can use bitbar_apiKey instead. For example,


The password for your BitBar account. You can use bitbar_apiKey instead.


Optional. The target test type. Use one of the following values: android and ios for native apps, selendroid when testing a hybrid app, and chrome and safari for web testing using the respective web browsers. selendroid is also needed for older Android devices with API strictly lower than 17. If bitbar_target is not set, the value of the platformName Appium capability is used.

Possible values: android, ios, selendroid, chrome, safari, xcuitest.


Optional. The project name that will be displayed on the Web UI. If none is provided, the Cloud sets a Project X name to your run. For example, Appium iOS Project.


Optional. Project description. For example, My first Appium project at BitBar Testing Cloud.


Optional. The name given to each Test Run under a Project. If no run name was given, the Cloud gives a Test run name to the run. For example, Test Run 1.


Required. The device name that uniquely identifies a device on BitBar. Alternatively, you can use a script to query for devices with particular properties (for example, with a python example). For example, iPhone 5c 7.0.4 A1532.


Required when not using the browserName capability for browser automation. Specifies the Application file (.app/.apk) to be installed on the device. The App can be given as a public URL or as the file ID of the file in BitBar. Upload an application either through the UI or using the command line (handling files over CLI). For example:


  • 126948355

  • latest

    Note: This option will use the latest apk/ipa used during the previous test run in the selected project.


Optional. The device language, identified by the java.util.locale Locale ID. Default value: EN. For example, fi_FI.


Optional. The time BitBar Cloud will wait to anticipate a JUnit XML upload after receiving driver.quit(). For example, 120. Default value: 0. Legal range: 0 - 300.


Optional. The timeout for the whole test execution (in seconds). It’s configurable only if you have an active plan or subscription. For example, 1200. Default value: 600. Java: capabilities.SetCapability(“bitbar_testTimeout”, 1200);.


Required. You can use the API key for authentication instead of the user name and password. This is available in the My Accounts view. For example, e4f86ac5b94e39810f33ad4ab71850a6.


Optional. Applies only to Private Cloud and Enterprise. You can add a new Appium run as a new device run to an existing test run by providing a test run ID. A new test run is created if there’s already a run for a similar device.


Optional. Defines the duration in seconds (max. 60) the broker should wait for a new Appium session after the last call to driver.quit(). This capability allows users to call driver.quit() inside of their tests and start a new Appium test using the same broker session and device. Default value: 0.


Optional. Applies to BitBar Public Cloud, BitBar Private Cloud, and BitBar Enterprise. This can be used to turn off the Appium client’s feature of finding a close match to the requested device. This allows the requested device name not to be a perfect match but the Appium client will search for a similar device. Default value: true.


Optional. Applies to BitBar Public Cloud, BitBar Private Cloud, and BitBar Enterprise. Allows the user to connect to an older version of the Appium server if this is required.

Currently, iOS supports only the latest Appium version. If you need to use older versions, please contact our support.

Default value: the latest available Appium version.


Optional. Applies to BitBar Public Cloud, BitBar Private Cloud, and BitBar Enterprise. Allows users to use a non-default testing framework. This is especially interesting for Private Cloud users that have different framework setups for different projects. Default value: the default framework ID. For example, 42.


Required for all iOS runs, optional for Android runs. The reason for the difference is in the difference of the .ipa installation mechanism to install in BitBar Testing compared to local case. Appium framework maps bundle ID automatically in the case of local run or installation. In the cloud case, we must notify the Appium framework about the correct bundle ID. For example, desired.bundleId = 'com.bitbar.testdroid.BitbarIOSSample';.

Appium desired capabilities

See the Appium desired capabilities documentation for the complete list of capabilities available for Appium.

See Also

Appium Support

Highlight search results