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

Please select the desired platform for your Automated Mobile Testing use case:

Emulator and Simulator Platform Support

For detailed information on the full list of supported emulators and simulators, visit Supported Browsers and Devices.

Emulator and Simulator Project Support

The mobile application must be:

  • compiled for the simulator/device version of your choice
  • compressed into a .zip package/archive file (must include app directory)
  • uploaded and hosted in a place that Sauce Labs can access (for example: AWS, GitHub, or Sauce Storage)


  1. If you're using Sauce Storage, get the returned location, which will look something like
  2. In your test capabilities, specify the location of the .zip file, or the URL as described in Temporary Sauce Storage.

The mobile application must be:


  1. This StackOverflow article contains instructions on how to build an .apk file in Eclipse.
  2. In the test capabilities, specify the location of the .apk file, or the sauce-storage:app.apk URL as described in Temporary Sauce Storage.

Emulator and Simulator Security Recommendations

Network Connection

If you require secure/proxied connections to the Sauce Labs Cloud platform, they are made in one of two ways: Sauce Connect Proxy or IPSec VPN.

NOTE: IPSec VPN is an Enterprise-only feature and it is also the industry standard in network security. It includes AES 256 encryption and multiple setup options with forward proxies.

More Information

Real Device Platform Support

For more detailed information on the full list of supported real devices visit the supported browsers and devices page.


Real Device Project Support

The mobile application must be:

  • an .ipa file. Refer to the documentation on how to create an .ipa file.
  • uploaded and hosted in sauce storage, real device storage or installed from a remote location

The mobile application must be:

  • configured to have internet permissions
  • built into an .apk package/archive file
  • uploaded and hosted in sauce storage, real device storage or installed from a remote location

Choosing Public vs. Private Cloud

Enterprise Plans Only

This feature is available for Enterprise plans only. For more information about other benefits that are included with Enterprise plans, check out our Pricing page.

Sauce Labs offers access to both public and private device clouds. Which option you should choose depends on your testing needs.

Click the tabs above to toggle each use case:

  • The devices available on the public cloud are sufficient for your testing coverage
  • You need to reproduce bugs on a selection of hundreds of iOS and Android devices

  • You need to upload and spot check apps on devices you don’t have access to

  • You need to share manual test sessions and devices across teams worldwide

  • You are looking for a low-cost real device testing option

Click the tabs above to toggle each use case:

  • You need a very specific set of devices that aren't supported on the public cloud
  • Your security team insists on dedicated devices
  • You require a secure tunnel between your tests and our cloud to test
  • You want to run automated/parallel tests across multiple devices
  • You need specific settings which are set on the devices all the time

Real Device Security Recommendations

Network Connection

If your organization requires a secure, proxied connection to the Sauce Labs Cloud platform, you can configure this for your network via Sauce Connect Proxy or IPSec VPN.

IPSec VPN, the industry standard in network security, includes AES 256 encryption and multiple setup options with forward proxies. It is a Sauce Labs Enterprise only feature, whereas Sauce Connect Proxy is available for all Sauce Labs plans.


We use a proprietary process that wipes every device clean at the end of the testing session. Steps in this process include:

  • User accounts and data are cleared from the device
  • History and user data is cleared from the browser
  • Network settings are reset
  • Device settings are reset
  • The app is uninstalled, and any cached data is deleted

While we take these actions after each test session on a public device, users of the public RDC should be aware that Sauce Labs does not factory reset devices in the public RDC between test sessions, and these devices do not have anti-virus software installed on them. It is possible that other users of the public RDC may engage in malicious, careless or unsecure activity, and that sophisticated, persistent malware could therefore be present on any device in the public RDC.

For more information on Sauce Labs security settings, see Security Settings for Organizations.

Data Center

Data Center security related to real devices is described in Data Center Endpoints.

Real Device Management

Device Allocation

Dynamic Allocation involves providing 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.

Required Capabilities for Dynamic Allocation


Capability Explanation


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"


The platform version to use in your tests, for example "4" or "4.1".

Version Matching

This is a substring match. You can specify both major versions and incremental versions of an operating system. 

For example if you set only a major version 4, you also have access to all devices running incremental versions: "4.1"," 4.2", "4.2.1", "4.4.4" etc.

This also extends to minor and point versions. For example if you specify "11.4" it will match "11.4.0", "11.4.1", etc.


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

privateDeviceOnlyIf you have access to both private and public devices, you can request allocation of private devices only with "true"


Capability Explanation

tabletOnlySelect only tablet devices with "true"
phoneOnlySelect only phone devices with "true"
carrierConnectivityOnlyOnly allocate devices if they are connected to a carrier network with "true"

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. 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 real device selection menu of the Sauce Labs application, and then click the Details link for the device.

Device Caching

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.

More Information