Skip to main content

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

Each of the properties supported for running Playwright 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: puppeteer-replay

showConsoleLog

| OPTIONAL | BOOLEAN |

Show the contents of the remote console.log as local output. By default, the contents of console.log are only displayed locally on failure.

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:
name: Testing Replay Support
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.

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:
name: Testing Replay 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 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.

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

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

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

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

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/

notifications

| OPTIONAL | OBJECT |

Specifies how to set up automatic job result alerts.

notifications:
slack:
channels:
- "replay-results"
send: always

slack

| OPTIONAL | OBJECT |

Specifies the settings related to sending tests result notifications through Slack. See Slack Integration for information about integrating your Sauce Labs account with your Slack workspace.

notifications:
slack:
channels:
- "saucectl-pw-tests"
send: always

channels

| OPTIONAL | STRING/ARRAY |

The set of Slack channels to which the test result notifications are to be sent.

notifications:
slack:
channels:
- "saucectl-results"
- "playwright-team"

send

| OPTIONAL | STRING |

Specifies when and under what circumstances to send notifications to specified Slack channels. Valid values are:

  • always: Send notifications for all test results.
  • never: Do not send any test result notifications.
  • pass: Send notifications for passing suites only.
  • fail: Send notifications for failed suites only.
notifications:
slack:
send: always

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, potentially overriding the default project timeout setting.

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