Skip to main content

Running Tests

This page details the different options for using the saucectl run command to execute your tests in the framework of your choice.

  • Run tests locally with Docker and send results to Sauce Labs
  • Run tests remotely on Sauce Labs virtual machines
  • Run tests against a local app server / app running on localhost

saucectl allows you to configure your test mode for your entire project or specify the mode at the individual test suite level. See the mode configuration property description for more information.

What You'll Need#

Test Locally on Docker#

Testing in your local environment with the containerized solution allows you to accelerate test execution in CI and results in a smaller bundle transmission to the Sauce Labs cloud.

Set mode to Docker#

saucectl runs on Sauce Labs by default. To run any of your tests locally, set either the default mode or the suite mode to docker in your config.yml file, as shown in the following examples:

defaults:  mode: docker


suites:  - name: saucy test    mode: docker

Specify a Docker Image#

saucectl can provide a default image to run your tests, or you can specify a Docker image in your .sauce/config.yml, as shown in the following example:

docker:  image: saucelabs/stt-cypress-mocha-node:v5.6.0

Refer to the framework version support matrix for a list of framework-specific images.

Transfer Test Files to the Container#

The configuration field: fileTransfer, instructs saucectl how to copy the test files into the docker container. There are currently two choices mount or copy. Refer to the fileTransfer property description for further detals.

docker:  fileTransfer: mount # Defaults to `mount`. Choose between mount|copy.  image: saucelabs/stt-cypress-mocha-node:v5.6.0

Test on Sauce Labs#

Cross-Browser Tests#

supported frameworks: Cypress

When you run tests on Sauce Labs VMs you have access to a wide range of OS + browser combinations. In order to test against multiple different browsers, you can indicate the desired combinations in the suites > browser field:

suites:  # Chrome  - name: "Swag Labs Login Chrome"    browser: "chrome"    platformName: "Windows 10"    screenResolution: "1400x1050"    config:      testFiles: [ "**/login.*" ]  # MicrosoftEdge  - name: "Swag Labs Login MicrosoftEdge"    browser: "microsoftedge"    platformName: "Windows 10"    screenResolution: "1400x1050"    config:      testFiles: [ "**/login.*" ] # Firefox   - name: "Swag Labs Login Firefox"     browser: "firefox"     platformName: "Windows 10"     screenResolution: "1400x1050"     config:       testFiles: [ "**/login.*" ]

For full examples, please visit this repository

Using Sauce Connect#

If you're running tests on Sauce Labs VMs, but the site under test is protected behind strict network security/policies, you can utilize Sauce Connect Proxy to circumvent the problem.

You can use the --tunnel-name flag with saucectl in order to use an existing Sauce Connect tunnel with your test session:

saucectl run --tunnel-name <tunnel-name>

For more information on how to use the --tunnel-name flag, please visit the CLI Reference.

To enable Sauce Connect Proxy in the config.yml, use the tunnel field:

sauce:  concurrency: 3  tunnel:    name: sauce-ci-tunnel  region: us-west-1

For more information regarding how to install, setup, and configure Sauce Connect Proxy, please visit the Sauce Connect Proxy documentation

Analyze 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:<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.

Quick demo#

saucectl Demo

Run Tests Against a Local App#

If you plan to run tests against a local app server / app running on localhost (either on your host machine or in a CI pipeline) there are specific workflows you must follow.

Need to Access Custom Node Modules?

If you have third party, or custom modules that are required test dependencies, you can utilize the npm field in your config.yml in order to include those packages during test execution. Refer to the syntax reference for further details.

Run Tests in Docker Mode and Send Results to Sauce Labs#

Set the default or suite-specific mode in config.yml to docker:

defaults:  mode: docker


suites:  - name: saucy test    mode: docker

Ensure the docker container can access the local app server (e.g. localhost:<port>/) from your host machine. After the tests complete the results upload to the Sauce Labs results dashboard.

Run Tests on Sauce Labs with Sauce Connect#

If you wish to test the app running on a local app server with Sauce Labs VMs:

  • Download and launch Sauce Connect
  • Specify the tunnel to use when running your tests (either in the config.yml tunnel property or using the --tunnel-name flag with the saucectl run command).
Working Example

Here is a working example of this use case using Sauce Connect and GitHub Actions.

Further Details

Please see Using Sauce Connect for further details.

Automation Framework Examples#

The examples here show how Pipeline testing can be used. Try them and find your own use cases.

Every Testrunner image comes with a preconfigured setup that allows you to focus on writing tests instead of tweaking with the configurations. Our initial testrunner flavors come either with Cypress, Playwright, or TestCafe as an automation framework.

Below are example snippets in the following frameworks: Cypress, Playwright, and TestCafe.

context('Actions', () => {        beforeEach(() => {            cy.visit('')        })        it('.type() - type into a DOM element', () => {            //            cy.get('.action-email')                .type('').should('have.value', '')        })    })