Sauce Runner for Virtual Devices CLI Reference

Now Available on saucectl

Espresso testing for virtual devices is now supported on saucectl, our CLI tool used with Testrunner Toolkit. For details, see:




Sauce Runner for Virtual Devices provides the ability to run Espresso tests on Android emulators 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 code 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 or Sauce Runner for Virtual 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., sauce-runner-virtual).
tip

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

./sauce-runner-virtual --help

Required#

These command flags are required in order to run native mobile tests with Sauce Runner on virtual devices.

--test-framework#

Description: Specifies the name of the test framework you want to use. At the moment, espresso is the only supported option and value.

Shorthand: -f

Example:

./sauce-runner-virtual --test-framework=espresso

--user#

Description: Your Sauce Labs username. You can use the environment variable SAUCE_USERNAME to provide your login information. The command line argument will take precedence over the environment variable.

Shorthand: -u

Example:

./sauce-runner-virtual --user $SAUCE_USERNAME

--api-key#

Description: Your Sauce Labs Access Key, which you can find under User Settings in the Sauce Labs interface. You can also use the environment variable SAUCE_ACCESS_KEY to provide your login information. The command line argument will take precedence over the environment variable.

Shorthand: -k

Example:

./sauce-runner-virtual --user $SAUCE_USERNAME --api-key $SAUCE_ACCESS_KEY

--app#

Description: The local path or publicly accessible URL to the location of the application you want to test.

Shorthand: -a

Example:

--app='https://the.bestapp.ai/helloworld.apk'

--test-app#

Description: The local path or publicly accessible URL to the location of the test package you want to use.

Shorthand: -t

Example:

--test-app='https://the.bestapp.ai/app-debug-AndroidTest.apk'

--devices#

Description: The type of device you want to use with your test. You can specify two or more device arguments to run tests on multiple devices in parallel, and each device will execute the full test suite. You specify the type of device to use by setting the required deviceName and platformVersion properties.

Shorthand: -d

Properties:

PropertyRequiredDescription
deviceNameYesThe name of the device to use. You can use the Sauce Labs Platform Configurator to look up the Appium deviceName for supported devices.
platformVersionYesThe operating system version of the device you want to use. Supported values depend on the device. You can use the Sauce Labs Platform Configurator to look up the Appium platformVersion for the device.
localeNoLocation of the device.
orientationNoOrientation of the device. Supported values are:
  • portrait(default)
  • landscape

Examples:

Test on one Device
-d 'deviceName=Google Pixel GoogleAPI Emulator,platformVersion=7.0'
Test on two Devices
--devices='deviceName=LG Nexus 4 GoogleAPI Emulator,platformVersion=4.4' \
--devices='deviceName=Google Pixel GoogleAPI Emulator,platformVersion=7.0'

Full Example#

Basic Setup (minimum required options only)

emulators/runner-ex1.sh
loading...
See full example on GitHub
tip

Go to our GitHub repository for example scripts, plus demo apps and tests.

Optional#

These flags provide additional configuration options.

--exclude-tests#

--include-tests#

Description: Optional parameters to run a subset of tests. You can provide a test filter to either exclude or include tests. By default, the full test suite is executed.

Shorthand: -e | -i

Filters:

FilterDescription
class com.example.MyClass#testLoginFilter one test method
com.example.MyClass#testOrderFilter two test methods
class com.example.MyClassFilter a test class
package com.example.testPackageFilter a package
size small|medium|largeFilter by size. Tests should be annotated with SmallTest, MediumTest, or LargeTest. Cannot be used to exclude-tests.
annotation com.example.MyAnnotationFilter by test annotation

Examples:

Run only one test method
--include-tests='class com.example.MyClass#testLogin'
Run all but one test class
--exclude-tests='class com.example.MyClass'
Run only the large tests
--include-tests='size large'

--tunnel-identifier#

Description: specify a Sauce Connect Proxy tunnel to use with the tests.

Shorthand: -n

Example:

--tunnel-identifier=dev_tunnel

--data-center#

Description: specify a Sauce Labs Data Center. Possible values are us-west-1 and eu-central-1.

Shorthand: n/a

Example:

--data-center eu-central-1

--skip-download-junit-reports#

Description: skips downloading the JUnit reporting files at the end of test suite execution.

Shorthand: n/a

Example:

--skip-download-junit-reports

--verbose#

Description: sets the verbosity of console output. Valid options as DEBUG, INFO, WARN and ERROR.

Shorthand: -v

Example:

--verbose

--version#

Description: returns the version information for Sauce Runner.

Shorthand: n/a

Example:

./sauce-runner-virtual --version

--help#

Description: prints this command line reference to the console.

Shorthand: -h

Example:

./sauce-runner-virtual --help
Last updated on by Kim