saucectl run
Execute framework-agnostic tests using the saucectl
test orchestrator.
Usage
$ saucectl run [OPTIONS]
Extended Description
Execute tests according to the environment, framework, and test suite specifications defined in your configuration file or via command line options described in this document.
Options Summary
Key | Shorthand | Description |
---|---|---|
--artifacts.cleanup | Clear the artifacts directory before downloading new test data. | |
--artifacts.download.directory | A local directory to which test assets are downloaded. | |
--artifacts.download.match | Which asset files to download. | |
--artifacts.download.when | Criteria for downloading assets. | |
--async | Launch tests without waiting for preceding test results. | |
--build | Add a build reference to your tests. | |
--ccy | Maximum tests to run concurrently. | |
--config | -c | Alternate location of the configuration YAML file. |
--dry-run | Simulate a test run without running tests. | |
--env | -e | Define environment variables. |
--fail-fast | Stop suite execution after first failure. | |
--help | -h | Usage information for the run command. |
--no-color | Disable colored console output. | |
--region | -r | Sauce Labs target data center. |
--retries | Number of times to rerun a failed test suite. | |
--select-suite | Execute a particular test suite. | |
--show-console-log | Include the console.log contents in the output for all tests. | |
--tags | Add reference tags to your tests. | |
--timeout | Set a max test duration. | |
--uploadTimeout | Set a max upload duration. | |
--tunnel-name | Use a running Sauce Connect tunnel to test. | |
--tunnel-owner | The tunnel owner, if it is not the testing account. | |
--verbose | Enable detailed output. |
Options Details
--artifacts.cleanup
| OPTIONAL | BOOLEAN |
When set to true
, all contents of the specified download directory are cleared before downloading any new assets from the current test.
saucectl run --artifacts.cleanup true
--artifacts.download.directory
| OPTIONAL | PATH | RDC Only |
Specifies the path to the folder location in which to download artifacts. A separate subdirectory is generated in this location for each suite for which artifacts are downloaded. Must be set in conjunction with --artifacts.download.match
and --artifacts.download.when
.
saucectl run --artifacts.download.directory ./artifacts
--artifacts.download.match
| OPTIONAL | FILE/LIST |
Specifies which artifacts to download based on whether they match the name or file type pattern provided. Supports the wildcard character *
. Must be set in conjunction with --artifacts.download.directory
and --artifacts.download.when
.
saucectl run --artifacts.download.match console.log,another.log
--artifacts.download.when
| OPTIONAL | ENUM |
Specifies when and under what circumstances to download artifacts. Valid values are:
always
: Always download artifacts.never
: Never download artifacts.pass
: Download artifacts for passing suites only.fail
: Download artifacts for failed suites only.
Must be set in conjunction with --artifacts.download.directory
and --artifacts.download.match
.
saucectl run --artifacts.download.when always
--async
| OPTIONAL | BOOLEAN |
Allows you to launch tests without waiting for results of the preceding tests. This option can be helpful when relying on a CI tool to automatically launch tests. This option does not require a value; including it inline sets it to true
.
--build
| OPTIONAL | STRING | VDC Only |
Associates the tests with a build to support easy filtering of related test results in the Sauce Labs UI. This option is not yet supported for mobile real device tests.
saucectl run --build myBuildID
--ccy
| OPTIONAL | INTEGER |
Sets the maximum number of suites to execute at the same time. If the config defines more suites than the max, excess suites are queued and run in order as each suite completes.
For tests running on Sauce, set this value to equal or less than your Sauce concurrency allowance, as setting a higher value may result in jobs dropped by the server.
saucectl run --ccy 2
--config
| OPTIONAL | FILEPATH |
Specify an alternative configuration file to the default .sauce/config.yml
for this execution.
Shorthand: -c <path>
saucectl run -c ./path/to/{config-file}.yml
While you can use multiple files of different names or locations to specify your configurations, each file must be a *.yml
and follow the saucectl
syntax. If you are less comfortable with YAML, any of a wide variety of free online YAML/JSON validator tools may be helpful.
--dry-run
| OPTIONAL | BOOLEAN |
Simulate a test run without actually running any tests. This option does not require a value; including it inline sets it to true
.
saucectl run --dry-run
--env
| OPTIONAL | KEY=VALUE |
An environment variable key value pair that may be referenced in the tests executed by this command. Expanded environment variables are supported.saucectl run --env <key1>=<value1> --env <key2>=<value2> ...
Supported Frameworks
Frameworks and Products | Supported? | Note |
---|---|---|
Cypress | ✅ | Virtual Devices Only |
Playwright | ✅ | Virtual Devices Only |
TestCafe | ✅ | Virtual Devices Only |
Puppeteer Replay | ❌ | |
Espresso | ❌ | |
XCUITest | ✅ | Virtual Devices Only |
API Testing | ✅ | |
Sauce Orchestrate | ✅ |
--fail-fast
| OPTIONAL | BOOLEAN |
Stops suites after the first failure. This will not interrupt suites that have been started already. This option does not require a value; including it inline sets it to true.
saucectl run --fail-fast
--help
Usage information for the run
command.
Shorthand: -h
--no-color
| OPTIONAL | BOOLEAN |
Disables colorized console output for saucectl. This is particularly useful for CI environments that cannot display ANSI color codes, which may render the log output illegible. This option does not require a value; including it inline sets it to true
.
saucectl run --no-color
--region
| REQUIRED | STRING |
Specifies the Sauce Labs data center through which tests will run. Valid values are: us-west-1
(default) or eu-central-1
.
Shorthand: -r
saucectl run --region us-west-1
--retries
| REQUIRED | INTEGER |
Instructs saucectl
to rerun failed tests this many times.
saucectl run --retries 2
--select-suite
| OPTIONAL | STRING |
Specifies a test suite to execute by name rather than all suites defined in the config file.
saucectl run --select-suite <suite_name>
--suite
Versions of saucectl before v0.52.4 use the option --suite
instead.
--show-console-log
| OPTIONAL | BOOLEAN |
Includes the contents of the suite's console.log
in the output of the command regardless of the test results. By default, the console log contents are shown for failed test suites only. This option does not require a value; including it inline sets it to true
.
saucectl run --show-console-log
--tags
| OPTIONAL | LIST | VDC Only |
A keyword that may help you distinguish the test in Sauce Labs, and also helps you apply filters to easily isolate tests based on metrics that are meaningful to you. This option is not yet supported for mobile real device tests.
saucectl run --tags e2e,team2
--timeout
| OPTIONAL | DURATION |
Sets a limit (in seconds or minutes) for how long saucectl
can run this test (no limit by default).
When setting the timeout values for your suites, consider that native framework tests on real devices enforce a maximum test duration limit of 60 minutes.
saucectl run --timeout 10s
saucectl run --timeout 30m
--uploadTimeout
| OPTIONAL | DURATION |
Upload timeout that limits how long saucectl will wait for an upload to finish. Supports duration values like '10s' '30m' etc. (default: 5m)
saucectl run --uploadTimeout 10s
saucectl run --uploadTimeout 30m
--tunnel-name
| OPTIONAL | STRING |
Specifies an active Sauce Connect tunnel to establish a secure connection to run this test on Sauce Labs.
Replaces the former --tunnel_id
option, which is deprecated.
saucectl run --tunnel-name my-tunnel
--tunnel-owner
| OPTIONAL | STRING |
Identifies the Sauce Labs user who created the specified tunnel, which is required if the user running the tests did not create the tunnel.
Replaces the former --tunnel-parent
option, which is deprecated.
saucectl run --tunnel-name not-my-tunnel --tunnel-owner another.sauce.username
--verbose
| OPTIONAL | BOOLEAN |
Enables detailed output during the test run in order to facilitate troubleshooting potential authentication, connection, and/or container issues. This option does not require a value; including it inline sets it to true
.
saucectl run --verbose