Desired Capabilities

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 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 in order to ensure that, during a Safari automation session, JavaScript is allowed to open up new windows.

An Appium test is very similar as a Selenium test: Both use the same WebDriver and DesiredCapabilities is used the same way.

Bitbar Desired Capabilities

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


  • Mandatory: no
  • Description: The email registered at Bitbar. Use bitbar_apiKey instead.
  • Example:


  • Mandatory: no
  • Description: The password for your Bitbar account. Use bitbar_apiKey instead.


  • Mandatory: no
  • Description: 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, value of Appium capability platformName is used.
  • Values: android | ios | selendroid | chrome | safari | xcuitest


  • Mandatory: no
  • Description: The project name that will be displayed on Web UI. If none is provided cloud sets a “Project X” name to your run.
  • Example: Appium iOS Project


  • Mandatory: no
  • Description: Project description.
  • Example: “My first Appium project at Bitbar Testing cloud”


  • Mandatory: no
  • Description: The name given to each Test Run under a Project. If no run name give, cloud gives a “Test run” name to run.
  • Example: Test Run 1


  • Mandatory: yes
  • Description: The device name that uniquely identifies a device on Bitbar. (Copy the name from Web UI, as shown in the snapshot). Alternatively you can use a script to query for devices with particular properties (eg. with a python example).
  • Example: iPhone 5c 7.0.4 A1532


  • Mandatory: yes - when not using “browserName” capability for browser automation
  • Description: 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 application either through UI or using the command line (handling files over CLI).
  • Example: “
  • Example: “126948355”
  • Example: “latest” - This option will use the latest apk/ipa used in previous test run in the selected project.


  • Mandatory: no
  • Description: Device language, identified by java.util.locale Locale ID
  • Default: EN
  • Example: fi_FI


  • Mandatory: no
  • Description: The time Cloud will wait anticipating a JUnit XML upload after receiving driver.quit()
  • Default: 0
  • Legal range: 0 - 300
  • Example: 120


  • Mandatory: no
  • Description: The timeout for whole test execution (in seconds). It’s configurable only, if you have active plan/subscription
  • Default: 600
  • Example: 1200
  • Java: capabilities.SetCapability(“bitbar_testTimeout”, 1200);


  • Mandatory: yes
  • Description: You can use API key to authentication instead of user name and password. This is available in “My Accounts” -view.
  • Default: none
  • Example: e4f86ac5b94e39810f33ad4ab71850a6


  • Scope: Private Cloud & Enterprise only
  • Mandatory: no
  • Description: You can add a new Appium run as a new device run to an existing testrun by providing a testrunid. Note! New test run is created, if there’s already a run for similar device.
  • Default: none
  • Example: 12345678


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.

  • Mandatory: no
  • Description: defines the duration in seconds (max. 60) the broker should wait for new Appium session after last call to driver quit.
  • Default: 0
  • Example: 42


  • Scope: Public, Private and Enterprise
  • Mandatory: no
  • Description: This can be used to turn off Appium client’s feature of finding a close match to request device. This allows the requested device name to not be a perfect match but Appium client will search for a similar device.
  • Default: true
  • Example: false


  • Scope: Public, Private and Enterprise
  • Mandatory: no
  • Description: Allows user to connect to older version of Appium server if this is required. NOTE! on iOS only latest version is supported currently. If you need to use older versions, please contact our support.
  • Default: latest available Appium
  • Example: “1.11.1”


  • Scope: Public, Private and Enterprise
  • Mandatory: no
  • Description: 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: uses default framework ID
  • Example: 42


  • Mandatory: yes (for all iOS runs), no (for any Android runs)
  • Description: The reason is the difference in mechanism to install ipa in Bitbar Testing compared to local case. Appium framework maps bundle ID automatically in case of local run/installation. In cloud case we must notify Appium framework about the correct bundle ID.
  • Example: desired.bundleId = 'com.bitbar.testdroid.BitbarIOSSample';

Some desired capabilities can be used as environment variables. For example the apikey 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");

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