saucectl command line tool orchestrates the communication between Sauce Labs and your test framework.
- A Sauce Labs account (if you don't have one, start a free trial)
- Know which test framework and browser versions you plan to run tests against
- Docker, if you plan to run tests locally
Ensure the Docker daemon is running (e.g.,
docker info works in your terminal / command prompt)
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:
Browser support depends on the chosen test framework.
You can install
saucectl using any of the following methods:
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.
If you would like to inspect the content of our one line installer, download it, have a look, and execute it:
Are you using mingw?
Mingw on Windows is known to interfere with the interactive
saucectl commands, so Windows users should use
powershell when interacting with
Your Sauce Labs
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
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.
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.
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.,
- a framework directory (e.g.,
cypress) and other relevant files (e.g.,
- an example test for the chosen framework (e.g.,
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.
- Run the following command to generate a config file:saucectl new
- At the prompt, specify your framework:? Choose a framework:❯ CypressPlaywrightPuppeteerTestCafe
- Specify your Sauce Labs data center at the next prompt:? Choose a framework: Cypress? Choose the sauce labs region:❯ us-west-1eu-central-1
The configuration script confirms your setup and prompts you to execute the
saucectl run command to begin testing.
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 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:
Once the test completes, you can view the test assets when you log into your Sauce Labs dashboard.