Running Client-Side Appium tests

Last modified on November 24, 2021


With BitBar Cloud, you can execute Appium tests similarly to the way you run the tests on your local machine. The difference is that the Appium server and the tested device are in the cloud.

The below steps show you how to get your existing Appium tests running against devices hosted in the cloud.

Upload your app to cloud

Your app under test needs to be uploaded to BitBar Cloud. This can be done either via cURL or with some automated CI solution. To learn more, see Managing Files.

curl -X POST -u "${BITBAR_API_KEY}:" -F 'file=@./BitbarSampleApp.apk' "${BITBAR_CLOUD_URL}/api/v2/me/files" | jq '.id'

Running this command returns a response JSON with the uploaded application ID. You will need this ID as your bitbar_app desired capability.

  "id": 126822909,
  "selfURI": null,
  "createTime": 1547718182000,
  "fileProperties": [...]

If you have already uploaded your application to the cloud using the file manager, you can get the application’s ID from there.

Client side file ID

Click the image to enlarge it.

Edit desired capabilities

Common values used in tests:

  • bitbar_apiKey – A personal unique key allowing you to connect to BitBar Testing without using the username and passwords in tests. The API key can be found under My account in the BitBar Testing Cloud UI.

  • bitbar_project  – The project name in BitBar Testing. Each project must have a unique name, which can be modified (in the cloud).

  • bitbar_testrun – The name of this test run inside of bitbar_project. Each test run can have its own name, for example, the date and time.

  • bitbar_app  – The ID of the uploaded file. To rerun a test against the last uploaded application, the “latest” value can be used.

In addition to the above capabilities, default Appium capabilities are supported. It is worth checking the list of supported Desired Capabilities.

Select device

With client-side Appium runs, BitBar Cloud gives preference on providing some available device over an exact match. This preference can be changed with the desired bitbar_findDevice capability. This capability allows the user to get a device similar to the one requested or exactly the requested one. Device similarity is defined by device name similarity matching. This means running the same test twice with bitbar_findDevice='true', the device selected by the cloud can be different.

To enforce selecting a specific device, one should check for the exact name from BitBar Cloud and set the bitbar_findDevice capability to false. If the selected device is currently busy, a new session is tried for a few minutes. The connection is closed if the device does not become available during this time.

Update existing tests for cloud

Update capabilities

Online samples on Github, accessible here, help getting started with running Appium tests. The samples are available in Python, Java, C#, and Ruby.

For running your existing Appium runs against BitBar Cloud, your existing desired capabilities need to be updated. You need to provide authentication information and select the appropriate device. The app name is the name as in the cURL above. The below example shows the additional capabilities that need to be added.

Before the changes are made:

'app' : 'com.bitbar.testdroid.BitbarIOSSample',
'device' : 'iphone'

After the changes are made:

'app' : 'com.bitbar.testdroid.BitbarIOSSample',
'device' : 'iphone',
'bitbar_apiKey' : '<your apiKey>',
'bitbar_project' : 'Appium iOS Project',
'bitbar_testrun' : 'Test run 1',
'bitbar_device' : 'iPhone 5c',
'bitbar_app' : '23425235',
'bitbar_locale' : 'fi_FI' # optional

Change WebDriver address

When running Appium locally, the web driver address is running on a localhost (http://localhost:4723/wd/hub). When running the test from your local machine against a cloud device, you need to update the Appium server location to

Upload results to cloud

Note: This step is optional.

If your test suite generates a JUnit XML result file, you can upload the XML file to BitBar Cloud. This will allow you to check your test cases and their run statuses on the web UI and let you download test reports.

  1. Add the bitbar_junitWaitTime Desired Capability in your TestScript with an appropriate value in seconds. For example, 60 seconds should be sufficient.

  2. Get the Appium session ID from your test script (after the WebDriver connection has been established) by printing the property:

    self.utils.log("Driver session id: "+ self.driver.session_id)

    Session ID
  3. After your test run has finished, and JUnit XML has been generated, use cURL to upload the XML to the cloud:

    curl -s -F "result=@/absolute/file/path/TEST-all.xml"<SESSION_ID>

See Also

Appium Support

Highlight search results