Skip to main content

Configuring your Cypress Tests

saucectl relies on a YAML specification file to determine exactly which tests to run and how to run them. To customize saucectl to run your Cypress tests, simply modify the properties of the YAML file accordingly. This page defines each of the configuration properties specific to running Cypress tests.

Setting an Alternative Configuration File#

By default, saucectl looks for the config.yml file in the .sauce folder of your project root, but you can actually specify a different file, or if you are using multiple frameworks or need to configure different sets of tests to run separately, you may choose to have multiple configuration files that you can direct saucectl to reference as necessary.

Use the following configuration at runtime to direct saucectl to use any configuration file you choose:

saucectl run -c ./path/to/{config-file}.yml
YAML Required

While you can use multiple files of different names or locations to specify your configurations, each file must be a *.yml and follow the saucectl syntax. Our IDE Integrations (e.g. Visual Studio Code) can help you out by validating the YAML files and provide handy suggestions, so make sure to check them out!

Example Configuration#

.sauce/config.yml
loading...

Each of the properties supported for running Cypress tests through saucectl is defined below.

apiVersion#

| REQUIRED | STRING |

Identifies the version of the underlying configuration schema. At this time, v1alpha is the only supported value.

apiVersion: v1alpha

kind#

| REQUIRED | STRING/ENUM |

Specifies which framework is associated with the automation tests configured in this specification.

kind: cypress

showConsoleLog#

| OPTIONAL | BOOLEAN |

Generates the console.log as local output and as a test asset in Sauce Labs for all tests. By default, console.log is only included in results for failed tests.

showConsoleLog: true

defaults#

| OPTIONAL | OBJECT |

Specifies any default settings for the project.

defaults:  mode: sauce  timeout: 15m

mode#

| OPTIONAL | STRING/ENUM |

Instructs saucectl run tests remotely through Sauce Labs (sauce) or locally on docker. You can override this setting for individual suites using the mode setting within the suites object. If not set, the default value is sauce.

  mode: sauce

timeout#

| OPTIONAL | DURATION |

Instructs how long (in ms, s, m, or h) saucectl should wait for each suite to complete. You can override this setting for individual suites using the timeout setting within the suites object. If not set, the default value is 0 (unlimited).

  timeout: 15m

sauce#

| OPTIONAL | OBJECT |

The parent property containing all settings related to how tests are run and identified in the Sauce Labs platform.

sauce:  region: eu-central-1  metadata:    name: Testing Cypress Support    tags:      - e2e      - release team      - other tag    build: Release $CI_COMMIT_SHORT_SHA  concurrency: 10

region#

| OPTIONAL | STRING/ENUM |

Specifies through which Sauce Labs data center tests will run. Valid values are: us-west-1 or eu-central-1.

  region: eu-central-1

metadata#

| OPTIONAL | OBJECT |

The set of properties that allows you to provide additional information about your project that helps you distinguish it in the various environments in which it is used and reviewed, and also helps you apply filters to easily isolate tests based on metrics that are meaningful to you, as shown in the following example:

metadata:  name: Testing Cypress Support  build: RC 10.4.a  tags:    - e2e    - release team    - beta    - featurex

concurrency#

| OPTIONAL | INTEGER |

Sets the maximum number of suites to execute at the same time. If the test defines more suites than the max, excess suites are queued and run in order as each suite completes.

caution

For tests running on Sauce, set this value to equal or less than your Sauce concurrency allowance, as setting a higher value may result in jobs dropped by the server.

  concurrency: 5

Alternatively, you can override the file setting at runtime by setting the concurrency flag as an inline parameter of the saucectl run command:

saucectl run --ccy 5

retries#

| OPTIONAL | INTEGER |

Sets the number of times to retry a failed suite.

  retries: 1

Alternatively, you can override the file setting at runtime by setting the retries flag as an inline parameter of the saucectl run command:

saucectl run --retries 1

tunnel#

| OPTIONAL | OBJECT |

saucectl supports using Sauce Connect to establish a secure connection with Sauce Labs. To do so, launch a tunnel; then provide the name and owner (if applicable) in this property.

sauce:  tunnel:    name: your_tunnel_name    owner: tunnel_owner_username

name#

| OPTIONAL | STRING |

Identifies an active Sauce Connect tunnel to use for secure connectivity to the Sauce Labs cloud.

note

This property replaces the former id property, which is deprecated.

sauce:  tunnel:    name: your_tunnel_name

owner#

| OPTIONAL | STRING |

Identifies the Sauce Labs user who created the specified tunnel, which is required if the user running the tests did not create the tunnel.

note

This property replaces the former parent property, which is deprecated.

sauce:  tunnel:    name: your_tunnel_name    owner: tunnel_owner_username

env#

| OPTIONAL | OBJECT |

A property containing one or more environment variables that are global for all tests suites in this configuration. Expanded environment variables are supported. Values set in this global property will overwrite values set for the same environment variables set at the suite level.

  env:    hello: world    my_var: $MY_VAR
caution

Since environment variables are provided to Cypress directly, avoid using CYPRESS_ as a prefix.


docker#

| OPTIONAL | OBJECT | Docker only |

The set of properties defining the specific Docker image and type your are using, if you are running any tests locally.

docker:  fileTransfer: mount  image: saucelabs/stt-cypress-mocha-node:vX.X.X

fileTransfer#

| OPTIONAL | STRING |

Method in which to transfer test files into the docker container. Valid values are:

  • mount: (Default) Mounts files and folders into the docker container. Changes to these files and folders will be reflected on the host (and vice a versa).
  • copy: Copies files and folders into the docker container. If you run into permission issues, either due to docker or host settings, copy is the advised use case. See the Docker documentation for more about the copy convention.
  fileTransfer: < mount | copy >

image#

| OPTIONAL | STRING |

Specifies which docker image and version to use when running tests. Valid values are in the format: saucelabs/<framework-node>:<vX.X.X>. See Supported Testing Platforms for Docker release notes related to Cypress.

  image: saucelabs/< stt-cypress-mocha-node | stt-playwright-node | stt-testcafe-node >:< vX.X.X >
caution

Avoid using the latest tag for docker images, as advised in this article.


rootDir#

| REQUIRED | OBJECT |

The directory of files that need to be bundled and uploaded for the tests to run. Ignores what is specified in .sauceignore. See Tailoring Your Test File Bundle for more details. The following examples show the different relative options for setting this value.

  rootDir: "./" # Use the current directory
  rootDir: "packages/subpackage" # Some other package from within a monorepo
caution

Only the files contained within rootDir will be available during the tests. Any reference to a file that is not included in rootDir will make the tests fail.


npm#

| OPTIONAL | OBJECT |

A parent property specifying the configuration details for any npm dependencies. Packages listed are installed in the environment prior to your tests executing.

npm:  registry: https://registry.npmjs.org  packages:    lodash: "4.17.20"    "@babel/preset-typescript": "7.12"    "@cypress/react": "^5.0.1"

registry#

| OPTIONAL | STRING |

Specifies the location of the npm registry source. If the registry source is a private address and you are running tests on Sauce Cloud, you can provide access to the registry source using Sauce Connect.

  registry: https://registry.npmjs.org

packages#

| OPTIONAL | OBJECT |

Specifies any NPM packages that are required to run tests and should, therefore, be included in the bundle. See Including Node Dependencies.

  packages:    lodash: "4.17.20"    "@babel/preset-typescript": "7.12"    "@cypress/react": "^5.0.1"

reporters#

| OPTIONAL | OBJECT |

Configures additional reporting capabilities provided by saucectl.

reporters:  junit:    enabled: true    filename: saucectl-report.xml

artifacts#

| OPTIONAL | OBJECT |

Specifies how to manage test artifacts, such as logs, videos, and screenshots.

artifacts:  download:    when: always    match:      - junit.xml    directory: ./artifacts/

download#

| OPTIONAL | OBJECT |

Specifies the settings related to downloading artifacts from tests run by saucectl.

  download:    when: always    match:      - junit.xml    directory: ./artifacts/

when#

| OPTIONAL | STRING |

Specifies when and under what circumstances to download artifacts. Valid values are:

  • always: Always download artifacts.
  • never: Never download artifacts.
  • pass: Download artifacts for passing suites only.
  • fail: Download artifacts for failed suites only.
    when: always

match#

| OPTIONAL | STRING/ARRAY |

Specifies which artifacts to download based on whether they match the name or file type pattern provided. Supports the wildcard character * (use quotes for best parsing results with wildcard).

  match:    - junit.xml    - "*.log"

directory#

| OPTIONAL | STRING |

Specifies the path to the folder location in which to download artifacts. A separate subdirectory is generated in this location for each suite for which artifacts are downloaded.

    directory: ./artifacts/

cypress#

| REQUIRED | OBJECT |

The parent property containing the details specific to the Cypress project.

cypress:  version: 6.6.0  configFile: "cypress.json"

version#

| REQUIRED | STRING |

The version of Cypress that is compatible with the tests defined in this file. See Supported Testing Platforms for the list of Cypress versions supported by saucectl and their compatible test platforms.

  version: 8.6.0

configFile#

| REQUIRED | STRING |

The designated cypress configuration file. saucectl determines related files based on the location of the config file. By default saucectl defers to the test file location defined in cypress.json.

  configFile: "cypress.json"

record#

| OPTIONAL | BOOLEAN |

Determines whether to record your test results in the Cypress dashboard.

  record: true  key: $MY_SECRET_KEY

key#

| OPTIONAL | STRING |

The secret key that grants permission to record your tests in the Cypress dashboard.

  record: true  key: $MY_SECRET_KEY

The record and key fields depend on the cypress "projectId" being set in your cypress.json file because the value of your projectId correlates directly with the value of the key field. See Cypress Project-ID Documentation for details about how to configure/retrieve the cypress projectId or Cypress Record-Key Documentation for details about configuring Record-Key parameters.

note

For additional information regarding cypress configurations, please consult the Cypress documentation.


reporters#

| OPTIONAL | OBJECT |

The set of additional reporters to execute as part of your Cypress tests.

  reporters:    - name: cypress-mochawesome      options:        reportDir: cypress/report        charts: true        reportPageTitle: Cypress running on Sauce
note

In order for your additional reporter to work, it must be compatible with the cypress-multi-reporter plugin, which provides the underlying functionality.


name#

| REQUIRED | STRING |

The name of the reporter to enable, which corresponds to the reporter property in the cypres.json file.

      - name: cypress-mochawesome
note

Some reporters may require you to install dependencies.


options#

| OPTIONAL | OBJECT |

Any relevant settings that are be supported by the specified reporter. These properties correspond to the reporterOptions object in the cypress.json file.

      options:        reportDir: cypress/report        charts: true        reportPageTitle: Cypress running on Sauce

suites#

| REQUIRED | OBJECT |

The set of properties providing details about the test suites to run. May contain multiple suite definitions. See the full example config for an illustration of multiple suite definitions.


name#

| REQUIRED | STRING |

The name of the test suite, which will be reflected in the results and related artifacts.

  - name: "saucy test"

browser#

| REQUIRED | STRING |

The name of the browser in which to run this test suite. Available browser names: chrome, firefox, microsoftedge(only for sauce mode) and electron(only for docker mode).

    browser: "chrome"

browserVersion#

| OPTIONAL | STRING |

The version of the browser to use for this test suite.

    browserVersion: "85.0"

platformName#

| OPTIONAL | STRING | Sauce Cloud only |

A specific operating system and version on which to run the specified browser and test suite. Defaults to a platform that is supported by saucectl for the chosen browser.

    platformName: "Windows 10"

screenResolution#

| OPTIONAL | STRING | Sauce Cloud only |

Specifies a browser window screen resolution, which may be useful if you are attempting to simulate a browser on a particular device type. See Test Configurations for a list of available resolution values.

    screenResolution: "1920x1080"

mode#

| OPTIONAL | STRING |

Specifies whether the individual suite will run on docker or sauce, potentially overriding the default project mode setting.

  mode: "sauce"

config#

| OPTIONAL | OBJECT |

Provides details related to the Cypress test configuration that are relevant for this test suite.

  suites:    - name: "Hello"      browser: "firefox"      platformName: "Windows 10"      config:        env:          hello: world        testFiles: [ "**/*.*" ]

env#

| OPTIONAL | OBJECT |

A property containing one or more environment variables that may be referenced in the tests for this suite. Expanded environment variables are supported. Values set here will be overwritten by values set in the global env property.

  config:    env:      hello: world      my_var: $MY_VAR
caution

Since environment variables are provided to Cypress directly, avoid using CYPRESS_ as a prefix.


testFiles#

| REQUIRED | STRING/ARRAY/REGEX |

One or more paths to the Cypress test files to run for this suite, if not otherwise specified explicitly in cypress.json. Regex values are supported to indicate all files of a certain type or in a certain directory, etc.

      testFiles: [ "**/*.*" ]
note

testFiles must be a regex or a path relative to cypress/integration or the integrationFolder value set in cypress.json.


shard#

| OPTIONAL | STRING |

When sharding is configured, saucectl automatically splits the tests (e.g. by spec) so that they can easily run in parallel. Selectable values: spec to shard by spec file. Remove this field or leave it empty "" for no sharding.

    shard: spec

timeout#

| OPTIONAL | DURATION |

Instructs how long saucectl should wait for the suite to complete, potentially overriding the default project timeout setting.

note

Setting 0 reverts to the value set in defaults.

  timeout: 15m

Advanced Configuration Considerations#

The configuration file is flexible enough to allow for any customizations and definitions that are required for any of the supported frameworks. The following sections describe some of the most common configurations.

Setting up a Proxy#

If you need to go through a proxy server, you can set it through the following variables:

  • HTTP_PROXY: Proxy to use to access HTTP websites
  • HTTPS_PROXY: Proxy to use to access HTTPS websites

Docker Proxy Considerations#

When running in docker-mode, saucectl still must reach the Sauce Labs platform get the latest docker image available or upload the test package to Sauce Cloud, and the docker container needs to access the tested website and Sauce Labs to upload results.

Therefore, you may be required to set the proxy twice, as shown in the following examples:

PS> $Env:HTTP_PROXY=http://my.proxy.org:3128/PS> $Env:HTTPS_PROXY=http://my.proxy.org:3128/PS> saucectl run -e HTTP_PROXY=${Env:HTTP_PROXY} -e HTTPS_PROXY=${Env:HTTPS_PROXY}
$> export HTTP_PROXY=http://my.proxy.org:3128/$> export HTTPS_PROXY=http://my.proxy.org:3128/$> saucectl run -e HTTP_PROXY=${HTTP_PROXY} -e HTTPS_PROXY=${HTTPS_PROXY}

Tailoring Your Test File Bundle#

The saucectl command line bundles your root directory (rootDir parameter of config.yml) and transmits it to the Sauce Labs cloud or your own infrastructure via Docker, then unpacks the bundle and runs the tests. This functionality is partly what allows Sauce Control to operate in a framework-agnostic capacity. However, you can and should manage the inclusion and exclusion of files that get bundled to optimize performance and ensure security.

Excluding Files from the Bundle#

The .sauceignore file allows you to designate certain files to be excluded from bundling.

Add any files that are not direct test dependencies to .sauceignore to reduce the size of your bundle, improve test speed, and protect sensitive information.

Examples of what can be included in .sauceignore:

# .sauceignore
# Ignore node_modulesnode_modules/
# Ignore all log files*.log
# Ignore executables/binaries*.exe*.bin**/*/bin
# Ignore media files*.png*.jpeg*.jpg*.mp4
# Ignore documentation*.rst*.md
# Ignore sensitive datacredentials.yml

Including Node Dependencies#

The default .sauceignore file lists node_modules/ so locally installed node dependencies are excluded from the bundle. If your tests require node dependencies to run, you can either:

Remove "node_modules" from .sauceignore#

Delete or comment out node_modules/ in your .sauceignore file to bundle your node dependencies. For example,

# Do NOT exclude node_modules from bundle# node_modules/

Node dependencies can increase your bundle by potentially hundreds of megabytes, so consider including only the required dependencies rather than the entire node_modules directory. The following sections provide some methods for limiting the scope of dependencies you must include.

Install "devDependencies" Only#

Consider only installing NPM devDependencies if your tests do not require all prod dependencies.

# Only install dev dependenciesnpm install --only=dev
saucectl run
Uninstall Nonessential Dependencies#

If your standard install includes dependencies that aren't needed to run your tests, uninstall them prior to bundling.

# Install node dependenciesnpm ci # or "npm install"
# Remove unneeded dependenciesnpm uninstall appiumnpm uninstall express
saucectl run
Install Essential Dependencies Individually#

If you know that your tests require only specific dependencies, install them individually instead of running npm install or npm ci.

# Install individual dependenciesnpm install cypress-xpathnpm install @cypress/react
saucectl run

Set NPM Packages in config.yml#

You can avoid installing or uninstalling dependencies prior to each bundling operation by defining a default set of NPM packages to install in your sauce configuration file using the npm parameter, as shown in the following example:

npm:  registry: https://registry.npmjs.org  packages:    lodash: "4.17.20"    "@babel/preset-typescript": "7.12"    "@cypress/react": "^5.0.1"