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 (either in the Sauce Labs Cloud or locally in a Docker image), 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

Since you can run saucectl locally via Docker or remotely via the Sauce Labs cloud, system requirements vary depending on your intention. The following reference serves as a general guide:

  • OS: 10.14+ (Mojave, Catalina, or Big Sur)
  • Docker: Desktop

Supported Frameworks and Browsers

Sauce Labs Cloud

Below are the frameworks supported on the Sauce Labs Cloud.

Docker Runner

Below are the frameworks supported on the Docker Runner. Browser support for each framework is based on the Sauce Labs Docker images provided in the saucectl installation. Each Docker image tag is the latest image that supports the specific framework version, as detailed in the available release notes.

Cypress on Sauce Docs

Browser support for each framework is based on the Sauce Labs docker images provided in the saucectl installation. Each Docker image tag is the latest image that supports the specific framework version, as detailed in the available release notes.

Installing saucectl

saucectl binaries are attached to GitHub releases.

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

Using NPM
npm install -g saucectl

If you would like to inspect the content of our one line installer, download it, have a look, and execute it:

curl -fsSL -o get_saucectl.sh https://saucelabs.github.io/saucectl/install && \
chmod 700 get_saucectl.sh && \
sudo ./get_saucectl.sh -b /usr/local/bin
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.

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.