saucectl authoring testcases
Inspect, run, author, and export test cases created with Sauce AI for Test Authoring.
Aliases: testcase, tc
Usage
$ saucectl authoring testcases [command] [flags]
Commands
| Command | Description |
|---|---|
list | List test cases. |
list-tags | List every tag in use across your organization's test cases. |
get | Show a test case, optionally with its recorded steps. |
generate | Author a new test case from a plain-language description. |
generate-status | Show the status of an authoring task, or reattach and wait for it. |
rename | Rename a test case. |
delete | Delete a test case. |
run | Start a run of a test case. |
list-runs | List the runs of a test case. |
get-run | Show a single run with its jobs. |
list-code-targets | List the languages and frameworks a test case can be exported to. |
code | Export a test case as source code. |
All commands also accept the global options, such as --region.
list
List test cases.
Alias: ls
$ saucectl authoring testcases list [flags]
| Flag | Shorthand | Description |
|---|---|---|
| --out | -o | Output format. Options: text (default) and json. |
| --search | None | Case-insensitive substring match on the test case name. |
| --tag | None | Filter by tag (case-sensitive). Repeatable. Returns test cases that have any of the tags. |
| --test-suite-id | None | Filter by test suite ID. Repeatable. Use null for test cases that are not in a suite. |
| --start-date | None | Only test cases created on or after this ISO 8601 date. |
| --end-date | None | Only test cases created on or before this ISO 8601 date. |
| --user-id | None | Filter by the ID of the user who created the test case. |
| --team-id | None | Filter by team ID. |
| --skip | None | Number of results to skip. Default is 0. |
| --limit | None | Maximum number of results to return. Default is 20. Use 0 to return only the total count. |
| --all | None | Return every result, fetching all pages. --limit is ignored. |
saucectl authoring testcases list
saucectl authoring testcases list --search checkout --tag smoke
saucectl authoring testcases list --test-suite-id <test-suite-id> -o json
saucectl authoring testcases list --limit 0
list-tags
List every tag in use across your organization's test cases.
Alias: tags
$ saucectl authoring testcases list-tags [flags]
| Flag | Shorthand | Description |
|---|---|---|
| --out | -o | Output format. Options: text (default) and json. |
saucectl authoring testcases list-tags
get
Show a test case, optionally with the steps recorded in its latest revision.
$ saucectl authoring testcases get <id> [flags]
| Flag | Shorthand | Description |
|---|---|---|
| --out | -o | Output format. Options: text (default) and json. |
| --revision | None | Show this revision instead of the latest. |
| --show-steps | None | Also print the revision's recorded steps. |
saucectl authoring testcases get <test-case-id>
saucectl authoring testcases get <test-case-id> --show-steps
saucectl authoring testcases get <test-case-id> -o json | jq '.revisions[-1].steps'
generate
Author a new test case. You describe the user journey, the starting URL, and a target, and an AI agent drives a real browser or device to work out the steps. The result is saved as a test case.
Authoring is asynchronous. Without --wait, the command prints the task ID and returns. With --wait, it streams each action the agent attempts as it happens. If the wait is interrupted or times out, the task keeps running on Sauce Labs. You can reattach with generate-status.
$ saucectl authoring testcases generate [flags]
| Flag | Shorthand | Description |
|---|---|---|
| --name | None | Required. Name of the new test case, 1 to 255 characters. |
| --intent | None | Required if --intent-file isn't set. Plain-language description of what the test should do, 1 to 20000 characters. Set either --intent or --intent-file. Setting both, or neither, returns an error. |
| --intent-file | None | Required if --intent isn't set. Read the description from a file, or use - to read it from standard input. |
| --target | None | Target capabilities as key=value pairs. See Specify Targets. Exactly one target is required, set with --target or --target-json. |
| --target-json | None | Target capabilities as a JSON object, or @path to a JSON file. See Specify Targets. |
| --test-url | None | Starting URL, up to 2048 characters. |
| --test-suite-id | None | Add the new test case to this suite. |
| --tag | None | Tag for the new test case. Repeatable, up to 20 tags of up to 60 characters each. |
| --max-steps | None | Maximum number of actions the agent can take, 1 to 200. Default is the service default. |
| --tunnel-name | None | Name of an active Sauce Connect tunnel to route the session through. |
| --generation-timeout | None | Time the service can spend authoring the test case, from 1m to 1h. Default is the service default. |
| --wait | None | Wait for authoring to finish, streaming each action as it happens. |
| --poll-interval | None | How often to check the task status while waiting. Default is 3s. |
| --wait-timeout | None | How long saucectl waits before it stops watching. With the default of 0, the wait is --generation-timeout plus two minutes, or 1h2m if no generation timeout is set. |
| --out | -o | Output format. Options: text (default) and json. With json, progress is not streamed and a single final object is printed. |
saucectl authoring testcases generate --name "Login" \
--intent "Log in as standard_user and verify the inventory page loads" \
--test-url https://www.saucedemo.com \
--target browserName=chrome,platformName="Windows 11" --wait
saucectl authoring testcases generate --name "Checkout" --intent-file checkout.txt \
--target-json @pixel9.json --tag mobile --generation-timeout 15m
generate-status
Show the status of an authoring task started with generate, or reattach to it and wait for it to finish.
$ saucectl authoring testcases generate-status <task-id> [flags]
| Flag | Shorthand | Description |
|---|---|---|
| --wait | None | Wait for the task to finish, streaming each action as it happens. |
| --poll-interval | None | How often to check the task status while waiting. Default is 3s. |
| --wait-timeout | None | How long saucectl waits before it stops watching. The default of 0 means 1h2m. |
| --out | -o | Output format. Options: text (default) and json. |
saucectl authoring testcases generate-status <task-id>
saucectl authoring testcases generate-status <task-id> --wait
rename
Rename a test case.
$ saucectl authoring testcases rename <id> <name> [flags]
| Flag | Shorthand | Description |
|---|---|---|
| --out | -o | Output format. Options: text (default) and json. |
saucectl authoring testcases rename <test-case-id> "Checkout - add two items"
delete
Delete a test case.
Alias: rm
$ saucectl authoring testcases delete <id> [flags]
| Flag | Shorthand | Description |
|---|---|---|
| --yes | -y | Skip the confirmation prompt. Required when saucectl is not running interactively. |
saucectl authoring testcases delete <test-case-id> --yes
run
Start a run of a test case against its stored run targets, or against the targets you set with --target or --target-json. The command returns as soon as the run is accepted. Use get-run to check on it.
To wait for results, report them, and fail a pipeline when a test fails, use saucectl run with a kind: authoring configuration instead.
Without --tunnel-name, the run starts with no tunnel, and any tunnel name stored on the test case is cleared.
$ saucectl authoring testcases run <id> [flags]
| Flag | Shorthand | Description |
|---|---|---|
| --target | None | Target capabilities as key=value pairs. Repeatable. See Specify Targets. |
| --target-json | None | Target capabilities as a JSON object, or @path to a JSON file. Repeatable. See Specify Targets. |
| --build | None | Build name to group the run's jobs under, up to 100 characters. |
| --tunnel-name | None | Name of an active Sauce Connect tunnel to route the run through. |
| --revision | None | Run this revision instead of the latest. |
| --out | -o | Output format. Options: text (default) and json. |
saucectl authoring testcases run <test-case-id> --build nightly
saucectl authoring testcases run <test-case-id> --target browserName=firefox,platformName="Windows 11"
saucectl authoring testcases run <test-case-id> --target-json @pixel9.json --tunnel-name my-tunnel
list-runs
List the runs of a test case.
Alias: runs
$ saucectl authoring testcases list-runs <id> [flags]
| Flag | Shorthand | Description |
|---|---|---|
| --out | -o | Output format. Options: text (default) and json. |
| --start-date | None | Only runs created on or after this ISO 8601 date. |
| --end-date | None | Only runs created on or before this ISO 8601 date. |
| --user-id | None | Only runs started by this user ID. |
| --team-id | None | Only runs that belong to this team ID. |
| --skip | None | Number of results to skip. Default is 0. |
| --limit | None | Maximum number of results to return. Default is 20. Use 0 to return only the total count. |
| --all | None | Return every result, fetching all pages. --limit is ignored. |
saucectl authoring testcases list-runs <test-case-id>
saucectl authoring testcases list-runs <test-case-id> --all -o json
get-run
Show a single run of a test case, with its jobs.
$ saucectl authoring testcases get-run <id> <run-id> [flags]
| Flag | Shorthand | Description |
|---|---|---|
| --out | -o | Output format. Options: text (default) and json. |
saucectl authoring testcases get-run <test-case-id> <run-id>
list-code-targets
List the languages and frameworks that a test case can be exported to with code. The available targets depend on the test case's platform.
Alias: code-targets
$ saucectl authoring testcases list-code-targets <id> [flags]
| Flag | Shorthand | Description |
|---|---|---|
| --out | -o | Output format. Options: text (default) and json. |
saucectl authoring testcases list-code-targets <test-case-id>
code
Export the latest revision of a test case as source code for a language and framework.
By default, the source code is printed to standard output so that you can redirect it. Use --filename to write it to a file, or --target-dir to write it to a directory with a filename based on the target's language. Existing files are not overwritten unless you pass --force. If you leave out --target in an interactive session, saucectl prompts you to choose one.
$ saucectl authoring testcases code <id> [flags]
| Flag | Shorthand | Description |
|---|---|---|
| --target | None | Code generation target, for example typescript_playwright. See list-code-targets. |
| --filename | -f | Write the source code to this file. |
| --target-dir | -d | Write the source code to this directory, with a filename based on the target. |
| --force | None | Overwrite an existing file. |
| --out | -o | Output format when printing to standard output. Options: text (default, the raw source code) and json. |
saucectl authoring testcases code <test-case-id> --target typescript_playwright > login.spec.ts
saucectl authoring testcases code <test-case-id> --target python_selenium -d tests/
saucectl authoring testcases code <test-case-id> --target java_selenium -f LoginTest.java --force
Specify Targets
The generate and run commands take targets in two forms.
--target takes comma-separated key=value capability pairs, one flag per target:
--target browserName=chrome,platformName="Windows 11",browserVersion=latest
- Dotted keys create nested capabilities, for example
sauce:options.screenResolution=1920x1080. - The values
trueandfalsebecome booleans. All other values stay strings.
--target-json takes a JSON object, or @path to read the object from a file. The object can be either a capabilities object or a full target that includes isRdc:
{
"capabilities": {
"platformName": "Android",
"appium:deviceName": "Google Pixel 9"
},
"isRdc": true
}