Skip to main content

saucectl init

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

Usage

$ saucectl init <framework> [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

Global Options Summary

These global options can be specified across all frameworks.

KeyShorthandDescription
--help-hUsage information for the init command.
--no-promptDisable interactive prompts.
--region-rThe Sauce Labs data center associated with the testing account.

Global Options Details

--help

Usage information for the init command.

Shorthand: -h

--no-prompt

Disables the interactive mode. You'll have to specify most values for initialization via CLI flags, since there'll be no more prompts for inputs.

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

Cypress Options Summary

KeyShorthandDescription
--artifacts-whenWhen to download artifacts.
--browserBrowser name.
--cypress-configPath to the cypress config file.
--platformOS name and version, such as Windows 11 or macOS 13.
--versionCypress version.

Cypress Option Details

--artifacts-when

| OPTIONAL |

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)

--browser

| REQUIRED |

The name of the browser in which to run tests.

--cypress-config

| REQUIRED |

The file path to the Cypress configuration file (typically cypress.config.js or cypress.config.ts).

--platform

| REQUIRED |

A specific operating system and version on which to run the specified browser and test suite, such as Windows 11 or macOS 13.

--version

| REQUIRED |

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

Espresso Options Summary

KeyShorthandDescription
--appPath to the application under test.
--artifacts-whenWhen to download artifacts.
--deviceReal device to use for testing.
--emulatorAndroid emulator to use for testing.
--other-appsPath to additional applications.
--test-appPath to the test application.

Espresso Option Details

--app

| REQUIRED |

The path to a valid mobile application to test.

--artifacts-when

| OPTIONAL |

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)

--device

| OPTIONAL |

Find a real device for this test by matching a set of one or more device characteristics. More details on static and dynamic device allocation can be found here.

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 |

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.*"
platformVersionsSpecify the emulator platform version.--emulator "platformVersions=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,platformVersions=7.1"

--other-apps

| OPTIONAL |

The path(s) to additional applications that need to be installed along with the main app.

--test-app

| REQUIRED |

The path to the mobile testing application.

Playwright Options Summary

KeyShorthandDescription
--artifacts-whenWhen to download artifacts.
--browserBrowser name.
--platformOS name and version, such as Windows 11 or macOS 13.
--projectPlaywright project name.
--test-matchTest file pattern to match against.
--versionPlaywright version.

Playwright Option Details

--artifacts-when

| OPTIONAL |

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)

--browser

| REQUIRED |

The name of the browser in which to run tests.

--platform

| REQUIRED |

A specific operating system and version on which to run the specified browser and test suite, such as Windows 11 or macOS 13.

--project

| OPTIONAL |

If your Playwright config file (playwright.config.js/ts) contains projects, you must specify which project you want to run. This flag is not required otherwise.

--test-match

| OPTIONAL |

Which test files to match against for the purpose of testing. Defaults to .*.spec.js.

--version

| REQUIRED |

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

Imagerunner Options Summary

KeyShorthandDescription
--artifacts-whenWhen to download artifacts.
--imageDocker image to use.
--workloadType of work performed.

Imagerunner Option Details

--artifacts-when

| OPTIONAL |

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)

--image

| REQUIRED |

The container image for Sauce Orchestrate.

--workload

| REQUIRED |

The type of work performed within the container. Valid values are:

  • webdriver: Choose this if you are running webdriver tests.
  • other: Choose this for any other work.

TestCafe Options Summary

KeyShorthandDescription
--artifacts-whenWhen to download artifacts.
--browserBrowser name.
--platformOS name and version, such as Windows 11 or macOS 13.
--versionTestCafe version.

TestCafe Option Details

--artifacts-when

| OPTIONAL |

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)

--browser

| REQUIRED |

The name of the browser in which to run tests.

--platform

| REQUIRED |

A specific operating system and version on which to run the specified browser and test suite, such as Windows 11 or macOS 13.

--version

| REQUIRED |

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

XCUITest Options Summary

KeyShorthandDescription
--appPath to the application under test.
--artifacts-whenWhen to download artifacts.
--deviceReal device to use for testing.
--other-appsPath to additional applications.
--simulatorThe iOS simulator to use for testing.
--test-appPath to the test application.

XCUITest Option Details

--app

| REQUIRED |

The path to a valid mobile application to test.

--artifacts-when

| OPTIONAL |

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)

--device

| OPTIONAL |

Find a real device for this test by matching a set of one or more device characteristics. More details on static and dynamic device allocation can be found here.

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=iPhone_15_Pro_real_sjc1"
nameFind a device based on a partial name in order to increase likelihood of availability of similar devices.--device "name=iPhone.*"
platformVersionFind a device based on the version of the iOS operating system.--device "platformVersion=16.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=iPhone.*,platformVersion=16.0,carrierConnectivity=true"

--simulator

| OPTIONAL |

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

CharacteristicDescriptionExample
nameSpecify all or part of the simulator name. Supported VMD List--simulator "name=iPhone.*"
platformVersionsSpecify the simulator platform version.--simulator "platformVersions=16.0"
orientationSpecify how the simulator should be oriented for the test (portrait or landscape).--simulator "orientation=portrait"

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

--simulator "name=iPhone 14 Simulator,platformVersions=16.0"

--other-apps

| OPTIONAL |

The path(s) to additional applications that need to be installed along with the main app.

--test-app

| REQUIRED |

The path to the mobile testing application.