The Sauce Labs Cookbook

Sauce Headless

Front End Performance Testing


External Resources

More Info

Page tree
Skip to end of metadata
Go to start of metadata

This topic describes the Appium capabilities to use in your real device tests. 

Different Behaviors from Local Server Testing

Some Appium capabilities behave differently when running Appium tests in the real device cloud instead of against a local Appium server, including :

  • All the emulator-only capabilities will not work
  • The app capability is always overwritten to point to the app file you uploaded to our system
  • The noReset capability only works if device caching is enabled. By default, noReset is set to false.
  • For test suite runs, the testobject_suite_name and name capabilities are ignored
  • Some Appium capabilities might not be supported. You can find a list in the last section of this topic.

Different setups might have slightly different ways of handling capabilities and/or different requirements. You should also check the examples for your specific setup to make sure you are providing all required capabilities.

Required Capabilities for Real Device Testing

Your Appium scripts for real device testing must include these capabilities. Check out the example script in Dynamic Allocation Examples for examples of these capabilities and their values. 

testobject_api_keyThe API key you use to authenticate your tests. You can find this in the Appium setup instructions for your project.
Appium Endpoint




The ID of the application you want to test. To find the ID for your application, log into and select the app you want to test. In the Active Version panel, click All Versions. You will find the app_id listed in the ID column, as shown in this screenshot:

Installing App Dependencies

You can install an application dependency on the same device by passing an array of app ids, for example testobject_app_id:[4,6] . The ID number for dependency apps is assigned when you upload them as dependencies of the main app.

Optional Capabilities for Real Device Testing


The version of Appium you want to use in your tests.
By default this is 1.14.0

A name for your test, to make it easier to find individual tests

Capabilities for Dynamic Allocation of Devices

Values are Not Case Sensitive

The values for capabilities are case-insensitive, so "android" is the same as "Android", and "ios" is the same as "iOS"

With dynamic allocation, you provide basic parameters for the platform and operating system, or the type of device you want to use in your tests, and a device with those specifications is selected from the device pool. While static allocation allows you more fine-grained control over the device used in your tests, it can also cause delays in your test execution if that device isn't available when you run your tests. If you only need to test on a particular platform and OS version, such as an Android 4.1,  or on a particular type of device, you should use dynamic allocation, and we recommend that you use dynamic allocation for all automated mobile application testing in CI/CD environments. 

platformName and platformVersion

Set the capabilities platformName and platformVersion to dynamically allocate any type of a device with those specifications to your test run. You must specify both capabilities. 



The type of mobile platform to use in your tests, for example "Android" or "iOS".


The platform version to use in your tests, for example "4" or "4.1". This is a substring match. You can specify both major versions and incremental versions of an operating system. If you set only a major version, for example 4, you will also have access to all devices running incremental versions, such as "4.1"," 4.2", "4.2.1", "4.4.4". This also extends to minor and point versions. If you specify "11.4" it will match "11.4.0", "11.4.1", etc.


If you only want to test on a particular type of device, such as a Samsung S7 or an iPhone, set deviceName to the display name of the device as shown in the Real Devices menu of Sauce Labs.



The display name of the device to use, such as "Samsung S7".

Using Regular Expressions for deviceName

You can also use regular expressions for setting the deviceName . For example:

"iPhone.*", "iPhone .*" will allocate any iPhone. "

.*nexus.*" will allocate any device with the word "nexus" in its display name.

"iPhone [67]" or "iPhone [6-7]" will allocate either "iPhone 7" or "iPhone 6" device.

"iPhone [67]S" or "iPhone [6-7]S" will allocate either "iPhone 7S" or "iPhone 6S" device. "iPhone 7.*" will allocate "iPhone 7" or "iPhone 7S", or any device that starts with the display name "iPhone 7"

Regular expressions are case insensitive, for example, "iphone .*S" and "IPHONe .*s" are the same.

Optional Capabilities for Dynamic Allocation


If you have access to both private and public devices, you can request allocation of private devices only. 


tabletOnly and phoneOnly

You can use the  tabletOnly  and  phoneOnly  desired capabilities to select only phone or tablet devices.



You can use the carrierConnectivityOnly desired capability to allocate only devices that are connected to a carrier network.



Device vitals are a collection of the mobile device performance data taken in real time during test execution. Vitals includes CPU utilization, memory consumption, network usage for both wifi and carrier connectivity where applicable, file operation and more. Measuring device vitals during test execution provides insights for analyzing app performance during operation.


Dynamic Allocation Examples

Setting Capabilities for Android Version 4
capabilities.setCapability(“platformName”, “Android”);
capabilities.setCapability(“platformVersion”, “4"); 
Setting Capabilities for Android Version 4.4.2
capabilities.setCapability(“platformName”, “Android”);
capabilities.setCapability(“platformVersion”, “4.4.2"); 
Setting Capabilities for iOS Version 9
capabilities.setCapability(“platformName”, “iOS”);
capabilities.setCapability(“platformVersion”, “9"); 
Setting Capabilities for iOS Version 10.3.1
capabilities.setCapability(“platformName”, “iOS”);
capabilities.setCapability(“platformVersion”, “10.3.1"); 
Dynamic Allocation of an iPhone Device from a Private Pool
public void setUp() throws Exception {

		DesiredCapabilities capabilities = new DesiredCapabilities();
		// Set my TestObject API Key

		capabilities.setCapability("testobject_api_key", "1234567890123456789012345678901234567890"); 
		// Dynamic device allocation of an iPhone 7, running iOS 10.3 device 
		capabilities.setCapability("platformName", "iOS"); 
		capabilities.setCapability("platformVersion", "10.3");
		capabilities.setCapability("deviceName", "iPhone 7");
		// Set allocation from private device pool only
		capabilities.setCapability("privateDevicesOnly", "true");
		// Set Application under test
		capabilities.setCapability("testobject_app_id", "1");
		capabilities.setCapability("name", "My Test 1!");

		// Set Appium version
		capabilities.setCapability("appiumVersion", "1.6.4");
		// Set Appium end point
		driver = new IOSDriver(new URL(""), capabilities);

Capabilities for Static Allocation of Devices

With static allocation, you can specify the device to use in your tests, but if that device is not available when you run your tests, it will delay test execution. For this reason, you should always make sure that the device you want to use is available before launching your tests. 


Set the capability deviceName to the ID of the device to allocate a specific type of device to use  in your tests. The platformName and platformVersion capabilities will be set by default, and if these are included in your test script, they will be ignored. 

deviceNameThe ID of the device you want to use in your test, for example "LG_Nexus_5X_real". You can find the ID for a device by locating it in the list of real devices in the Sauce Labs application, and then click the Details link for the device.

Device Caching and Resetting Applications

testobject_cache_device Capability Deprecated

Previous versions of the Real Device Cloud platform used the capability  testobject_cache_device to keep the device allocated to you during the cleaning process, but you could only use this capability for static allocation. This has been deprecated and replaced with the capability cacheId, described in this section, which works for both static and dynamic allocation. If you have scripts that use testobject_cache_device, they will still work for static allocation, and the 10 second limit on cached devices is still the same.

By default, every time you complete a test session, the real device cloud uninstalls your application, performs device cleaning, and de-allocates the device. This means that if you have multiple tests that you want to run on the same device, you will, by default, wait for this cleaning process to complete between every test. However, you can use the capability cacheId to leave the device allocated to you for 10 seconds after each test completes. If you immediately start another test on the device, you won't need to wait for the allocation and device cleaning process to be repeated. In this case, no device cleaning will take place in between sessions, with the only exception being the application under test and the data it owns.



A random string. This value for cacheId must be the same for all test methods that you want to run on the cached device. In addition, the application and project ID used for the tests must remain the same, along with the values for these capabilities:
  • deviceName
  • platformName
  • platformVersion
  • tabletOnly
  • phoneOnly
  • privateDevicesOnly
  • automationName
  • autoGrantPermissions
  • appiumVersion

Using Device Caching with noReset

You can also use the cacheId capability in conjunction with the standard noReset Appium capability. In the default case, where noReset is set to false, your application will be uninstalled and reinstalled after every test. If noReset is set to true, the application you are testing won't be reinstalled after every test run. This might save you further time, but it won't be suitable for test setups that require the application's state to be reset between tests. Note that then cacheId is set, no device cleaning will take place in between sessions, regardless of noReset value.

UIAutomator2 support

Set the following capabilities to use UIAutomator2 with Appium (Android native apps only)

Setting Capabilities for an LG G2 Device
capabilities.setCapability("automationName", "uiautomator2");

Live View and Report URLs

Set these capabilities to view your test while it's running, and to view the report when it completes.



The URL to the live view of your test execution


The URL to Appium test report generated when the test completes.
Example for Setting Live View and Report Capabilities
private AndroidDriver driver;

public void setup() throws MalformedURLException {

    AppiumDriver driver = new AppiumDriver(new URL(""), capabilities);


Public URL to API for Test Details

Use this capability  to get access to test details such as test information, video, and screenshots via the Sauce Labs API.




The URL to the test report

Session Creation Timeout

When creating an Appium session on the real devicepublic cloud, it may be the case that the device you want to test against is "in use" and not currently available for testing. When this happens, the tests will wait for 15 minutes to create a session on the device by default. If you want to set a custom timeout for session creation, you can do so using the desired capability  testobject_session_creation_timeout

testobject_session_creation_timeoutA string containing the desired timeout in milliseconds. The maximum allowed timeout is 30 minutes.

WebDriverAgent Timeout for iOS Devices

When creating an Appium session on the real device cloud for any iOS device, it is possible to set the desired capability commandTimeouts . It will set a timeout for the WebDriverAgent backend which will prevent automated test sessions from being blocked when the Appium WebdriverAgent backend freezes unexpectedly. TestObject sets a default of 60 seconds for this capability. If it is necessary it is possible to set a lower value by setting the desired capability.

commandTimeoutsCustom timeout in milliseconds for the WDA backend. The maximum allowed timeout is 60,000 seconds.

Patched Chromedriver for Use with Crosswalk

As described in Appium Issue 4597 and Chromedriver Issue 2375613002, mobile tests using Crosswalk will fail because because of attempts to connect to the wrong socket on the device. Sauce Labs has developed a patched version of Chromedriver that will work with Crosswalk. You can specify to use this patched version with the crosswalkApplication desired capabilitiy.


Disabling autoGrantPermissions

By default, applications are installed on devices in the Sauce Labs real device cloud with the autoGrantPermissions desired capability set to true, as long as the API number of the device is equal to 23 or higher. You can disable this by explicitly setting autoGrantPermissions to false


true = default

false = option

Enabling Animations

By default, animations are disabled on real devices. You can enable animations for private cloud devices only with the enableAnimations capability. 


true = option

false = default


Unsupported Appium Capabilities

Some Appium capabilities are not yet supported for real device. If you have any questions or concerns about unsupported capabilities, please contact your Customer Success Manager.

iOS, AndroidManaged by RDC differently, but cannot be used inside an Appium test as part of the routine.
iOS, AndroidManaged by RDC differently, but cannot be used inside an Appium test as part of the routine.