Skip to main content

Using the 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. saucectl performs the underlying business logic to access the tests in your existing framework, runs them in the Sauce Labs Cloud, then securely transmits the test assets to the Sauce Labs platform, where you can review, share, and evaluate your test outcomes at scale.

What You'll Need​

System Requirements​

Supported OS:

  • Windows 10 / Windows 11
  • macOS 10.15+
  • Linux

Supported Frameworks and Browsers​

Below are the frameworks supported.

Cypress on Sauce Docs

Installing saucectl​

saucectl binaries are attached to GitHub releases.

Following is a list of saucectl installation options that are common across different development environments.

Requires Node.js 16 or higher and npm 8 or higher.
Using NPM
npm install -g saucectl
Are you using mingw?

Mingw on Windows is known to interfere with the interactive saucectl commands, so Windows users should use cmd or powershell when interacting with saucectl.

Updating saucectl​

To ensure you have access to the most current feature set of saucectl, keep your installation up to date by periodically upgrading to the latest release.

To do this, run the same command you used to download saucectl. If you originally installed saucectl using npm, for example, you'd run npm update -g saucectl.

Next Steps​

Once you've got saucectl installed, you can customize your configurations based on your testing objectives. The following sections offer some common use cases.

Associate Your Credentials​

Your SAUCE_USERNAME and SAUCE_ACCESS_KEY (available on your User Settings page) are required to run tests through saucectl. You can pass your credentials to saucectl via several different methods:

  • Use the saucectl configure CLI command to create a credentials.yml file from which saucectl can automatically pull your credentials.
  • Set your credentials as environment variables that saucectl can access at runtime.
  • Manually enter your credentials as options in the saucectl run command.
Credentials Order of Preference

If you set your credentials using more than one of the methods above, saucectl will apply the values in the following order or preference:

  1. Environment Variables
  2. saucectl run command
  3. credentials.yml file

Check Out Your Framework Demo Repo​

saucectl provides working samples for each of its supported frameworks, so you can quickly run a sample test, or use the project as a template for your own tests.

Configure saucectl for your Tests​

If you already have tests in the framework of your choice, you can use the saucectl init command to generate a config.yml file specifying all the relevant options for your test. See the framework-specific YAML Configuration documentation for a complete reference of all available properties for your framework:

Run Your Tests​

When you are ready to run your tests, you can do so using the saucectl run command. Typically, if you have set all of your configuration properties in your config.yml file, you need only execute the command itself, with no options. However, most of the properties available through the file are also available as runtime options you can set at the command line.

Command Line Values Prioritized

If you set conflicting configuration values in the config.yml file and as saucectl run command options, the values in set in the run command are applied.

The CLI output includes a Results table. The Attempts column in the table displays the number of times a test suite was run, which can be configured with the Retries property in your YAML specification file.

View Your Test Results in Sauce Labs​

After tests complete, saucectl uploads test assets such as logs, test results, screenshots, and videos to your Sauce Labs account, as long as they are in the __assets__ directory of your project root. Some frameworks automatically place assets in the correct directory, but other frameworks may require you to manually set the location.

The CLI output includes a link to the job test results page in Sauce Labs:

Open job details page: https://app.saucelabs.com/tests/<job-number>
Media Assets Not Viewable in UI

Any screenshots and video recorded during the test execution and uploaded to Sauce Labs are not currently viewable in the Sauce Labs UI, but can be accessed and downloaded through the Job Assets API endpoints. Alternatively, you can automatically download your test assets locally using the artifacts parameter in your config file.