Skip to main content

saucectl Configuration

This page describes each saucectl configuration option and commands to use when interacting with Sauce Orchestrate. To get started with Sauce Orchestrate, see Getting Started.

Configuration Options

note

Only the saucectl configuration options for Sauce Orchestrate are listed below. For the full list of options, see Using the saucectl CLI.

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 |

Tells saucectl this is a Sauce Orchestrate configuration. imagerunner is the required value for Sauce Orchestrate.

kind: imagerunner

sauce

| OPTIONAL | OBJECT |

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

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

sauce:
region: eu-central-1

concurrency

| OPTIONAL | INTEGER |

Sets the maximum number of suites to run 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.

sauce:
concurrency: 3

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

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

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.

suites:
- name: "saucy test"

workload

| REQUIRED | STRING |

Tell Sauce Orchestrate what kind of entrypoint process you are running. workload is important for security monitoring. Options are webdriver or other. For most configurations webdriver is required.

suites:
- name: "saucy test"
workload: webdriver

resourceProfile

| OPTIONAL | STRING |

Sets the CPU and memory limits for the container. The format for specifying the limits is as follows: <CPU><level><memory><level>.

The larger the level value, the higher the allocated CPU and memory resources. Available options are: c1m1, c2m2, and c3m3. The default value is set to c1m1.

suites:
- name: "saucy test"
resourceProfile: c2m2

image

| REQUIRED | STRING |

The location of your container image. Takes the format [registry]/[image]:[tag].

suites:
- name: "saucy test"
image: saucelabs/sl-demo-docker-primary:0.0.1

imagePullAuth

| OPTIONAL | OBJECT |

The credentials needed to access an image hosted in a private registry. It is highly recommend to not hardcode credentials in your saucectl config. Use environment variables instead.

suites:
- name: "saucy test"
image: saucelabs/sl-demo-docker-primary:0.0.1
imagePullAuth:
user: $DOCKER_USERNAME
token: $DOCKER_PASSWORD

entrypoint

| REQUIRED | STRING |

The command that is executed after the container is ready.

suites:
- name: "saucy test"
image: saucelabs/sl-demo-docker-primary:0.0.1
entrypoint: mvn test

files

| OPTIONAL | ARRAY |

Files to be uploaded onto the container. Can be used for populating test data that your scripts access. src and dst must be an absolute path.

suites:
- name: "saucy test"
image: saucelabs/sl-demo-docker-primary:0.0.1
files:
- src: "runsauce.json"
dst: "/workdir/runsauce.json"

env

| OPTIONAL | ARRAY |

Environment variables to be injected into the container. Can be used for populating secrets used in your tests. These environment variables are not stored anywhere in Sauce Labs.

suites:
- name: "saucy test"
env:
KEY: value
note

Environment variables set with the saucectl --env flag will overwrite those specified in the sauce config file.

The order of precedence is as follows: --env flag > root-level environment variables > suite-level environment variables.

artifacts

| OPTIONAL | ARRAY |

In order for saucectl to download files from the Sauce Orchestrate container two configurations are needed. The first is to tell Orchestrate which files to upload from the container once your entrypoint command finishes.

# declared within your suites definition
suites:
...
artifacts:
- "/workdir/best-practice/target/surefire-reports/*"

Then you must tell saucectl to download the artifacts to your machine.

# declared at the top level of your config.yml
artifacts:
download:
when: always
match:
- "*"
directory: ./artifacts
note

The following limitations are in effect for artifact downloads. They do not apply to files uploaded:

  • Must specify an absolute path (starting at the root /)
  • Max requested volume for parent dir is 10M
  • You can only specify up to 10 paths

cleanup

| OPTIONAL | BOOLEAN |

When set to true, all contents of the specified download directory are cleared before any new artifacts from the current test are downloaded.

artifacts:
cleanup: true

download

| OPTIONAL | OBJECT |

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

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

reporters

| OPTIONAL | OBJECT |

Configures additional reporting capabilities provided by saucectl.

reporters:
json:
enabled: true
filename: saucectl-report.json

json

| OPTIONAL | OBJECT |

The JSON reporter creates a single report of all executed saucectl suites.

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 |

Specifies the webhook URL. When saucectl test is finished, it'll send an HTTP POST with a JSON payload to the configured webhook URL.

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

filename

| OPTIONAL | STRING |

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

reporters:
json:
filename: my-saucectl-report.json

saucectl Commands

The following are some common saucectl commands for interacting with Sauce Orchestrate.

saucectl run

The main command to run a Sauce Orchestrate job. Must be executed at the root level of your project. Your project must contain a configuration file located in .sauce/config.yml.

saucectl run

saucectl imagerunner logs

Get logs of the container from a Sauce Orchestrate run.

saucectl imagerunner logs <runID>

saucectl imagerunner artifacts

Get artifacts/files of the container from a Sauce Orchestrate run. Only the files specified in artifacts configuration are downloaded.

saucectl imagerunner artifacts <runID>