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.
- 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.,
You can also view the vUSB CLI directly in the command line terminal by running the
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.
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.
Description: specifies the path to the
*.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.
Description: specifies the path to the
*.apk file of the test.
Description: specifies the Data Center to use in your tests. Possible values:
Full Example (required flags only)
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.
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
platformVersionbecause they'll be set by default (i.e., if you include these separately included in your test script, they will be ignored).Example--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.Example--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
--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
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.
Description: if set, only private devices will be queried.
Description: if set, only phones will be queried.
Description: if set, only tablets will be queried.
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:
Allocates any Samsung Galaxy device:
Allocates any device with Samsung Galaxy S7 in the name (i.e., Samsung Galaxy S7, Samsung Galaxy S7 Edge):
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
--testsToRun ClassA,ClassB/methodCruns all tests in
ClassB). This executes all tests in
Description: specify a list of test options to Espresso. The key-value pairs supported by Espresso are documented here: Android Developers—am instrument options.
Execute all tests in class
TestClassA:Example--e class com.example.android.TestClassA
Execute a specific test in class
TestClassB:Example--e class com.example.android.TestClassB#methodName
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.
Description: specifies the interval in seconds to check test results. Default is
Description: sets your test timeout (unit = minutes). Test duration cannot exceed 60 minutes. Default value is
Description: specifies the folder for the JUnit XML output.
Description: specifies the URL of an alternative REST endpoint to use. For a list of endpoints, see Data Center Endpoints for further details.
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.
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