The Sauce Labs Cookbook

Sauce Headless

Front End Performance Testing

Insights

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, from required capabilities to enabling animations.

Different Behaviors from Local Appium 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, and points 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.
  • 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 of the 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. 

CapabilityData TypeSummary
username
StringThe Sauce Labs "Username" you use to authenticate your tests. You can find this by logging into saucelabs.com, and going to Account > User Settings.
accessKey
StringThe Sauce Labs "Access Key" you use to authenticate your tests. You can find this by logging into saucelabs.com, and going to Account > User Settings.
Appium EndpointString

This capability refers the specific region/data-center that your desired device is located. There are currently two options for real devices:

app
String

This capability refers to the location of your mobile application. Please refer to the following page to learn more about how to upload your application to real devices.

Please note that if you're running a mobile browser test, this capability can be left blank.

platformName
String

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

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"

platformVersion
StringThe 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.
deviceName

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.

Using Regular Expressions for dynamic allocation of deviceName

You can use regular expressions for setting the deviceName dynamically. 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.

To learn more please visit: Dynamic Device Allocation.

Optional Capabilities for Real Device Testing

CapabilityData TypeSetting
appiumVersion
String

The version of Appium you want to use in your tests. If you leave this capability blank, or omit it completely, Sauce Labs will defer to the default Appium version installed on our platform.

name
StringA name for your test, to make it easier to find individual tests.
build
StringIf you're running several tests within a test suite, you can add a build tag to group these tests together.
tag
StringTags are useful for collaborating with teams and also for filtering results on your Sauce Labs Test Results and Archive pages.
newCommandTimeout
Float

Automated tests time out by default after 60 seconds of inactivity. You can increase this to 90 seconds with the newCommandTimeout desired capability.

commandTimeout
Float

Custom timeout in milliseconds for the WebDriverAgent backend. The maximum allowed timeout is 60,000 seconds.

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. Sauce Labs sets a default of 60 seconds for this capability.

tabletOnly
BooleanYou can use the tabletOnly desired capability to select only tablet devices by setting this capability to "true".
phoneOnly
BooleanYou can use the  phoneOnly desired capabilities to select only phone devices by setting this capability to "true".
privateDevicesOnly
BooleanIf you have access to both private and public devices, you can request allocation of private devices only by setting this capability to "true".
automationName
String

You can pass an automation value to use native automation frameworks (supported for Android native apps only). For Example:

UiAutomator2 Example
capabilities.setCapability("automationName", "uiautomator2");
cacheId
String
Specifying the desired capability cacheId (a randomized String) will allocate the device to you for 10 seconds after a test finishes. You can then re-use the same device in your next test. However the 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


Device Management Awareness

It's recommended to review the page: Device Management for Real Devices, to learn more about how Sauce Labs manages device allocation, device caching, and device cleanup.

noReset
BooleanYou 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, and is 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.
carrierConnectivityOnly
BooleanYou can use the carrierConnectivityOnly desired capability to allocate only devices that are connected to a carrier network.
recordDeviceVitals
BooleanDevice 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.
crosswalkApplication
BooleanAs 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.
autoGrantPermissions
BooleanBy default, applications are installed on devices in the Sauce Labs real device cloud with autoGrantPermissions 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.
enableAnimations
Boolean

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

NOTE: The enableAnimations capability will only work if privateDevicesOnly is set to true.

Unsupported Appium Capabilities

Some Appium capabilities are not yet supported for real devices. If you have any questions or concerns about unsupported capabilities, please contact your Customer Success Manager, refer to the Real Devices FAQ page, or submit a help desk ticket to: support@saucelabs.com

CapabilityPlatformNotes
installApp
iOS, AndroidManaged by RDC differently, but cannot be used inside an Appium test as part of the routine.
removeApp
iOS, AndroidManaged by RDC differently, but cannot be used inside an Appium test as part of the routine.
Edit TimezoneiOS, AndroidAppium does not provide a capability to edit the timezone of a device in automated testing on real devices. See Appium Capabilities for Emulators and Simulators for information about timezone capabilities in virtual device testing.

Override Settings Capabilities

These are custom capabilities developed by Sauce Labs to override settings that are enabled during app configuration. 

CapabilityPlatformDescription
resigningEnabled
iOS, AndroidEnables the resigning (iOS) or instrumentation (Android) of apps on the Sauce Labs side, which enables the usage of the other capabilities listed in this table.
sauceLabsImageInjectionEnabled
iOS, AndroidEnables the image injection feature.
sauceLabsBypassScreenshotRestriction
AndroidBypasses the restriction on taking screenshots for secure screens (i.e., secure text entry).
allowTouchIdEnroll
iOSEnables the interception of biometric input, allowing the test to simulate Touch ID interactions (not a Sauce Labs-specific capability).
groupFolderRedirectEnabled
iOS

Enables the use of the app's private app container directory instead of the shared app group container directory.
For testing on the Real Device Cloud, the app gets resigned, which is why the shared directory is not accessible.

systemAlertsDelayEnabled
iOSDelays system alerts, such as alerts asking for permission to access the camera, to prevent app crashes at startup.