Installing saucectl

The saucectl command line tool orchestrates the communication between Sauce Labs and your test framework.

What You'll Need#


Ensure the Docker daemon is running (e.g., docker info works in your terminal / command prompt)

System Requirements#

You can run saucectl locally via Docker or remotely via the Sauce Labs cloud, so system requirements vary depending on your intention.

As a rule of thumb, if you are planning to run in Docker, matching the Docker installation requirements is likely adequate. Please use the reference below as a quick reference:

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

Browser support depends on the chosen test framework.

Installing saucectl#

You can install saucectl using any of the following methods:

Using NPM
npm install -g saucectl
SAUCECTL_INSTALL_BINARY= npm install -g saucectl

Use the SAUCECTL_INSTALL_BINARY environment variable to make saucectl available from a known source within your control or if you use npx saucectl to bypass installation.

Using curl
curl -L | bash
Using Homebrew (macOS)
brew tap saucelabs/saucectl
brew install 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 && \
chmod 700 && \
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.

Associating Your Sauce Labs Account#

Your Sauce Labs username and accessKey are required to post your test results to the Sauce Labs platform. These values are available in the User Settings page in the Sauce Labs app.

You can associate your Sauce Labs account with saucectl either by creating environment variables or by generating a credentials.yml file.

Use credentials.yml#

The saucectl configure command prompts you to manually enter your credentials if it cannot detect relevant environment variables, then generates a credentials.yml file in a .sauce directory in your home folder, which it will reference for subsequent saucectl operations that require authentication.

saucectl configure

Use Environment Variables#

From the root of your project directory, enter the following to set your credentials as environment variables:

Protect your Credentials

Whether you are using environment variables or a credentials file, make sure your authentication data is protected. Use secrets or context variables to mask your environment variables, or add credentials.yml to your gitignore file to ensure your credentials are not exposed in your commits.

Setting up a Working Directory#

This process generates a set of dependencies that allow you to quickly set up a working test. At the end of this process, you will have a root directory with the following assets:

  • a config file (e.g., .sauce/config.yml)
  • a framework directory (e.g., cypress) and other relevant files (e.g., cypress.json)
  • an example test for the chosen framework (e.g., cypress/integration/example.test.js)

If you already have working tests in your framework, you can skip this section and run your tests in order to run your existing tests.

  1. Run the following command to generate a config file:
    saucectl new
  2. At the prompt, specify your framework:
    ? Choose a framework:
    โฏ Cypress
  3. Specify your Sauce Labs data center at the next prompt:
    ? Choose a framework: Cypress
    ? Choose the sauce labs region:
    โฏ us-west-1

The configuration script confirms your setup and prompts you to execute the saucectl run command to begin testing.

Running a Sample Test#

The previous steps have set up a sample test environment that should allow you to run the example test in that directory to ensure saucectl can execute.

saucectl run

saucectl kicks off the example test in the framework directory you have created (e.g., cypress/integration/example.test.js), the output of which may look as follows:

$ saucectl run
13:02:33 INF Running version 0.33.1
13:02:33 INF Reading config file config=.sauce/config.yml
13:02:33 INF Ignoring framework version for Docker, using provided image saucelabs/stt-cypress-mocha-node:v5.6.0 (only applicable to docker mode)
13:02:33 INF Running Cypress in Sauce Labs
13:02:33 INF Project archived. durationMs=1 size=1030
13:02:33 INF Project uploaded. durationMs=864 storageId=09159989-ce03-4e96-b35e-a6aefed0ec10
13:02:34 INF Launching workers. concurrency=2
13:02:34 INF Starting suite. region=us-west-1 suite="saucy test"
13:02:36 INF Suite started. suite="saucy test" url=
13:02:44 INF Suites in progress: 1
13:02:54 INF Suites in progress: 1
13:03:04 INF Suites in progress: 1
13:03:14 INF Suites in progress: 1
13:03:21 INF Suite finished. passed=true suite="saucy test" url=
13:03:21 INF โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
13:03:21 INF All suites have passed!
13:03:21 INF โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
~ $

Once the test completes, you can view the test assets when you log into your Sauce Labs dashboard.

Next Steps#

  • Run a Test: Learn how to run tests using TestRunner.
  • saucectl Syntax Ref: Review the syntax for saucectl commands and learn how to adjust for different testing scenarios.
Last updated on by Nancy Sweeney