HeadSpin Documentation

Getting Started with Appium

Getting Started with Appium

Appium is an open-source, cross-platform tool for automating mobile app testing. If your team has existing Appium tests, they can be integrated with HeadSpin and run on any HeadSpin device you have access to. Using Appium Desktop you can inspect the view hierarchy of an application, determine the selectors, and even generate scaffold Appium code.

Note: The API calls in this guide will be expressed as cURL commands for ease of readability cross-platform and independent of programming language.

Automation Configuration API

The HeadSpin Automation Configuration API provides you with the optimal minimum Desired Capabilities to use for a given device and the WebDriver URL. To recap, Desired Capabilities tell Appium how you want your test to work. They are represented as keys and associated values encoded in a JSON object and sent by the Appium client to the Appium server.

curl https://<your_api_token>@api-dev.headspin.io/v0/devices/automation-config

This is an example response:

    "ce0917194392a140017e@proxy-us-nyc-4.headspin.io": {
        "device_location": {
            "city": "nyc",
            "carrier": "AT&T",
            "country_readable": "US",
            "city_readable": "New York",
            "lat": 40.7127837,
            "country": "us",
            "lon": -74.0059413
        "lock_url": "https://us-nyc.headspin.io:7016/v0//lock",
        "working_dir": "/home/pbox/appium_tests/ce0917194392a140017e",
        "capabilities": {
            "deviceName": "ce0917194392a140017e",
            "autoAcceptAlerts": "true",
            "udid": "ce0917194392a140017e",
            "automationName": "UiAutomator2",
            "platformName": "Android",
        "host": "proxy-us-nyc-4.headspin.io",
        "unlock_url": "https://us-nyc.headspin.io:7016/v0//unlock",
        "driver_url": "https://us-nyc.headspin.io:7016/v0//wd/hub",
        "device_carrier": {
            "network_subtype": "LTE",
            "network_connected": true,
            "network_type": "MOBILE",
            "phone_network": "LTE",
            "carrier": "AT&T"
        "os": "android",
        "control_url": "https://us-nyc.headspin.io:10100"

The <code class="dcode">capabilities</code> object will have the values for your Desired Capabilities. The <code class="dcode">driver_url</code> will be the remote WebDriver you will use in your test.

Launching your application

In addition, the the minimum Desired Capabilies, the last remaining item to specify is the app you want to test.


For a given Android application you will need to specify the <code class="dcode">appPackage</code> and <code class="dcode">appActivity</code> you would like to launch. The appPackage is the Android app that you want to run and the <code class="dcode">appActivity</code> is the specific activity within the Android app package you would like to launch.

For example:

"appPackage": "com.google.android.apps.messaging",
  "appActivity": "com.google.android.apps.messaging.ui.conversationlist.ConversationListActivity"

If you have the project source of your app, you can acertain these values from taking a look at the AndroidManifest.xml in Android Studio.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"

    <uses-permission android:name="android.permission.INTERNET" />

                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />


The starting <code class="dcode">&lt;manifest></code> tag includes the <code class="dcode">appPackage</code> name and the <code class="dcode"><activity></code> tags show the activities of your app.

In the event where you don't have project source, you can determine this via <code class="dcode">adb.</code> If you install your app on your HeadSpin Device, launch it, and then use <code class="dcode">adb shell</code> either via the HeadSpin Remote ADB or REST API, you can run:

 dumpsys window windows | grep -E ‘mCurrentFocus’

This will return the information in the following format: <code class="dcode">(appPackage/appActivity)</code>


For iOS you will need to specify the bundleId of the application. If you have .xcodeproj or .xcworkspace source then you can determine this from the General section in the Project Information section in Xcode:

xcode bundle

In the event where you don't have project source, you can determine this from the iOS REST API to retrieve a list of installed apps on a given device. Please refer to the iOS Device API guide.

Examples in Appium Client Languages

The reference code snippets below provide a visual reference to how the desired capabilities and remote driver URL syntax appear in different Appium Client languages.


from appium import webdriver

caps = {}
caps["udid"] = "{device-id}"
caps["deviceName"] = "{device-id}"
caps["platformName"] = "Android"
caps["appPackage"] = "io.headspin.example"
caps["appActivity"] = "io.headspin.example.LauncherActivity"
caps["automationName"] = "UiAutomator2"
caps["noReset"] = True
caps["autoAcceptAlerts"] = True

driver = webdriver.Remote("https://proxy-us-sf-3.headspin.io:7003/v0//wd/hub", caps)


require 'rubygems'
require 'appium_lib'

caps = {}
caps["udid"] = "{device-id}"
caps["deviceName"] = "{device-id}"
caps["platformName"] = "Android"
caps["appPackage"] = "io.headspin.example"
caps["appActivity"] = "io.headspin.example.LauncherActivity"
caps["automationName"] = "UiAutomator2"
caps["noReset"] = true
caps["autoAcceptAlerts"] = true
opts = {
    server_url: "https://proxy-us-sf-3.headspin.io:7003/v0//wd/hub"
driver = Appium::Driver.new({caps: caps, appium_lib: opts}).start_driver


import io.appium.java_client.MobileElement;
import io.appium.java_client.android.AndroidDriver;
import junit.framework.TestCase;
import org.junit.After;
import org.junit.Before;
import java.net.URL;
import org.openqa.selenium.remote.DesiredCapabilities;

public class SampleTest {

  private AndroidDriver driver;

  public void setUp() throws MalformedURLException {
    DesiredCapabilities desiredCapabilities = new DesiredCapabilities();
    desiredCapabilities.setCapability("udid", "{device-id}");
    desiredCapabilities.setCapability("deviceName", "{device-id}");
    desiredCapabilities.setCapability("platformName", "Android");
    desiredCapabilities.setCapability("appPackage", "io.headspin.example");
    desiredCapabilities.setCapability("appActivity", "io.headspin.example.LauncherActivity");
    desiredCapabilities.setCapability("automationName", "UiAutomator2");
    desiredCapabilities.setCapability("noReset", true);
    desiredCapabilities.setCapability("autoAcceptAlerts", true);

    URL remoteUrl = new URL("https://proxy-us-sf-3.headspin.io:7003/v0//wd/hub");

    driver = new AndroidDriver(remoteUrl, desiredCapabilities);

  public void tearDown() {

HeadSpin Appium Capabilities

HeadSpin also provides a set of convenient Appium Capabilities for using certain platform features such as Performance Sessions or setting a specific Appium Server version for example. The full listing of capabilities can be found in the HeadSpin Appium Capabilities document.