> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# saucelabs/saucectl-run

saucectl is a command line interface that orchestrates the relationship between
your tests in your framework, and the rich parallelization, test history
filtering, and analytics of Sauce Labs.

Usage requires a Sauce Labs account.


## Commands

### saucectl-run

This command fetches saucectl binary and then execute "saucectl run".

Note: A Sauce Labs account is required. You must set Username and Access Key
credentials either through the env variables SAUCE_USERNAME and
SAUCE_ACCESS_KEY or using orb parameters in order to execute the command.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `async` | boolean | false | Launches tests without awaiting outcomes; operates in a fire-and-forget manner. |
| `ccy` | string |  | Sets the concurrency to be used for the run. |
| `config-file` | string | .sauce/config.yml | Configuration file to use with saucectl. |
| `env` | string |  | Environment variables to pass to saucectl. |
| `region` | string |  | Specifies the Sauce Labs data center through which tests will run. Valid values are us-west-1 or eu-central-1. |
| `retries` | string |  | Sets the number of retries to do for the run. |
| `sauce-access-key` | string |  | Sauce Labs account's access key. |
| `sauce-username` | string |  | Sauce Labs account's username. |
| `saucectl-version` | string | latest | Version of saucectl to use. Example: v0.25.1. |
| `sauceignore` | string |  | Path to .sauceignore file. |
| `select-suite` | string |  | Suite to be tested. |
| `show-console-log` | boolean | false | Show console log when suite succeed. |
| `test-env-silent` | boolean | false | Skips the test environment announcement. |
| `timeout` | string |  | Test timeout in seconds. |
| `tunnel-name` | string |  | Sets the sauce-connect tunnel ID to be used for the run. |
| `tunnel-owner` | string |  | Sets the sauce-connect tunnel parent to be used for the run. |
| `tunnel-timeout` | string |  | How long to wait for the specified tunnel to be ready. Supports duration values like '10s', '30m' etc. |
| `working-directory` | string |  | Change directory before running saucectl. |

## Examples

### run_on_sauce

This example illustrates how to execute your tests in Sauce Labs through
saucectl.

Note: A Sauce Labs account is required. You must set Username and Access Key
credentials either through the env variables SAUCE_USERNAME and
SAUCE_ACCESS_KEY or using orb parameters in order to execute the command.


```yaml
version: '2.1'
orbs:
  saucectl: saucelabs/saucectl-run@3.0.0
jobs:
  run_saucectl:
    docker:
      - image: cimg/node:lts
    steps:
      - checkout
      - saucectl/saucectl-run
workflows:
  test_on_sauce:
    jobs:
      - run_saucectl
```