Using the saucectl CLI | Sauce Labs Documentation (2024)

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​

• A Sauce Labs account (Log in or sign up for a free trial license)
• Your Sauce Labs Username and Access Key
• Know which test framework and browser versions you plan to run tests against

System Requirements​

Supported OS:

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

Supported Frameworks and Browsers​

Below are the frameworks supported.

Installing saucectl​

saucectl binaries are attached to GitHub releases.

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

npm install -g 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.

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.

• Cypress Demo
• Playwright Demo
• Cucumber.js with Playwright Demo
• TestCafe Demo
• Replay Demo
• Espresso Demo
• XCUITest Demo

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:

• Cypress YAML
• Playwright YAML
• Cucumber.js with Playwright YAML
• TestCafe YAML
• Replay YAML
• Espresso YAML
• XCUITest YAML

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.

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>