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

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

We provide a set of predefined environment variables for each suite. They include basic information about your account or a SauceLabs region you use to run tests. However, if you specify those variables in your configuration, we won't inject the default value into them.

Environment variableExample valueDescription
SAUCE_USERNAMEawesome.saucerUsername of the account triggering Sauce Orchestrate job
SAUCE_ACCESS_KEY0039e1dc-c1bf-4006-bc99-ab5672fb2f8cAccess key for the account triggering Sauce Orchestrate job
SAUCE_ONDEMAND_URLhttps://ondemand.us-west-1.saucelabs.com/wd/hubUrl for the closest OnDemand Data Center endpoint
SAUCE_REGIONus-west-1Name of the closest SauceLabs region
SAUCE_REST_ENDPOINThttps://api.us-west-1.saucelabs.com/Url for the closest SauceLabs REST API
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:

  1. --env flag
  2. root-level environment variables
  3. suite-level environment variables
  4. default environment variables

metadata

| OPTIONAL | OBJECT |

This field's primary use case is for troubleshooting. Unless instructed by a Sauce Labs employee, setting any random values here will serve you no purpose.

suites:
- name: "saucy test"
metadata:
KEY: value

services

| OPTIONAL | ARRAY |

Define service containers that are required to run alongside the main container of the suite. The available configuration options for services are similar to those of the main container.

suites:
- name: "saucy test"
services:
- name: "a service"
image: your-org/your-service-image:0.0.1
imagePullAuth:
user: sauceuser
token: "123"
entrypoint: mvn test
files:
- src: "runsauce.json"
dst: "/workdir/runsauce.json"
env:
KEY: value
resourceProfile: c1m1
note

A service container may not be up and running by the time your main container starts. Please take that into account when writing your tests.

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 Commands

Supported commands:

OperationDescription
Get artifactsGet artifacts/files of the container from a Sauce Orchestrate run.
List containersReturn the list of Sauce Orchestrate containers.
Get logsFetch the logs from an imagerunner run.
Stop a containerStop a running Sauce Orchestrate container.