Skip to main content

saucectl CLI

The saucectl command line interface orchestrates the relationship between your tests in your framework, and the rich parallelization, test history filtering, and analytics of Sauce Labs. This page defines each of the commands and flags available in the CLI to allow you to execute your tests with precision.

See Installation and Setup for installation options.

$ saucectl init [flags]#

A bootstrapping command to generate a configuration file for the framework of your choice in the format required by saucectl. Running the command with no parameters initiates interactive mode, prompting you for relevant property values iteratively. Alternatively, you can add supported parameters inline to specify the relevant property values.

In either case, the command generates a .sauce/config.yml folder and file in the location from which the command is run. If you have an existing project directory for your framework, it is advised that you run this command from the project root.

Interactive Example
$ saucectl init12:13:20 INF Start Init Command? Select region: us-west-1? Select framework:  [Use arrows to move, type to filter]> cypress playwright puppeteer testcafe espresso xcuitest
Batch Example
$ saucectl init -r us-west-1 -f cypress -b chrome

saucectl supports the following configuration flags as inline specifications.

--accessKey <string>#

| OPTIONAL | STRING |

The authentication access key associated with the Sauce Labs user account making this request. If you have not set your authentication credentials as environment parameters or generated a credentials.yml file, this value is required.

Shorthand: -a <string>


--app <string>#

| OPTIONAL | STRING | XCUITEST/ESPRESSO ONLY |

The path to a valid mobile application to test.


--artifacts.download.when <string>#

| OPTIONAL | STRING |

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. (default value)

--async#

| OPTIONAL | BOOLEAN | Sauce Cloud only |

Launches tests without waiting for test results.


--browserName <string>#

| REQUIRED | STRING | WEB-APP ONLY |

The name of the browser in which to run tests.

Shorthand: -b <string>


--cypress.config <string>#

| REQUIRED | STRING | CYPRESS ONLY |

The file path to the Cypress configuration file (typically cypress.json).


--device <string>#

| OPTIONAL | STRING | XCUITEST/ESPRESSO ONLY |

Find a real device for this test by matching a set of one or more device characteristics:

CharacteristicDescriptionExample
idSpecify a device by its ID. Using this selection flag ignores all other characteristics and is not advised because availability of a specific device is uncertain and could cause your test to time out.--device "id=HTC_U11_real_us"
nameFind a device based on a partial name in order to increase likelihood of availability of similar devices.--device "name=HTC.*"
platformVersionFind a device based on its platform version.--device "platformVersion=8.0"
carrierConnectivityThe selected device must be connected to a cellular network.--device "carrierConnectivity=true"
deviceTypeThe selected device must be a particular type (PHONE, TABLET, or ANY).--device "deviceType=PHONE"
privateThe selected device must be private.--device "private=true"

You can specify a combination of device characteristics within this flag:

--device "name=HTC.*,platformVersion=8.0.0,carrierConnectivity=true"

--emulator <string>#

| OPTIONAL | STRING | ESPRESSO ONLY |

Specify a virtual device for the test by matching a set of one or more emulator characteristics.

CharacteristicDescriptionExample
nameSpecify all or part of the emulator name. Supported VMD List--emulator "name=Android.*"
platformVersionSpecify the emulator platform version.--emulator "platformVersion=7.1"
orientationSpecify how the emulator should be oriented for the test (portrait or landscape).--emulator "orientation=portrait"

You can specify a combination of emulator characteristics within this flag:

--emulator "name=Samsung Galaxy S8 FHD GoogleAPI Emulator,platformVersion=7.1"

--framework <string>#

| REQUIRED | STRING |

The framework for which this configuration is intended.

Shorthand: -f <string>


--frameworkVersion <string>#

| REQUIRED | STRING | WEB APPS ONLY |

The version of the framework that is compatible with the tests defined in this configuration.

Shorthand: -v <string>


-h, --help#

Usage information for the init command.


--platformName <string>#

| OPTIONAL | STRING | WEB APPS ONLY |

A specific operating system and version on which to run the specified browser and test suite.

note

You can optionally specify docker here as the platform.

Shorthand: -p <string>


--region <string>#

| 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 <string>


--testApp <string>#

| REQUIRED | STRING | XCUITEST/ESPRESSO ONLY |

The path to the mobile testing application.

Shorthand: -t <string>


--username <string>#

| OPTIONAL | STRING |

A valid Sauce Labs user account. If you have not set your authentication credentials as environment parameters or generated a credentials.yml file, this value is required.

Shorthand: -u <string>


$ saucectl configure [flags]#

Allows you to provide your [Sauce Labs credentials]((https://app.saucelabs.com/user-settings) for the purpose of generating a credentials.yml file that saucectl can access to automatically authenticate commands without requiring manual authentication. The credentials.yml file is created in a .sauce folder in your home directory.

Environment Variable credentials prioritized

saucectl will also detect your credentials as environment variables if you have set them. In fact, if both exist, the environment variable values take precedence.

You can run the configure command without flags, invoking it to prompt you for your credential values, or you can supply the values inline using the username and access key flags.

Inline Example
$ saucectl configureDon't have an account? Signup here:https://bit.ly/saucectl-signup
Already have an account? Get your username and access key here:https://app.saucelabs.com/user-settings
? SauceLabs username tester.ninja? SauceLabs access key 2a4a9x11-56b7-4d83-8f6o-b601bg67555e
You're all set!
Interactive Example
$ saucectl configure -u tester.ninja -a 2a4a9x11-56b7-4d83-8f6o-b601bg67555eYou're all set!

--accessKey <string>#

| REQUIRED | STRING |

The authentication access key for the Sauce Labs user account interacting with saucectl.

Shorthand: -a <string>


--username <string>#

| REQUIRED | STRING |

The valid Sauce Labs user account that will be interacting with saucectl.

Shorthand: -u <string>


$ saucectl run [flags]#

Executes tests according to the environment, framework, and test suite specifications defined in the configuration file.

saucectl run

--artifacts.download.directory <path>#

| OPTIONAL | PATH |

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.

saucectl run --artifacts.download.directory ./artifacts

--artifacts.download.match [list]#

| OPTIONAL | STRING/LIST |

Specifies which artifacts to download based on whether they match the name or file type pattern provided. Supports the wildcard character *.

saucectl run --artifacts.download.match console.log,another.log

--artifacts.download.when <string>#

| OPTIONAL | STRING |

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.
saucectl run --artifacts.download.when always

--build <string>#

| OPTIONAL | STRING | VIRTUAL ONLY |

Associates the tests with a build. This flag is not yet supported for mobile real device tests.

saucectl run --build myBuildID

--concurrency <int>#

| OPTIONAL | INTEGER |

Sets the maximum number of suites to execute at the same time. If the test defines more suites than the max, excess suites are queued and run in order as each suite completes.

Shorthand: -ccy

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 <path>#

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


--env <key=value>#

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

--region <string>#

| 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 <string>

saucectl run --region use-west-1

--select-suite <string>#

| OPTIONAL | STRING |

Specifies a test suite to execute by name.

saucectl run --select-suite <suite_name>
Formerly --suite <string>

Versions of saucectl before v0.52.4 use the flag --suite instead.


--tags <tag1,tag2,...>#

| OPTIONAL | LIST | VIRTUAL ONLY |

A keyword that may help you distinguish the test on Sauce Labs, and also helps you apply filters to easily isolate tests based on metrics that are meaningful to you. This flag is not yet supported for mobile real device tests.

saucectl run --tags e2e,team2

--timeout <duration>#

| OPTIONAL | DURATION |

Sets a limit (in seconds or minutes) for how long saucectl can run this test (no limit by default).

saucectl run --timeout 10ssaucectl run --timeout 30m

--tunnel-name <string>#

| OPTIONAL | STRING | Sauce Cloud only |

Specifies an active Sauce Connect tunnel to establish a secure connection to run this test on Sauce Labs.

note

Replaces the former --tunnel-id flag, which is deprecated.

saucectl run --tunnel-name <tunnel-name>

--tunnel-owner <string>#

| OPTIONAL | STRING | Sauce Cloud only |

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 flag, which is deprecated.

saucectl run --tunnel-owner <tunnel-owner-username>

--dry-run#

| OPTIONAL | BOOLEAN | Sauce Cloud only |

Simulate a test run without actually running any tests. This flag does not require a value; including it inline sets it to true.

saucectl run --dry-run

--verbose#

| OPTIONAL | BOOLEAN |

Enables detailed output during the test run in order to facilitate troubleshooting potential authentication, connection, and/or container issues. This flag does not require a value; including it inline sets it to true.

saucectl run --verbose

$ saucectl completion#

Allows you to generate a completion script for bash, zsh, fish and powershell shells.

bash#

Linux#

saucectl completion bash > /etc/bash_completion.d/saucectl

macOS#

saucectl completion bash > /usr/local/etc/bash_completion.d/saucectl

zsh#

If shell completion is not already enabled in your environment, enable it by executing the following once:

$ echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions for each session, execute once:

saucectl completion zsh > "${fpath[1]}/_saucectl"

Start a new shell to apply this setup.

fish#

saucectl completion fish | source

To load completions for each session, execute once:

saucectl completion fish > ~/.config/fish/completions/saucectl.fish

PowerShell#

saucectl completion powershell | Out-String | Invoke-Expression

To load completions for every new session, run the following and then source this file from your Powershell profile:

saucectl completion powershell > saucectl.ps1