Skip to main content

saucectl init

Generate a configuration file for use in running tests through saucectl.

Usage

$ saucectl init [OPTIONS]

Extended Description

This bootstrapping command generates a configuration file for the framework of your choice in the format required by saucectl.

You can run the command with no options to initiate interactive mode, where you are iteratively prompted for each relevant property value. Alternatively, you can specify relevant property values by entering them as inline options in the command.

In either case, the command generates a .sauce/config.yml folder and file in the location from which the command is run. If you have an existing project directory for your framework, it is advised that you run this command from the project root.

Alternative Configuration Editing

Options Summary

KeyShorthandDescription
--accessKey-aA valid Sauce Labs account access key.
--appThe path to a valid mobile application to test.
--artifacts.download.when-fThe framework for which this configuration is intended.
--browserName-bThe browser in which web-app tests will run.
--cypress.configThe path to the Cypress configuration file.
--deviceThe set of desired characteristics to match when finding a device.
--emulatorThe set of desired characteristics to match when finding an emulator.
--framework-fThe framework for which this configuration is intended.
--frameworkVersion-vThe version of the framework that is compatible with the tests to be run.
--help-hUsage information for the init command.
--platformName-pThe operation system and verseion on which tests will be run.
--region-rThe Sauce Labs data center associated with the testing account.
--testApp-tThe path to the mobile testing application.
--username-uA valid Sauce Labs user account.

Options Details

--accessKey

| OPTIONAL | STRING |

The authentication access key associated with the Sauce Labs user account making this request. If you have not set your authentication credentials as environment parameters or generated a credentials.yml file, this value is required.

Shorthand: -a

--app

| OPTIONAL | STRING | Espresso/XCUITest Only |

The path to a valid mobile application to test.

--artifacts.download.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. (default value)

--browserName

| REQUIRED | STRING | Web-app Only |

The name of the browser in which to run tests.

Shorthand: -b

--cypress.config

| REQUIRED | STRING | Cypress Only |

The file path to the Cypress configuration file (typically cypress.json).

--device

| OPTIONAL | STRING | Espresso/XCUITest Only |

Find a real device for this test by matching a set of one or more device characteristics:

CharacteristicDescriptionExample
idSpecify a device by its ID. Using this selection flag ignores all other characteristics and is not advised because availability of a specific device is uncertain and could cause your test to time out.--device "id=HTC_U11_real_us"
nameFind a device based on a partial name in order to increase likelihood of availability of similar devices.--device "name=HTC.*"
platformVersionFind a device based on its platform version.--device "platformVersion=8.0"
carrierConnectivityThe selected device must be connected to a cellular network.--device "carrierConnectivity=true"
deviceTypeThe selected device must be a particular type (PHONE, TABLET, or ANY).--device "deviceType=PHONE"
privateThe selected device must be private.--device "private=true"

You can specify a combination of device characteristics within this flag:

--device "name=HTC.*,platformVersion=8.0.0,carrierConnectivity=true"

--emulator

| OPTIONAL | STRING | Espresso Only |

Specify a virtual device for the test by matching a set of one or more emulator characteristics.

CharacteristicDescriptionExample
nameSpecify all or part of the emulator name. Supported VMD List--emulator "name=Android.*"
platformVersionSpecify the emulator platform version.--emulator "platformVersion=7.1"
orientationSpecify how the emulator should be oriented for the test (portrait or landscape).--emulator "orientation=portrait"

You can specify a combination of emulator characteristics within this flag:

--emulator "name=Samsung Galaxy S8 FHD GoogleAPI Emulator,platformVersion=7.1"

--framework

| REQUIRED | STRING |

The framework for which this configuration is intended.

Shorthand: -f

--frameworkVersion

| REQUIRED | STRING | Web-app Only |

The version of the framework that is compatible with the tests defined in this configuration.

Shorthand: -v

--help

Usage information for the init command.

Shorthand: -h

--platformName

| OPTIONAL | STRING | Web-app Only |

A specific operating system and version on which to run the specified browser and test suite.

Shorthand: -p

--region

| REQUIRED | STRING |

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

Shorthand: -r

--testApp

| REQUIRED | STRING | Espresso/XCUITest Only |

The path to the mobile testing application.

Shorthand: -t

--username

| OPTIONAL | STRING |

A valid Sauce Labs user account. If you have not set your authentication credentials as environment parameters or generated a credentials.yml file, this value is required.

Shorthand: -u

Examples

Interactive Example

$ saucectl init
12:13:20 INF Start Init Command
? Select region: us-west-1
? Select framework: [Use arrows to move, type to filter]
> cypress
playwright
testcafe
espresso
xcuitest

Batch Example

$ saucectl init -r us-west-1 -f cypress -b chrome