Sauce Runner for Real Devices CLI Reference

Sauce Runner for Real Devices provides the ability to run Espresso and XCUITest tests on Android and iOS real devices in the Sauce Labs cloud. This topic describes the required and optional command parameters you can use to set up your test runs.

NOTE: All examples in this page assume knowledge of Sauce Runner General Usage. Please review before proceeding.

What You'll Need#

  • Your Sauce Labs account credentials.
  • Your mobile app file (both debug and non-debug app) and test file.
  • Have the Sauce Runner for Real Devices downloaded and installed to your local machine.
  • Prior to using the CLI Reference below, navigate (cd) to the specific folder directory on your local machine where you downloaded and placed your Sauce Runner file (i.e., runner.jar).

You can also view the vUSB CLI directly in the command line terminal by running the -h (--help) flag.

java -jar runner.jar --help


These commands and flags are required for use with Sauce Runner for Real Devices. They are not compatible for use with Real Device Cloud YAML file configuration.

espresso or xcuitest#

Description: defines the test framework you wish to use for your test (choose only one).


Description: specifies the access key for your Sauce Labs account. You can find it under Account > User Settings.

--apikey ab015c1e-xxxx-xxxx-xxxx-xxxxxxxxxxx


Description: specifies the path to the *.ipa or *.apk file of the app under test, or the ID number of an already uploaded app. In your command line, refer to the location where you have downloaded the runner.jar file and run the command from the folder from where you downloaded the runner.

Example Folder Structure
|_{root / your project folder}
--app ExampleApp.ipa


Description: specifies the path to the *.ipa or *.apk file of the test.

--test ExampleApp.Tests.ipa


Description: specifies the Data Center to use in your tests. Possible values: US or EU.

--datacenter US

Full Example (required flags only)#

Full Example (required flags only)

java -jar runner.jar espresso --test ExampleApp.Tests.apk /
--app ExampleApp.apk --apikey 77029389527648BE81600Dxxxxxxxxxx --datacenter US


Here are some additional command line configuration options.


Description: specifies the exact device to use in your tests by providing the Device ID. See Static Device Allocation for detailed instructions. For Static Allocation.

--datacenter US --device iPhone_11_13_5_real_us


Description: define a list of devices on which the tests should be executed, using static and/or dynamic allocation, to run tests in parallel. See Static and Dynamic Device Allocation for detailed instructions.

  • Static Allocation: specify an exact device by setting to the Device ID. When using this, there's no need to specify the platformName and platformVersion because they'll be set by default (i.e., if you include these separately included in your test script, they will be ignored).
    --datacenter EU --devices iPhone_11_13_5_real_us --testname MyTestName
  • Dynamic Allocation: specify basic device name parameters using regular expressions (regex) to dynamically allocate a device.
    --datacenter EU --devices iPhone.* --testname MyTestName

As an option, you can combine this with the --testsToRun command to run a select set of tests against a specific device. See --testsToRun for examples.

Default Device Allocation

If you don't specify a --device/--devices for your test, one will be assigned to your tests based on your AUT (application under test) platform type.


Description: sets a custom test name to appear on the UI. Default is Test.

--datacenter US --device iPhone_11_13_5_real_us --testname MyTestName


Description: specifies an operating system version to use. For Dynamic Allocation. For example, use 9 to allocate a device running major version 9 and arbitrary versions of the OS; use 9.3.3 for a specific minor version.

--platformVersion 9.3.3


Description: if set, only private devices will be queried.

--datacenter US --privateDevicesOnly true


Description: if set, only phones will be queried.

--datacenter US --phoneOnly true


Description: if set, only tablets will be queried.

--datacenter US --tabletOnly true


Description: find a find by specifying a regular expression (regex) to dynamically allocate a device. It looks for available devices using wildcard names, giving you the ability to run a specified test on a pool of devices that are configured the same but have different names for parallel processing. For Dynamic Allocation; see Static and Dynamic Device Allocation for detailed instructions.

Allocates any iPhone Plus device:

--datacenter US --deviceNameQuery 'iPhone 8.*'

Allocates any Samsung Galaxy device:

--datacenter US --deviceNameQuery 'Samsung Galaxy.*'

Allocates any device with Samsung Galaxy S7 in the name (i.e., Samsung Galaxy S7, Samsung Galaxy S7 Edge):

--datacenter US --deviceNameQuery 'Samsung Galaxy 7'


iOS Only

Description: specify a comma-separated list of test cases or test classes on which you'd like to run tests.

  • If you want to run all tests of a class, provide only the classname.
  • If you want to run a specific method of a class, provide the class name and method name separated with a / (i.e., --testsToRun ClassA,ClassB/methodC runs all tests in ClassA and only methodC of ClassB). This executes all tests in ClassA and only methodC of ClassB:
--datacenter EU --testname MyTestName4 --testsToRun ClassA,ClassB/methodC


Android/Espresso Only

Description: specify a list of test options to Espresso. The key-value pairs supported by Espresso are documented here: Android Developers—am instrument options.

  1. Execute all tests in class TestClassA:

    --e class
  2. Execute a specific test in class TestClassB:

    --e class


Description: specifies the identifier of the tunnel you want to use. This is required if you're using Sauce Connect Proxy. You can find the tunnelIdentifier name on Sauce Labs under Tunnels, after you've launched the tunnel.

--tunnelIdentifier <your-tunnel-name>


Description: specifies the interval in seconds to check test results. Default is 30.

--checkFrequency 15


Description: sets your test timeout (unit = minutes). Test duration cannot exceed 60 minutes. Default value is 60.

--timeout 10


Description: specifies the folder for the JUnit XML output.

--test ./SampleAppUITests-tests.apk --xmlFolder ./tmp


Description: specifies the URL of an alternative REST endpoint to use. For a list of endpoints, see Data Center Endpoints for further details.

--url <rest-endpoint-url>


Android/Espresso Only

Description: if set, the instrumentation will start with Test Orchestrator version 1.1.1 in use.

In most cases, we recommend adding the --e clearPackageData true parameter to remove all shared state from your device's CPU and memory after each test.

--e useTestOrchestrator clearPackageData true class


Description: specifies a direct domain connection for your proxy server and port, so that Sauce Runner can connect to the internet. If the proxy needs authentication, use the optional parameters http.proxyUser and http.proxyPassword.

-Dhttp.proxyHost=<your proxy server>
-Dhttp.proxyPort=<the port to use>
-Dhttp.proxyUser=<the username to use>
-Dhttp.proxyPassword=<the password to use>

Additional Resources#

Last updated on by Kim