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.

caution

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

YAML Required

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>

Formerly --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).

Real Device Max Duration

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.

note

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.

note

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