Skip to main content

Espresso and XCUITest on Sauce Labs

Sauce Labs uses its framework agnostic test orchestrator saucectl to execute Espresso and XCUITest tests based on one or more configuration files that instruct saucectl to run your tests exactly the way you specify. Results get published in your Sauce Labs account, where you can compare 30 days of results across different environments and frameworks all in one view.

What You'll Need#

Installation & Setup#

saucectl can execute both Espresso and XCUITest tests, so the set up steps are the same regardless of which framework you are using.

1. Install saucectl#

Begin by installing the saucectl CLI so it has access to your local project.

sudo sh -c 'curl -L | bash -s -- -b /usr/local/bin'
Required Minimum Versions

Espresso requires saucectl version 0.36.0 or later and XCUITest requires saucectl version 0.44.0 or later.

2. Check out the demo repositories#

Clone or download the Espresso and/or XCUITest example repos, as applicable to your project, to obtain the saucectl directory structure and example files for use as templates.

3. Link your Sauce Labs account#

  1. Generate a credentials file that saucectl can reference to authenticate your CLI commands.
    saucectl configure
  2. Enter your Sauce Labs SAUCE_USERNAME and SAUCE_ACCESS_KEY at the prompts.
  3. saucectl creates a credentials.yml file in a .sauce folder of your home directory.
Use Environment Variables

You can set your Sauce Labs credentials as environment variables instead of generating a credentials.yml, if you prefer. In systems where both sets of credentials exist, environment variable values are prioritized.


Each demo repo includes a sample config.yml file (in the <root>/.sauce directory) that is preconfigured to run the example test, which is also included in the repo.

Modify the config.yml file to run your existing tests.

  • TestObject Migration: refer to the Commands Map to determine which CLI commands and/or YAML configuration properties to use based on your TestObject configurations.
  • New Accounts: see the saucectl configuration documentation for Espresso and XCUITest.

For Android tests, if your emulator session fails to start, make sure the app you are targeting is an \*.apk, not an \*.aab, as the latter is not yet supported in emulator tests.

Alternative Config Files

You can create multiple configuration files to support different frameworks or different test setups and then reference the applicable configuration file at runtime using the CLI command:

saucectl run -c ./path/to/<configFile>.yml

TestObject (Legacy RDC) to saucectl Commands Map#


TestObject End-of-life

TestObject was discontinued on September 1, 2021. If you have any questions, please reach out to your Customer Success Manager or Sauce Labs Support.

saucectl configures and runs your Espresso and XCUITest tests entirely from the CLI and YAML configuration settings. The following tables provide a list of testing actions, mapping the TestObject configuration settings to the equivalent settings in saucectl. Both TestObject and Sauce Labs utilize CLI commands and YAML configuration files to define the many ways in which you can run your tests. Some actions can be set using either a CLI command or a YAML property, while other actions can only be configured by one or the other, so the maps below are separated by CLI commands and YAML properties for ease of navigation.


Real Device testing on Sauce Labs is data center contingent, so you will only have access to the public and private devices available within the data center specified for the test, rather than the entire body of devices across all data centers. Each data center includes a very similar variety of devices and operating systems to provide a broad selection for testing, but depending on your organization’s concurrency allowances, this separation may affect the number of tests you can run in parallel.

ConfigurationLegacy CLIsaucectl CLI
Specify the framework.espresso or xcuitestMust use YAML
Pass account credentials (TestObject).--apikeyCreate Credentials file
Provide the location of the app to be tested.--appMust use YAML
Provide the location of the test app.--testMust use YAML
Identify your applicable data center.--datacenter--region
Specify a particular device to run the test on.--deviceMust use YAML
Indicate device selection to be dynamic.--devicesMust use YAML
Provide a name for the test.--testnameMust use YAML
Choose a device running a particular platform version.--platformVersionMust use YAML
Choose devices from a private pool only.--privateDevicesOnlyMust use YAML
Choose a phone device only.--phoneOnlyMust use YAML
Choose a tablet device only.--tabletOnlyMust use YAML
Ensure the device is connected to a cellular network.Not supportedMust use YAML
Choose any device where the name matches the regex.--deviceNameQueryMust use YAML
Specify which test class to run.--testsToRun <class>Must use YAML
Specify which methods to run.--testsToRun <class>/<method>Must use YAML
Exclude certain classes from the test.--e -e= class name.of.class1,name.of.class2Must use YAML
Run only tests matching the specified size.--e -i=size sizeMust use YAML
Specify which package to run.--e packageMust use YAML
Exclude tests in the specified package.--e notPackageMust use YAML
Run only tests matching the specified annotation.--e -i=annotation use YAML
Exclude tests matching the specified annotation.--e -i=notAnnotation use YAML
Further specify Espresso test options using supported key-value pairs.--eNot supported
Identify a running Sauce Connect tunnel to use for secure connectivity to the cloud.--tunnelIdentifier--tunnel-name
--tunnel-id DEPRECATED
Identify the user who created the tunnel, if it differs from the user running the test.Not supported--tunnel-owner
--tunnel-parent DEPRECATED
Specify how often (seconds) the runner should check for test results.--checkFrequencyNot supported
Specify the maximum length of time (minutes) the test can run.--timeout--timeout
Specify a folder to direct the JUnit XML output.--xmlFolderNot supported
Specify an alternative REST endpoint (Is this TO only? Covered by region in SL??--urlNot supported
Remove shared states between tests.--e clearPackageDataMust use YAML
Set up a proxy connection.--D-e HTTP_PROXY=$<HTTP> HTTPS_PROXY=$<HTTPS>
Specify the concurrency to use for the test execution (up to account max).Not supported--ccy
Specify an alternative path and file to use as the configuration file.config --path--config
Set environment variable values on which other settings depend (such as proxy host/port values).Not supported--env
Simulate a test without actually executing.Not supported--dry-run
Return additional output for troubleshooting purposes.--verbose--verbose
Provide tags for use in filtering jobs in the Sauce Labs UI in ways that are meaningful for your org, such as release numbers or dev teams.Not supported--tags <tag1,tag2...> (Espresso RDC Only)
Associate the job with a build ID for grouping jobs in the Sauce Labs UI.Not supported--build (Espresso RDC Only)
Specify the circumstances under which to download test artifacts.Not supportedMust use YAML
When downloading is enabled, specify that only certain types of test artifacts are to be downloaded.Not supportedMust use YAML
When downloading is enabled, specify the download location.Not supportedMust use YAML