Cypress on Sauce Labs

This page provides a walkthrough on how to run Cypress tests locally and on Sauce Labs.

What You'll Need#

Configure saucectl#

Before you begin running cypress tests, you must configure saucectl if you plan to view test results on the Sauce Labs dashboard or running tests on the Sauce Labs VMs:

  1. Configure your Sauce Labs credentials:

    • via system environment variables:

      bash example
      export SAUCE_USERNAME=<your sauce labs username>
      export SAUCE_ACCESS_KEY=<your sauce labs access key>
    • via saucectl configure:

      saucectl configure

      This command generates a credentials.yml file:

      example credentials.yml
      username: <your saucelabs username>
      accessKey: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      source: saucectl configure
      Do NOT commit credentials.yml

      It should go without saying, but do not publicly expose your credentials.yml file over the internet. Make sure you add this file to your .gitignore file, as you should only use it locally.

  2. Create the saucectl configuration:

    saucectl new
  3. Choose the cypress framework. This command generates the default cypress directory, the cypress.json file, and an example cypress test:

    INF Start New Command
    Choose a framework:
    โฏ Cypress
    Want to use your existing Cypress tests?

    If you have existing cypress tests, saucectl prompts you to potentially overwriting the cypress directory and the cypress.json file.

    If you want to edit the configuration manually select "No" and visit the configuration documentation for more details.

  4. Choose a Sauce Labs data center location:

    INF Start New Command
    Choose a framework: Cypress
    Choose the sauce labs region:
    โฏ us-west-1

Run Tests Locally#

The following steps outline how to run your cypress tests on your local machine with the containerized solution, Testrunner Toolkit:

  1. Run your cypress tests using docker mode by modifying config.yml:

    mode: docker


    - name: saucy test
    mode: docker

    The test results display in the console like so:

    9:49AM INF Running version 0.23.2
    9:49AM INF Reading config file config=.sauce/config.yml
    9:49AM INF Starting local runner
    9:49AM INF Setting up test environment
    9:49AM INF File mounted from=./tests/ to=/home/seluser/tests
    9:49AM INF Using credentials from environment variables
    9:49AM INF Starting tests
    > sauce-cypress-runner@0.0.0 test /home/seluser
    > ./bin/cypress
    It looks like this is your first time using Cypress: 4.9.0
    [18:49:28] Verifying Cypress can run /home/seluser/.cache/Cypress/4.9.0/Cypress [started]
    [18:49:33] Verified Cypress! /home/seluser/.cache/Cypress/4.9.0/Cypress [title changed]
    [18:49:33] Verified Cypress! /home/seluser/.cache/Cypress/4.9.0/Cypress [completed]
    Opening Cypress...
    (Run Starting)

    You can also troubleshoot any issues with the --verbose flag.

  2. A Sauce Labs job link appears in the console where you can verify the results in the Sauce Labs dashboard:

    Preparing assets for tests/home.tree.test.js
    Open job details page:

Run Tests on Sauce Labs#

The following steps outline how to run your cypress tests using Sauce Labs virtual machines:

  1. Run your cypress tests with the following saucectl setting:

    mode: sauce


    - name: saucy test
    mode: sauce

    For more information regarding the saucectl parameters, including how to increase your VM concurrency, please visit the configuration documentation.

  2. Watch test runs in real-time, or verify the results in the Sauce Labs dashboard:

    Cypress Test Results
Running Tests with a Local App

If you plan to run your cypress tests with either of the following scenarios:

  • A localhost app running on your host machine
  • An app running locally in a CI pipeline
  • An app running on a local app server in a private network

Please review the following documentation section for further details.

Additional Resources#

Below are some additional topics related to using Cypress with Sauce Labs.

Configuration Details#

Please visit the Configuration page to learn more about config.yml and the specific fields and properties:

Running in CI#

Please visit our CI integrations page for more information about how to run your tests in the following CI platforms:

Last updated on by Tian Feng