Common Configuration Syntax

Each time you initiate a test session, saucectl reads your configuration file (.sauce/config.yml by default) to determine:

  • which framework you are using;
  • where your tests are located;
  • which tests to run;
  • which devices, operating systems and browsers you are testing against;
  • and many other specifications

This reference document defines each of the parameters that you can set in your configuration file to help saucectl run your tests, your way.

Framework Parameter Sets

Some sets of parameters include settings that vary by framework. In those cases, examples for each framework are provided with links to pages defining the individual settings specific to each framework.

apiVersion#

Description: The version of saucectl you are running.

Type: string

Example:

apiVersion: v1alpha

kind#

Description: The framework of your automation tests. This value is set during the saucectl new setup script based on the value you choose at the command line prompt.

Type: enum Valid values are:

* `cypress`
* `playwright`
* `testcafe`
* `puppeteer`
* `espresso`

Example:

kind: cypress

defaults#

Description: Specifies any default settings for the project.

Type: object

Example:

defaults:
- mode: "sauce"

mode#

Description: Specifies whether tests in the project will run on docker or sauce. You can override this setting for individual suites using the mode setting within the suites object. The default value is sauce.

note

Espresso is supported in sauce mode only.

Type: enum Valid values are: sauce or docker.

Example:

mode: "sauce"

sauce#

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

Type: object

Example:

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#

Description: The Sauce Labs data center through which test will run.

Type: enum Valid values are: us-west-1 or eu-central-1.

Example:

region: eu-central-1

metadata#

Description: The set of parameteres that specify how the tests are grouped and identified in Sauce Labs (i.e. name, tags, build, etc.)

Type: object

Example:

metadata:
name: Testing Cypress Support
tags:
- e2e
- release team
- other tag
build: Release $CI_COMMIT_SHORT_SHA

concurrency#

Description: For test suites running on Sauce Cloud, the maximum number of suites to execute concurrently. This value is limited by your Sauce Labs account settings.

Type: int

Example:

concurrency: 10

tunnel#

Description: Specifies an open Sauce Connect tunnel to use when running tests inside the Sauce cloud. See Sauce Connect for information about finding the correct identifier.

Type: object

Example:

tunnel:
id: your_tunnel_id
parent: parent_owner_of_tunnel # if applicable, specify the owner of the tunnel

docker#

Description: The set of parameters defining the specific Docker image and type your are using. See Supported Docker Frameworks for framework specific release notes.

Type: object

Example:

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

fileTransfer#

Description: Method in which to transfer test files into the docker container. There are two options:

  • mount : Default method; 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 to read more about the copy convention (docker cp | COPY).

Type: string

Example:

fileTransfer: < mount | copy >

image#

Description: Specifies which docker image and version to use when running tests. Valid image values are shown in the example below.

Type: string

Example:

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#

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

Type: object

Examples:

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

npm#

Description: Details specific to the npm configuration. Packages listed are installed in the environment prior to your tests executing.

Type: object

Example:

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

registry#

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

Type: string

Example:

registry: https://registry.npmjs.org

packages#

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

Type: object

Example:

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

artifacts#

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

Type: object

Example:

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

download#

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

Type: object

Example:

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

when#

Description: Specifies when and under what circumstances to download artifacts.

Type: string

Values:

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

Example:

when: always

match#

Description: Allows you to specify particular files or file types to download based on whether they match the name pattern provided. Supports the wildcard character *.

Type: string[]

Example:

match:
- junit.xml
- *.log

directory#

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

Type: string

Example:

directory: ./artifacts/

{framework}#

Description: The set of parameters providing details about the relevant framework. Specific parameters vary for each supported framework. More detail is available on the individual framework configuration pages, links to which are available in each example below.

Type: object

Examples:

See the full Cypress Configuration reference.

.sauce/config.yml
loading...
See full example on GitHub

suites#

Description: The set of parameters providing details about the test suites to run. Each supported framework may include different parameters for each test suite, so refer to the individual framework configuration pages linked in each example below for relevant definitions.

Type: object

Examples:

See the full Cypress Configuration reference.

.sauce/config.yml
loading...
See full example on GitHub

name#

Description: Name of the test suite.

Type: string

Example:

- name: "saucy test"

env#

Description: Field for setting enviornment variables. It supports expanded enviornment variables.

Type: object

Example:

env:
hello: world
my_var: $MY_VAR

browser#

Description: Name of the browser in which the test runs.

Type: string

Example:

browser: "chrome"

browserVersion#

Description: Version of the browser in which the test runs.

Type: string

Example:

browserVersion: "85.0"

platformName#

Description: Operating system on which the browser and test runs. This value is optional and will be defaulted to a sensible platform. Set this value explicitly if you'd like to have greater control over where your tests should run.

Type: string

Example:

platformName: "Windows 10"

screenResolution#

Description: Field where you can change the browser window screen resolution.

Type: string

Example:

screenResolution: "1920x1080"

For all available resolutions please visit Sauce Labs Test Configurations.

mode#

Description: Allows you to specify whether the individual suite will run on docker or sauce, potentially overriding the default project mode setting.

Type: string

Example:

mode: "sauce"

Framework Syntax Reference#

Last updated on by Nancy Sweeney