Appium Capabilities

In addition to the standard Appium capabilities^1 (including each driver specific capabilities) and the W3C WebDriver spec^2, the Appium server running on each HeadSpin host supports a number of custom capabilities below. In addition, the HeadSpin Appium load balancer running in the cloud supports additional capabilities that control device selection and redundancy.

Unless otherwise stated, these capabilities work for any Android, iOS, or TV device in the pool.

Supported drivers

HeadSpin supports

Host capabilities

Note, that HeadSpin allows <code class="dcode">deviceName</code> to be blank in the capabilities and will automatically use the device <code class="dcode">udid</code> instead.

Appium session

HeadSpin session and capture

Apps

If <code class="dcode">appium:app</code> capability has http/https scheme, and the URL has <code class="dcode">.ipa</code> extension name, HeadSpin's provisioning profile will be applied by default to avoid possible installation failure. <code class="dcode">headspin:app.resign</code>, <code class="dcode">headspin:app.resignTimeout</code>, <code class="dcode">headspin:appId.resignIpa</code> and <code class="dcode">headspin:appId.resignIpaTimeout</code> capabilities can handle the resigning as same.

Please make sure the application under test has isInspectable enabled for <code class="dcode">WkWebView</code> or <code class="dcode">JSContext</code> components in apps built with the iOS/iPadOS 16.4+ SDK, to make WebView contexts available in Appium. Apple started requiring this attribute, which defaults to <code class="dcode">NO</code>/<code class="dcode">false</code>. Please read Enabling the Inspection of Web Content in Apps for more details.

TV devices

TV devices support limited capabilities as below. The description section explains the TV devices specific behavior. Empty description means the behavior is the same the above.

Setting <code class="dcode">options</code> for HeadSpin Appium options

<code class="dcode">headspin:options</code> used to combine all capabilities as an object value of a single <code class="dcode">headspin:options</code> capability, meaning you do not need to use prefixes for each capability inside the object. Values specified in this way take precedence over values specified outside of this capability.

Example:

{
    "headspin:options": {
        "restartOnError": "true",
        "app.id": "be06ca64-712a-4695-9430-2e6937144a3e",
        "app.resign": "true"
    }
}

HeadSpin commands

These HeadSpin commands are designed to be run by the Execute Mobile Command interface.

Example of <code class="dcode">headspin:installApp</code>

# Python
driver.execute_script('headspin:installApp', {'id': 'be06ca64-712a-4695-9430-2e6937144a3e', 'grantPermissions': False})

# Ruby
driver.execute_script 'headspin:installApp', {'id' => 'be06ca64-712a-4695-9430-2e6937144a3e', 'resign' => false}

<code class="dcode">app</code> standard Appium capability

HeadSpin drops the <code class="dcode">app</code> capability when <code class="dcode">*</code> is provided as the value.

The value <code class="dcode">*</code> is invalid for standard Appium, but some Appium client tools require the app capability even when it is not necessary. In these cases you can set * as the value to establish an Appium session using another capability.

<code class="dcode">appium:autoLaunch</code> and <code class="dcode">headspin:capture.autoStart</code>

Appium uses an <code class="dcode">appium:autoLaunch</code> capability to control if Appium launches the application under test. This is documented in the Appium documentation for desired capabilities. The application under test launches when the capability is <code class="dcode">true</code>.

When <code class="dcode">appium:autoLaunch</code> is <code class="dcode">false</code>, Appium does not launch the application under test automatically in creating a new session. Then, you are responsible for launching the application under test manually with one of the available ways to launch an application under test. HeadSpin session capture starts when Appium receives one of thes

If you have a scenario where you need to launch the application under test without the standard application launch commands, for example, when you test a Progressive Web Application (PWA) on iOS, then HeadSpin session capture does not start automatically as described above. Instead, you can combine the <code class="dcode">"appium:autoLaunch"</code>: false capability with the <code class="dcode">"headspin:capture.autoStart"</code>: <code class="dcode">true</code> capability to start HeadSpin capture anyway. Then you may launch the application under test in any available manner, for example, by tapping the PWA application icon on the home screen.

with <code class="dcode">appium:autoLaunch</code>

The following table describes the possible outcomes in the case where appium:autoLaunch is specified. Note that setting a value for <code class="dcode">headspin:capture.autoStart</code> is ignored in the case that <code class="dcode">appium:autoLaunch</code> is set to <code class="dcode">true</code> and a capture session will always start along with the application under test.

without <code class="dcode">appium:autoLaunch</code>

Appium is going to stop supporting the <code class="dcode">appium:autoLaunch</code> capability in accordance with this issue. When not specifying <code class="dcode">appium:autoLaunch</code>, detecting if a session starts the application under test as part of a new session request will depend on the whether or not other capabilities are set; if both an app is specified via <code class="dcode">appium:app</code>, <code class="dcode">headspin:appId</code>, or <code class="dcode">headspin:app.id</code> or a corresponding <code class="dcode">appium:appPackage</code> or <code class="dcode">appium:bundleId</code> is specified then appium will start the application under test in a new session request.

If the capabilities exclude <code class="dcode">appium:app</code>, <code class="dcode">headspin:appId</code>, <code class="dcode">headspin:app.id</code>, <code class="dcode">appium:appPackage</code>, and <code class="dcode">appium:bundleId</code> AND <code class="dcode">headspin:capture.autoStart</code> capability is false (default), the session will only start capture when it gets one of the available ways to launch an application under test. Otherwise the capture session will automatically start along with the launching of the application under test when a new session request starts.

Available ways to launch an application under test

The following are ways to manually launch an app. Launch App, Activate App, Reset App, and Start Activity. Future versions of Appium will favor the following existing ways to launch an app: <code class="dcode">mobile:activateApp</code>, documentation for iOS, documentation for Android, and <code class="dcode">mobile:launchApp</code> for iOS.

Browser logs (<code class="dcode">enableJSConsoleLog</code>)

HeadSpin collects JavaScript console logs when <code class="dcode">headspin:enableJSConsoleLog</code> is enabled in a capture session before ending the session. The log can be downloaded from the Waterfall UI or the Session API. They are in <code class="dcode">jsconsole.log</code>.

To get logs from Appium, you must specify the log type for Appium to collect the logs. For Android, use <code class="dcode">browser</code> log type, and for iOS use <code class="dcode">safariConsole</code> log type.

If you already acquired the log during a session, HeadSpin will only collect the log after the command runs.

Android (UiAutoamtor2 driver) requires that the context be WEBVIEW when the session ends since the <code class="dcode">browser</code> log type is available only via chromedriver over Appium.

Setting the Appium Version

New Appium versions are made available to customers as soon as they are certified on the platform. HeadSpin works with the Appium team to test and provide new versions ^3. A few select versions are available on every host by default. You can always confirm what versions are available in a host via the version API below. Please contact us if you need a specific version that is not in the result.

You should always set <code class="dcode">headspin:appiumVersion</code> to the version you are using, to avoid changes related to system updates in the future.

Appium 2.x support

HeadSpin supports Appium 2.x and drivers, which are available over Appium 2.x. The session needs to specify Appium 2.x with <code class="dcode">headspin:appiumVersion</code> right now, such as <code class="dcode">"headspin:appiumVersion": "2.0.0"</code>. The available Appium versions and driver versions are listed in the result of <a href="#check-available-appium-versions">Check available Appium versions</a> below. The <code class="dcode">default</code> keys/values in the <code class="dcode">drivers</code> are the default driver version for each <code class="dcode">appium:automationName</code> session.

<code class="dcode">headspin:appiumAutomationVersion</code> capability allows a session to start with the specific driver version with the given <code class="dcode">appium:automationName</code> if the host had the pair. With the automation version capability, you could run an arbitrary driver version for a session.

Check available Appium and driver versions

HeadSpin host provides the list of available Appium versions as API. It helps to confirm which Appium versions can run on the host machine. Please contact us if you want to use a particular Appium version which is not available on the host machine.

The minimum supported version is <code class="dcode">1.11.0</code>.

Example

curl -X GET https://proxy-jp-tyo-1.headspin.io:7001/v0/{your-api-token}/wd/hub/versions

Response

{
    "status": 0,
    "session_id": null,
    "value": {
        "default": "2.0.0",
        "available": ["1.22.3", "2.0.0", "2.2.1"],
        "drivers": {
            "default": {
                "uiautomator2": "2.34.0"
            },
            "available": {
                "uiautomator2": ["2.29.10", "2.34.0", "2.34.1"]
            }
        },
        "plugins": {
            "available": {
                "relaxed-caps": "1.0.5"
            },
            "default": {
                "relaxed-caps": "1.0.5"
            }
        }
    }
}

The <code class="dcode">available</code> is available Appium versions. You can specify them as <code class="dcode">headspin:appiumVersion</code>. The <code class="dcode">default</code> is chosen if a create session capabilities has no <code class="dcode">headspin:appiumVersion</code>.

The <code class="dcode">default</code> in the <code class="dcode">drivers</code> is the pairs of <code class="dcode">appium:automationName</code> and the available version on the host. The <code class="dcode">available</code> in the <code class="dcode">drivers</code> shows what driver versions are available on the host. <code class="dcode">appium:automationName</code> and <code class="dcode">headspin:appiumAutomationVersion</code> capabilities let a session specify the combination.

The <code class="dcode">default</code> in the <code class="dcode">plugins</code> is the pairs of <code class="dcode">headspin:appiumPlugins</code> and the available version on the host. The <code class="dcode">available</code> in the <code class="dcode">plugins</code> shows what plugin versions are available on the host. <code class="dcode">headspin:appiumPlugins</code> capability let a session activate the plugins.

The <code class="dcode">drivers</code> and <code class="dcode">plugins</code> will be used when you create a new session with the Appium 2.x.

Please contact us if you would like to use a driver, a plugin or a version which is not in the list.

Setting <code class="dcode">appiumOptions</code> for Appium 2

<code class="dcode">headspin:appiumOptions</code> capability is available to configure the Appium server in a session, using the capabilities suggested by the Appium team for providers supporting Appium 2.x*.

Available keys

Example

{
    "headspin:appiumOptions": {
        "version": "2.0.0",
        "automationVersion": "5.5.0",
        "plugins": ["images", "relaxed-caps"]
    }
}

Without <code class="dcode">headspin:appiumOptions</code>, you also can specify them as individual HeadSpin Appium capabilities.

• <code class="dcode">version</code> works as same as <code class="dcode">headspin:appiumVersion</code>
• <code class="dcode">automationVersion</code> works the same as <code class="dcode">headspin:appiumAutomationVersion</code>
• <code class="dcode">plugins</code> works as same as <code class="dcode">headspin:appiumPlugins</code>

The individual capabilities will take priority over those inside <code class="dcode">headspin:appiumOptions</code>. For example, if a capabilities set has both <code class="dcode">"headspin:appiumOptions": { "version": "2.0.0" }</code> and <code class="dcode">"headspin:appiumVersion": "1.22.3"</code>, the session will use Appium 1.22.3 provided as <code class="dcode">headspin:appiumVersion</code>.

Network Config

User Flow Status

To mark sessions passed, failed, or in some error state, you can either use a HeadSpin Appium command to end the session, or use the Performance Monitoring API at any time. In either case, the session must be attached to a user flow by specifying <code class="dcode">headspin:testName</code> (this in turn requires that capture is turned on for the session, see description in the Appium capabilities section).

Valid user flow status strings are: <code class="dcode">passed</code>, <code class="dcode">failed</code>, <code class="dcode">excluded</code>, and <code class="dcode">not_set</code>.

Note: If a session gets attached to a user flow and its status is set to passed, failed, or excluded, standard tags will be automatically added to the session. For more details on what these standard tags are, see Annotating Your Session: Session Tags.

Set user flow status using the <code class="dcode">headspin:quitSession</code> command

1. Set <code class="dcode">headspin:testName</code> when starting the session. This is required for the next step to work.
2. End the session by sending the command <code class="dcode">headspin:quitSession</code> with the argument <code class="dcode">{"status": <user flow status>}</code>.

For example, the Python script below sets the session's status to <code class="dcode">excluded</code>:

from appium import webdriver

caps = {
    ...  # Other capabilities
    "headspin:testName": "test user flow",  # Required to link session to user flow
    "headspin:capture": True                # Required to have a capture session
}

driver = webdriver.Remote('<Web Driver URL>', caps)

# Perform tests
...

response = driver.execute_script('headspin:quitSession', {'status': 'excluded'})

This will end the session and set its user flow status at the same time. It can be used in place of the <code class="dcode">driver.quit()</code> command to end the session. When called without any argument, it has the same effect as <code class="dcode">driver.quit()</code>.

If the command is successful, there will be no return value (<code class="dcode">response is None</code> is <code class="dcode">True</code>). However, if an argument is given but it could not be processed into a valid user flow status, then a string containing information about the problem will be returned. The session will still end, but no user flow status will be set.

Set user flow status using Performance Monitoring API

1. Set headspin:testName when starting the session, or link the session to a user flow after it has started using the Performance Monitoring API.
2. POST to the Performance Monitoring API to set the status of the session, using the session ID from the driver.

For example, the Python script below sets the session's status to <code class="dcode">passed</code> using <code class="dcode">requests</code> to post to the API:

from appium import webdriver
import requests

# Start a session with capture
driver = webdriver.Remote(...)

# Set api_token in the header
headers = {
    'Authorization': 'Bearer <your_api_token>'
}

perf_data = {
    'session_id': driver.session_id,
    'status': 'passed'
}
requests.post('https://api-dev.headspin.io/v0/perftests/upload', headers=headers, json=perf_data)

BYOD and <code class="dcode">appInstallStrategy</code>

Bring Your Own Device allows you to add your own devices to HeadSpin platform. You can run appium sessions against the devices, but the application installation might fail in iOS for some reason. You can try the Appium capability <code class="dcode">"appium:appInstallStrategy": "ios-deploy"</code> to help complete the installation successfully.

Resolving Errors

HeadSpin Appium sessions return errors directly from the underlying Appium driver without modification. Additionally, the HeadSpin platform may return the following extra errors: