Skip to main content

Configuring saucectl for API Testing

saucectl relies on a YAML specification file to determine exactly which tests to run and how to run them. To customize saucectl to run your API tests, simply modify the properties of the YAML file accordingly. This page defines each of the configuration properties specific to running API tests.

Setting an Alternative Configuration File​

By default, saucectl looks for the config.yml file in the .sauce folder of your project root, but you can actually specify a different file, or if you are using multiple frameworks or need to configure different sets of tests to run separately, you may choose to have multiple configuration files that you can direct saucectl to reference as necessary.

Use the following configuration at runtime to direct saucectl to use any configuration file you choose:

saucectl run -c ./path/to/{config-file}.yml
YAML Required

While you can use multiple files of different names or locations to specify your configurations, each file must be a *.yml and follow the saucectl syntax. Our IDE Integrations (e.g., Visual Studio Code) can help you out by validating the YAML files and provide handy suggestions, so make sure to check them out!

Example Configuration​

.sauce/config.yml
loading...

Each of the properties supported for running API tests through saucectl is defined below.

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/ENUM |

Specifies which framework is associated with the automation tests configured in this specification.

kind: apitest

sauce​

| OPTIONAL | OBJECT |

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

sauce:
  region: eu-central-1
  metadata:
    build: Release $CI_COMMIT_SHORT_SHA

region​

| OPTIONAL | STRING/ENUM |

Specifies through which Sauce Labs data center tests will run. Valid values are: us-west-1 or eu-central-1.

note

If you do not specify a region in your config file, you must set it when running your command with the --region flag.

  region: eu-central-1

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.

sauce:
  tunnel:
    name: your_tunnel_name
    owner: tunnel_owner_username

metadata​

| OPTIONAL | OBJECT |

The set of properties that allows you to provide additional information about your project that helps you distinguish it in the various environments in which it is used and reviewed, and also helps you apply filters to easily isolate tests based on metrics that are meaningful to you, as shown in the following example:

metadata:
  build: RC 10.4.a

env​

| OPTIONAL | OBJECT |

A property containing one or more environment variables that are global for all tests suites in this configuration. Values set in this global property will overwrite values set for the same environment variables set at the suite level.

  env:
    hello: world
    my_var: $MY_VAR  # You can also pass through existing environment variables through parameter expansion

rootDir​

| REQUIRED | OBJECT |

The directory where tests will be looked for.

  rootDir: "./" # Use the current directory
  rootDir: "api/tests" # Some other package from within a monorepo

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.

  - name: "saucy test"

env​

| OPTIONAL | OBJECT |

A property containing one or more environment variables that may be referenced in the tests for this suite. Expanded environment variables are supported. Values set here will be overwritten by values set in the global env property.

  env:
    hello: world
    my_var: $MY_VAR

useRemoteTests​

| OPTIONAL | STRING/ARRAY |

Use the tests already stored in Sauce Labs instead of uploading them before execution.

    useRemoteTests: true

tags​

| OPTIONAL | STRING/ARRAY |

Executes the tests contained in the specified tags. This value is only considered when using useRemoteTests: true.

    tags: ["contract"]

testMatch​

| REQUIRED | STRING/ARRAY |

One or more paths to the API Testing folders to run for this suite. Regex values are supported to indicate all or certain directory, etc.

    testMatch: ["01 Basic Request"]