Client Side Appium

Overview

With Bitbar Cloud it is possible to execute Appium tests similarly as when running the tests on your local machine. The difference is that Appium server and the tested device are in cloud.

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

Upload Your App To Cloud

Your app under test needs to be uploaded to Bitbar Cloud. This can be done either using curl on the command line or some automated CI solution. Read more on managing files.

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

Running this command returns a response JSON with the uploaded application’s 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.

../../../_images/client-side-file-id.png

Edit Desired Capabilities

Common values used in tests:

  • bitbar_apiKey - a personal unique key allowing you to connect to Bitbar Testing without using username and passwords in tests. Api key is found under “My account” in Bitbar Testing Cloud UI.
  • bitbar_project - the project name in Bitbar Testing. Each project must have a unique name, which can be modified (in Cloud)
  • bitbar_testrun - name of this test run inside of bitbar_project. Each test run can have it’s own name (eg. date + time)
  • bitbar_app - id of the uploaded file. To rerun against the last uploaded application the value “latest” can be used.

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

Selecting a 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 capability bitbar_findDevice. This capability allows the user to get a similar device to the one requested or the exact requested. Device similarity is defined by device name similarity matching. This means running the same test twice with bitbar_findDevice='true', the device selected by 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 device does not become available during this time.

Updating Existing Tests For Cloud

Updating Capabilities

Online samples on Github, accessible here, help getting started on 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. Mainly authentication information and selecting the appropriate device need to be provided. The app name is the name from the above curl upload. Below example shows the additional capabilities that need to be added.

Before

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

After changes

'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 localhost (http://localhost:4723/wd/hub). When running the test from your local machine against a cloud device, you must update the Appium server location to https://appium.bitbar.com/wd/hub.

Upload Results to Cloud (Optional)

If your test suite generates a JUnit XML results file, you can upload the XML to Bitbar Cloud. Doing this will allow you to check your test cases and their run statuses on the web UI, and let you download test reports in various formats.

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

  2. Get 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 printed to command line

  3. After your test run has finished, and JUnit XML has been generated, use Curl to upload the XML to Cloud:

    curl -s -F result=@"/absolute/file/path/TEST-all.xml"  http://appium.bitbar.com//upload/result?sessionId=<SESSION_ID>