Skip to main content

Mobile App Testing with Espresso and XCUITest

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 dashboard, where you can compare 30 days of results across different environments and frameworks all in one view.

What You'll Need#

  • Sauce Labs account USERNAME and ACCESS_KEY Look them up
  • Your Espresso or XCUITest apps and files

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.

curl -L | bash
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.

  • Test Object Migration: refer to the Commands Map to determine which CLI commands and/or YAML configuration properties to use based on your Test Object configurations.
  • New Accounts: see the saucectl configuration documentation for Espresso and XCUITest.
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

Legacy to saucectl Commands Map#

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 Test Object configuration settings to the equivalent settings in saucectl. These maps are separated by CLI commands and YAML properties for ease of navigation.


Both Test Object 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.

ConfigurationLegacy CLIsaucectl CLI
Specify the framework.espresso or xcuitestMust use YAML
Pass account credentials (Test Object).--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
Run only tests matching the specified annotation.--e -i=annotation 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-id
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 a name for the job as it will appear in the Sauce Labs UI.Not supportedMust use YAML
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 supportedMust use YAML
Associate the job with a build ID for grouping jobs in the Sauce Labs UI.Not supportedMust use YAML
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
Last updated on by Tian Feng