Configuring Your Chrome DevTools Recordings

saucectl relies on a YAML specification file to determine exactly which recordings to replay and how. To customize saucectl to replay your Chrome DevTools Recordings, simply modify the properties of the YAML file accordingly. This page defines each of the configuration properties specific to running Chrome DevTools recordings.

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

View on GitHub

Each of the properties supported for replaying Chrome DevTools recordings 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: puppeteer-replay

`showConsoleLog`

| OPTIONAL | BOOLEAN |

Controls whether the contents of console.log are always shown in the local output of saucectl. By default (false), console.log is only shown for failed suites.

showConsoleLog: true

`defaults`

| OPTIONAL | OBJECT |

Specifies any default settings for the project.

defaults:
  timeout: 15m

`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).

defaults:
  timeout: 15m

`sauce`

| OPTIONAL | OBJECT |

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

sauce:
  region: us-west-1
  metadata:
    tags:
      - e2e
      - release team
      - other tag
    build: Release $CI_COMMIT_SHORT_SHA
  concurrency: 10

`region`

| OPTIONAL | STRING/ENUM |

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

note

If you do not specify a region in your config file, you must set it when running your command with the --region flag.

sauce:
  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 Jobs based on metrics that are meaningful to you, as shown in the following example:

sauce:
  metadata:
    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 config defines more suites than the max, excess suites are queued and run in order as each suite completes.

caution

Set this value to equal or less than your Sauce Labs concurrency allowance, as setting a higher value may result in jobs dropped by the server.

sauce:
  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. For more settings, you can refer to passThreshold.

sauce:
  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, and then provide the name and owner (if applicable) in this property.

sauce:
  tunnel:
    name: your_tunnel_name
    owner: tunnel_owner_username

caution

Only certain HTTP(S) ports are proxied by the tunnel.

`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 job 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

`timeout`

| OPTIONAL | DURATION |

How long to wait for the specified tunnel to be ready. Supports duration values like '10s', '30m' etc. (default: 30s)

sauce:
  tunnel:
    name: your_tunnel_name
    timeout: 30s

`visibility`

| OPTIONAL | STRING |

Sets the visibility level of Jobs on Sauce Labs. If unspecified or empty, team visibility will be applied. Valid values are:

public: Accessible to everyone.
public restricted: Share your job's results page and video, but keeps the logs only for you.
share: Only accessible to people with a valid link.
team: (Default) Only accessible to people under the same root account as you.
private: Only you (the owner) will be able to view assets and test results page.

sauce:
  visibility: private

`launchOrder`

| OPTIONAL | STRING |

Specifies the execution order for your test suites. When set to fail rate, test suites with the highest failure rate will execute first. If unspecified, test suites will execute in the order in which they are written in the configuration file.

sauce:
  launchOrder: fail rate

`reporters`

| OPTIONAL | OBJECT |

Configures additional reporting capabilities provided by saucectl.

reporters:
  json:
    enabled: true
    filename: saucectl-report.json
    webhookURL: https://my-webhook-url

`spotlight`

| OPTIONAL | OBJECT |

The spotlight reporter highlights failed or otherwise interesting jobs. It may include an excerpt of failed tests or other information that may be useful for troubleshooting.

reporters:
  spotlight:
    enabled: true

`json`

| OPTIONAL | OBJECT |

The JSON reporter gathers Job results and combines them into a single report.

reporters:
  json:
    enabled: true
    filename: saucectl-report.json
    webhookURL: https://my-webhook-url

`enabled`

| OPTIONAL | BOOLEAN |

Toggles the reporter on/off.

reporters:
  json:
    enabled: true

`webhookURL`

| OPTIONAL | STRING |

The JSON reporter gathers Job results, combines them into a single report and sends an HTTP POST request with the JSON payload to the specified webhook URL.

reporters:
  json:
    webhookURL: https://my-webhook-url

`filename`

| OPTIONAL | STRING |

Specifies the report filename. Defaults to "saucectl-report.json".

reporters:
  json:
    filename: saucectl-report.json

`artifacts`

| OPTIONAL | OBJECT |

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

artifacts:
  cleanup: true
  download:
    when: always
    match:
      - "*"
    directory: ./artifacts/

`cleanup`

| OPTIONAL | BOOLEAN |

When set to true, all contents of the specified download directory are deleted before downloading new artifacts.

artifacts:
  cleanup: true

`retain`

| OPTIONAL | OBJECT |

Define directories to archive and retain as a test asset at the end of a test run. Archived test assets can be downloaded automatically using the download configuration, via the REST API, or through the test details page.

artifacts:
  retain:
    source-directory: destination-archive.zip
  download:
    when: always
    match:
      - destination-archive.zip
    directory: ./artifacts/

note

The source and destination will be relative to the rootDir defined in your configuration.

note

The destination archive must have a .zip file extension.

`download`

| OPTIONAL | OBJECT |

Specifies the settings related to downloading artifacts.

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

artifacts:
  download:
    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).

artifacts:
  download:
    match:
      - "*.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. The name of the subdirectory will match the suite name. If a directory with the same name already exists, the new one will be suffixed by a serial number.

artifacts:
  download:
    directory: ./artifacts/

`allAttempts`

| OPTIONAL | BOOLEAN |

If you have your tests configured with retries, you can set this option to true to download artifacts for every attempt. Otherwise, only artifacts of the last attempt will be downloaded.

artifacts:
  download:
    match:
      - console.log
    when: always
    allAttempts: true
    directory: ./artifacts/

`suites`

| REQUIRED | OBJECT |

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

suites:
  - name: "getting some coffee"
    recordings: [ "recordings/coffee-cart.json" ]
    platform: "Windows 11"
    timeout: 5m

`name`

| REQUIRED | STRING |

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

suites:
  - name: "saucy test"

`platform`

| OPTIONAL | STRING |

A specific operating system and version on which to run the specified recordings. Defaults to a platform that is supported by saucectl.

suites:
  - name: "getting some coffee"
    platform: "Windows 11"

`recordings`

| REQUIRED | STRING/ARRAY |

One or more paths to the Chrome DevTools JSON recordings to run for this suite. Regex values are supported to indicate all files of a certain type or in a certain directory, etc.

suites:
  - name: "getting some coffee"
    recordings:
      - "recordings/*.json"

`browserName`

| OPTIONAL | STRING |

The name of the browser in which to run this test suite. Defaults to googlechrome, which is currently the only supported browser.

suites:
  - name: "getting some coffee"
    browserName: "googlechrome"

`browserVersion`

| OPTIONAL | STRING |

The version of the browser in which to run this suite. Defaults to latest.

suites:
  - name: "getting some coffee"
    browserVersion: "latest"

`timeout`

| OPTIONAL | DURATION |

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

When the suite reaches the timeout limit, its status is set to '?' in the CLI. This does not reflect the actual status of the job in the Sauce Labs web UI or API.

note

Setting 0 reverts to the value set in defaults.

suites:
  - name: "getting some coffee"
    timeout: 15m

`passThreshold`

| OPTIONAL | INTEGER |

Specifies the minimum number of successful attempts for a suite to be considered as passed. It should be used along with retries.

note

For example, setting retries to 3 and passThreshold to 2. The max attempt would be 4 times. If the test passed twice, it'd stop and be marked as passed. Otherwise, it'd be marked as failed.

sauce:
  retries: 3
suite:
  - name: My Saucy Test
    passThreshold: 2

Setting an Alternative Configuration File​

Example Configuration​

apiVersion​

kind​

showConsoleLog​

defaults​

timeout​

sauce​

region​

metadata​

concurrency​

retries​

tunnel​

name​

owner​

timeout​

visibility​

launchOrder​

reporters​

spotlight​

json​

enabled​

webhookURL​

filename​

artifacts​

cleanup​

retain​

download​

when​

match​

directory​

allAttempts​

suites​

name​

platform​

recordings​

browserName​

browserVersion​

timeout​

passThreshold​

Setting an Alternative Configuration File

Example Configuration

`apiVersion`

`kind`

`showConsoleLog`

`defaults`

`timeout`

`sauce`

`region`

`metadata`

`concurrency`

`retries`

`tunnel`

`name`

`owner`

`timeout`

`visibility`

`launchOrder`

`reporters`

`spotlight`

`json`

`enabled`

`webhookURL`

`filename`

`artifacts`

`cleanup`

`retain`

`download`

`when`

`match`

`directory`

`allAttempts`

`suites`

`name`

`platform`

`recordings`

`browserName`

`browserVersion`

`timeout`

`passThreshold`