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.

`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 variable	Example value	Description
`SAUCE_USERNAME`	`awesome.saucer`	Username of the account triggering Sauce Orchestrate job
`SAUCE_ACCESS_KEY`	`0039e1dc-c1bf-4006-bc99-ab5672fb2f8c`	Access key for the account triggering Sauce Orchestrate job
`SAUCE_ONDEMAND_URL`	`https://ondemand.us-west-1.saucelabs.com/wd/hub`	Url for the closest OnDemand Data Center endpoint
`SAUCE_REGION`	`us-west-1`	Name of the closest SauceLabs region
`SAUCE_REST_ENDPOINT`	`https://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:

--env flag
root-level environment variables
suite-level environment variables
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:

Operation	Description
Get artifacts	Get artifacts/files of the container from a Sauce Orchestrate run.
List containers	Return the list of Sauce Orchestrate containers.
Get logs	Fetch the logs from an imagerunner run.
Stop a container	Stop a running Sauce Orchestrate container.

Configuration Options​

apiVersion​

kind​

sauce​

region​

concurrency​

tunnel​

name​

owner​

suites​

name​

workload​

resourceProfile​

image​

imagePullAuth​

entrypoint​

files​

env​

metadata​

services​

artifacts​

cleanup​

download​

when​

match​

directory​

reporters​

json​

enabled​

webhookURL​

filename​

saucectl Commands​

saucectl run​

saucectl imagerunner Commands​

Configuration Options

`apiVersion`

`kind`

`sauce`

`region`

`concurrency`

`tunnel`

`name`

`owner`

`suites`

`name`

`workload`

`resourceProfile`

`image`

`imagePullAuth`

`entrypoint`

`files`

`env`

`metadata`

`services`

`artifacts`

`cleanup`

`download`

`when`

`match`

`directory`

`reporters`

`json`

`enabled`

`webhookURL`

`filename`

saucectl Commands

`saucectl run`

`saucectl imagerunner` Commands