Configuring Your XCUITest Tests for Real Devices and Simulators

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 XCUITest tests, simply modify the properties of the YAML file accordingly. This page defines each of the configuration properties specific to running XCUITest 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...

View on GitHub

Each of the properties supported for running XCUITest 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: xcuitest

`showConsoleLog`

| OPTIONAL | BOOLEAN |

Controls whether the contents of console.log are always shown in the local output of saucectl. By default (false), console.log is only shown for failed suites.

showConsoleLog: true

`defaults`

| OPTIONAL | OBJECT |

Specifies any default settings for the project.

defaults:
  timeout: 15m

`timeout`

| OPTIONAL | DURATION |

Instructs how long (in ms, s, m, or h) saucectl should wait for each suite to complete. You can override this setting for individual suites using the timeout setting within the suites object. If not set, the default value is 0 (unlimited).

Real Device Max Duration

When setting the timeout values for your suites, consider that native framework tests on real devices enforce a maximum test duration limit of 90 minutes.

defaults:
  timeout: 15m

`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:
    tags:
      - e2e
      - release team
      - other tag
    build: Release $CI_COMMIT_SHORT_SHA
  concurrency: 5

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

sauce:
  region: eu-central-1

`metadata`

| OPTIONAL | OBJECT | VIRTUAL ONLY |

The set of properties that allows you to provide additional information about your project that helps 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.

note

At this time, the metadata property is not supported for XCUITest because XCUITest is only supported for real device testing.

sauce:
  metadata:
    build: RC 10.4.i
    tags:
      - e2e
      - iPad
      - beta
      - featurex

`concurrency`

| OPTIONAL | INTEGER |

Sets the maximum number of suites to execute at the same time. If the test defines more suites than the max, excess suites are queued and run in order as each suite completes.

caution

Set this value to equal or less than your Sauce concurrency allowance, as setting a higher value may result in jobs dropped by the server.

sauce:
  concurrency: 5

Alternatively, you can override the file setting at runtime by setting the concurrency flag as an inline parameter of the saucectl run command:

saucectl run --ccy 5

`retries`

| OPTIONAL | INTEGER |

Sets the number of times to retry a failed suite. For more settings, you can refer to passThreshold.

sauce:
  retries: 1

Alternatively, you can override the file setting at runtime by setting the retries flag as an inline parameter of the saucectl run command:

saucectl run --retries 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.

note

This property replaces the former parent property, which is deprecated.

sauce:
  tunnel:
    name: your_tunnel_name
    owner: tunnel_owner_username

`launchOrder`

| OPTIONAL | STRING |

Specifies the execution order for your test suites. When set to fail rate, test suites with the highest failure rate will execute first. If unspecified, test suites will execute in the order in which they are written in the configuration file.

sauce:
  launchOrder: fail rate

`env`

| OPTIONAL | OBJECT | Virtual Devices Only |

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:
    FOO: bar

`reporters`

| OPTIONAL | OBJECT |

The parent property containing all reporting capabilities provided by saucectl.

reporters:
  junit:
    enabled: true
    filename: saucectl-report.xml
    webhookURL: https://my-webhook-url

`spotlight`

| OPTIONAL | OBJECT |

The spotlight reporter highlights failed or otherwise interesting jobs. It may include an excerpt of failed tests or other information that may be useful for troubleshooting.

reporters:
  spotlight:
    enabled: true

`junit`

| OPTIONAL | OBJECT |

The JUnit reporter gathers JUnit reports from all jobs and combines them into a single report.

reporters:
  junit:
    enabled: true

`json`

| OPTIONAL | OBJECT |

The JSON reporter gathers test results from all jobs and combines them into a single report.

reporters:
  json:
    enabled: true

`enabled`

| OPTIONAL | BOOLEAN |

Toggles the reporter on/off.

reporters:
  junit: # or json
    enabled: true

`webhookURL`

| OPTIONAL | STRING |

Specifies the webhook URL. When saucectl test is finished, it'll send an HTTP POST with a JSON payload to the configured webhook URL.

reporters:
  junit: # or json
    webhookURL: https://my-webhook-url

`filename`

| OPTIONAL | STRING |

Specifies the report filename. Defaults to "saucectl-report.json".

reporters:
  junit: # or json
    filename: my-saucectl-report.json

`artifacts`

| OPTIONAL | OBJECT |

The parent property specifying how to manage test output, such as logs, videos, and screenshots.

artifacts:
  cleanup: true
  download:
    when: always
    match:
      - junit.xml
    directory: ./artifacts/

`cleanup`

| OPTIONAL | BOOLEAN |

When set to true, all contents of the specified download directory are cleared before any new artifacts from the current test are downloaded.

artifacts:
  cleanup: true

`download`

| OPTIONAL | OBJECT |

Specifies the settings related to downloading artifacts from tests run by saucectl.

artifacts:
  download:
    when: always
    match:
      - junit.xml
    directory: ./artifacts/

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

artifacts:
  download:
    when: always

`match`

| OPTIONAL | STRING/ARRAY |

Specifies which artifacts to download based on whether they match the name or file type pattern provided. Supports the wildcard character * (use quotes for best parsing results with wildcard).

artifacts:
  download:
    match:
      - junit.xml
      - "*.log"

`directory`

| OPTIONAL | STRING |

Specifies the path to the folder location in which to download artifacts. A separate subdirectory is generated in this location for each suite for which artifacts are downloaded. The name of the subdirectory will match the suite name. If a directory with the same name already exists, the new one will be suffixed by a serial number.

artifacts:
  download:
    directory: ./artifacts/

`xcuitest`

| REQUIRED | OBJECT |

The parent property containing the details specific to the XCUITest project.

xcuitest:
  app: ./apps/SauceLabs-Demo-App.ipa # This is an example app for real devices.
  appDescription: My demo app
  testApp: ./apps/SauceLabs-Demo-App-Runner.app
  testAppDescription: My test app
  otherApps:
    - ./apps/pre-installed-app1.ipa # This is an example app for real devices.
    - ./apps/pre-installed-app2.ipa # This is an example app for real devices.

caution

saucectl supports running XCUITests on Real Devices and Simulators which can be configured by using:

devices, see Devices
simulators, see Simulators

They can NOT be used in the same suites configuration due to app and testApp architecture differences between Real Devices and Simulators (enforced by Apple). If you want to use both Real Devices and Simulators, you need to create two separate suites configurations and provide app and testApp configuration for each suite.

Follow the instructions to build iOS Real Device .ipa files or iOS Simulator .app files.

`app`

| REQUIRED | STRING |

Specifies a local path, url, or storage identifier to the app under test. This property supports expanded environment variables. Supports *.ipa, *.app and *.zip file types.

xcuitest:
  # Local paths
  ## Real Devices
  app: ./apps/xcuitest/SauceLabs-Demo-Real-Device-App.ipa

  ## Simulators
  app: ./apps/xcuitest/SauceLabs-Demo-Simulator-App.app # Will automatically be zipped
  app: ./apps/xcuitest/SauceLabs-Demo-Simulator-App.zip

  # Remote locations
  ## Real Devices
  app: https://example.app.download.url/SauceLabs-Demo-Real-Device-App.ipa

  ## Simulators
  app: https://example.app.download.url/SauceLabs-Demo-Simulator-App.zip

  # Using an environment variable
  app: $APP

  # Storage identifiers
  app: storage:c78ec45e-ea3e-ac6a-b094-00364171addb

  ## Real Devices
  app: storage:filename=SauceLabs-Demo-App.ipa

  ## Simulators
  app: storage:filename=SauceLabs-Demo-Simulator-App.zip

`appDescription`

| OPTIONAL | STRING |

Specifies description for the uploaded app.

xcuitest:
  appDescription: My demo app

`testApp`

| REQUIRED | STRING |

Either a local path, url, or storage identifier to the testing app. This property supports expanded environment variables. Supports *.ipa, *.app or *.zip file types.

xcuitest:
  # Local paths
  ## Real Devices
  testApp: ./apps/xcuitest/SauceLabs-Demo-Real-Device-App-Runner.ipa

  ## Simulators
  testApp: ./apps/xcuitest/SauceLabs-Demo-Simulator-App-Runner.app # Will automatically be zipped
  testApp: ./apps/xcuitest/SauceLabs-Demo-Simulator-App-Runner.zip

  # Remote locations
  ## Real Devices
  testApp: https://example.app.download.url/SauceLabs-Demo-Real-Device-App-Runner.ipa

  ## Simulators
  testApp: https://example.app.download.url/SauceLabs-Demo-Simulator-App-Runner.zip

  # Using an environment variable
  testApp: $APP

  # Storage identifiers
  testApp: storage:11f421f0-30e3-23c2-9026-d73a205dcd38

  ## Real Devices
  testApp: storage:filename=SauceLabs-Demo-App-Runner.ipa

  ## Simulators
  testApp: storage:filename=SauceLabs-Demo-Simulator-App-Runner.zip

`testAppDescription`

| OPTIONAL | STRING |

Specifies description for the uploaded testApp.

xcuitest:
  testAppDescription: My test Runner app

`otherApps`

| OPTIONAL | ARRAY |

Set of up to seven (real devices) or two (virtual devices) apps to pre-install for your tests. See app for more app details.

note

Real Device and Simulator apps can NOT be combined, see xcuitest for more details.
Apps specified as otherApps inherit the configuration of the main app under test for Device Language, Device Orientation, and Proxy, regardless of any differences that may be applied through the Sauce Labs UI, because the settings are specific to the device under test. For example, if the dependent app is intended to run in landscape orientation, but the main app is set to portrait, the dependent app will run in portrait for the test, which may have unintended consequences.

xcuitest:
  otherApps:
    - ./apps/pre-installed-app1.ipa                           # This is an example app for real devices.
    - https://example.app.download.url/pre-installed-app1.ipa # This is an example app for real devices.
    - $PRE_INSTALLED_APP2
    - storage:8d250fec-5ecb-535c-5d63-aed4da026293
    - storage:filename=pre-installed-app3.ipa                 # This is an example app for real devices.

`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 and related artifacts.

suites:
  - name: My Saucy Test

`app`

| OPTIONAL | STRING |

Sets the test application on the suite level. See the full usage. If this property is not set, saucectl will use the default app from the xcuitest level.

suites:
  - name: My Saucy Test
    app: ./apps/SauceLabs-Demo-App.ipa # This is an example app for real devices.

`appDescription`

| OPTIONAL | STRING |

Specifies description for the uploaded test app on the suite level. If app is not set on suite level, saucectl will use the default appDescription from the xcuitest level.

suites:
  - name: My Saucy Test
    appDescription: My Demo app

`testApp`

| OPTIONAL | STRING |

Sets the test runner application on the suite level. See the full usage. If this property is not set, saucectl will use the default testApp from the xcuitest level.

suites:
  - name: My Saucy Test
    testApp: ./apps/SauceLabs-Demo-App-Runner.app

`testAppDescription`

| OPTIONAL | STRING |

Specifies description for the uploaded test runner applicaiton on the suite level. If testApp is not set on suite level, saucectl will use the default testAppDescription from the xcuitest level.

suites:
  - name: My Saucy Test
    testAppDescription: My Demo test runner app

`timeout`

| OPTIONAL | DURATION |

Instructs how long saucectl should wait for the suite to complete, potentially overriding the default project timeout setting.

When the suite reaches the timeout limit, its status is set to '?' in the CLI. This does not reflect the actual status of the job in the Sauce Labs web UI or API.

note

Setting 0 reverts to the value set in defaults.

suites:
  - name: My Saucy Test
    timeout: 15m

`passThreshold`

| OPTIONAL | INTEGER |

Specifies the minimum number of successful attempts for a suite to be considered as passed. It should be used along with retries.

note

For example, setting retries to 3 and passThreshold to 2. The max attempt would be 4 times. If the test passed twice, it'd stop and be marked as passed. Otherwise, it'd be marked as failed.

sauce:
  retries: 3
suites:
  - name: My Saucy Test
    passThreshold: 2

`smartRetry`

| OPTIONAL | OBJECT |

Specifies the retry strategy to apply for that suite. It should be used along with retries.

sauce:
  retries: 3
suites:
  - name: My Saucy Test
    smartRetry:
      failedOnly: true

`failedOnly`

| OPTIONAL | BOOLEAN |

When set to true, saucectl collects any failed tests from the previous run and performs an automatic retry on them.

suites:
  - name: My Saucy Test
    smartRetry:
      failedOnly: true

`failedClassesOnly`

| OPTIONAL | BOOLEAN |

failedClassesOnly is deprecated. Use failedOnly instead.

`appSettings`

| OPTIONAL | OBJECT | Real Devices Only |

Application settings for real device tests.

suites:
  - name: My Saucy Test
    appSettings:
      instrumentation:
        networkCapture: true

`resigningEnabled`

| OPTIONAL | BOOLEAN | Real Devices Only |

Enables resigning of the app so that it can run on RDC devices. Set to true by default. It must be kept as true in order for instrumentation features to work. Can be set to false for private devices to install the app to the device as is.

suites:
  - name: My Saucy Test
    appSettings:
      resigningEnabled: true

`instrumentation`

| OPTIONAL | OBJECT | Real Devices Only |

Instrumentation settings for real device tests.

suites:
  - name: My Saucy Test
    appSettings:
      instrumentation:
        networkCapture: true

`vitals`

| OPTIONAL | BOOLEAN | Real Devices Only |

Configure app settings for real device to enable vitals.

suites:
   - name: My Saucy Test
     appSettings:
        instrumentation:
          vitals: true

`networkCapture`

| OPTIONAL | BOOLEAN | Real Devices Only |

Record network traffic for HTTP/HTTPS requests during app tests on real devices.

suites:
  - name: My Saucy Test
    appSettings:
      instrumentation:
        networkCapture: true

`biometrics`

| OPTIONAL | BOOLEAN | Real Devices Only |

Configure app settings for real device to intercept biometric authentication.

suites:
   - name: My Saucy Test
     appSettings:
        instrumentation:
          biometrics: true

`groupDirectory`

| OPTIONAL | BOOLEAN | Real Devices Only |

Configure app settings for real device to enable group directory access.

suites:
   - name: My Saucy Test
     appSettings:
        instrumentation:
          groupDirectory: true

`sysAlertsDelay`

| OPTIONAL | BOOLEAN | Real Devices Only |

Configure app settings for real device to delay system alerts.

suites:
   - name: My Saucy Test
     appSettings:
        instrumentation:
          sysAlertsDelay: true

`imageInjection`

| OPTIONAL | BOOLEAN | Real Devices Only |

Configure app settings for real device to inject provided images in the user app.

suites:
   - name: My Saucy Test
     appSettings:
        instrumentation:
          imageInjection: true

`simulators`

| OPTIONAL | ARRAY |

The parent property that defines details for running this suite on virtual devices using a Simulator. Check our Platform Configurator to see which Simulator configurations are available.

caution

A device or a simulator is required to run your tests. You can NOT combine them in one suite.

suites:
  - name: My Saucy Test
    simulators:
      - name: "iPhone 13 Simulator"
        orientation: portrait
        armRequired: false
        platformVersions:
          - "15.5"
          - "16.2"

`name`

| OPTIONAL | STRING |

The name of the device to simulate for this test suite. To ensure name accuracy, check the list of supported virtual devices. If you are using Simulators for this test suite, this property is REQUIRED.

suites:
  - name: My Saucy Test
    simulators:
      - name: "iPhone 13 Simulator"

`orientation`

| OPTIONAL | ENUM |

The screen orientation to use while executing this test suite on this virtual device. Valid values are portrait or landscape.

suites:
  - name: My Saucy Test
    simulators:
      - name: "iPhone 13 Simulator"
        orientation: portrait

`armRequired`

| OPTIONAL | BOOLEAN |

If set to true, the simulator will run on an ARM-based Mac. If set to false, the simulator will run on an Intel-based Mac.

suites:
  - name: My Saucy Test
    simulators:
      - name: "iPhone 15 Pro Simulator"
        armRequired: true

`platformVersions`

| OPTIONAL | ARRAY |

The set of one or more versions of the device platform on which to run the test suite. Check the list of supported virtual devices for compatible versions. If you are using Simulators for this test suite, this property is REQUIRED.

note

XCUITest for Simulators only supports iOS 15 and up.

suites:
  - name: My Saucy Test
    simulators:
      - name: "iPhone 13 Simulator"
        platformVersions:
          - "15.5"
          - "16.2"

`devices`

| OPTIONAL | OBJECT |

The parent property that defines how to select real devices on which to run the test suite. You can request a specific device using its ID, or you can specify a set of criteria to choose the first available device that matches the specifications.

When an ID is specified, it supersedes the other settings.

caution

A device or a simulator is required to run your tests. You can NOT combine them in one suite.

suites:
  - name: My Saucy Test
    devices:
      - name: "iPhone 11"
        platformVersion: "14.3"
        options:
          carrierConnectivity: true
      - id: iPhone_11_14_5_real_us

`id`

| OPTIONAL | STRING |

Request a specific device for this test suite by its ID. You can look up device IDs on device selection pages or by using our Get Devices API request.

suites:
  - name: My Saucy Test
    devices:
      - id: iPhone_11_14_5_real_us

`name`

| OPTIONAL | STRING |

Find a device for this test suite that matches the device name or portion of the name (Dynamic Device Allocation), which may provide a larger pool of available devices of the type you want.

Use Complete Name
suites:
  - name: My Saucy Test
    devices:
      - name: iPhone 11

Use Dynamic Allocation
suites:
  - name: My Saucy Test
    devices:
      - name: iPhone.*

`platformVersion`

| MANDATORY for Virtual Devices | OPTIONAL for Real Devices | STRING |

Allows you to set the mobile OS platform version that you want to use in your test.

note

Android and iOS platform versions are based on Semantic Versioning, also known as SEMVER. This means that the versions will have the format MAJOR.MINOR.PATCH.

Virtual Devices

This is mandatory for Android Emulators and iOS Simulators. You can find the available versions in our Platform Configurator.

Real Devices

This is optional for Real Devices. There are three options you can use to determine which version you want to use for your automated Appium, Espresso, or XCUITest tests:

Don't provide a platformVersion, this will result in any available Android or iOS device, no matter the version.
Provide a platformVersion that starts with your provided platformVersion string:
- 12: matches all minors and patches for platformVersion: "12". For example 12.1.0|12.1.1|12.2.0|...
- 12.1: matches all patches for platformVersion: "12.1". For example 12.1.0|12.1.1, it will not match 12.2.x|12.3.x and higher
- 12.1.1: matches all devices that have this exact platform version
In/exclude a specific version and or a range of versions by using a regular expression (regex). You don't need to provide the forward slashes (/{your-regex}/) as you would normally do with regex. Keep in mind that the regex needs to match the format MAJOR.MINOR.PATCH. The possibilities are endless, but here are just a few examples:
- ^1[3-4|6].*: Will match 13, 14 and 16, but not 15, see example.
- ^(?!15).*: Will exclude version 15 with all it's minors and patches, but will match all other versions, see example.

note

The stricter the platformVersions is, the smaller the pool of available devices will be and the longer you might need to wait for the available device. We recommend using only the major version or using the regex option to get the best results and an available device in the fastest way.

Use complete version for Real Devices
suites:
  - name: My Saucy Test
    devices:
      - name: iPhone.*
        platformVersion: 14.3

Use complete version for Virtual Devices
suites:
  - name: My Saucy Test
    simulators:
      - name: iPhone 14 Pro Simulator
        platformVersion: 16.2

Use dynamic platformVersion allocation. Real Devices Only
suites:
  - name: My Saucy Test
    devices:
      platformVersion: '^1[3-4|6].*'

`options`

| OPTIONAL | OBJECT | Real Devices Only |

A parent property to further specify desired device attributes within the pool of devices that match the name and version criteria.

`carrierConnectivity`

| OPTIONAL | BOOLEAN | Real Devices Only |

Request that the matching device is also connected to a cellular network.

suites:
  - name: My Saucy Test
    devices:
      - name: iPhone.*
        options:
          carrierConnectivity: true

`deviceType`

| OPTIONAL | STRING | Real Devices Only |

Request that the matching device is a specific type of device. Valid values are: ANY, TABLET, or PHONE.

suites:
  - name: My Saucy Test
    devices:
      - name: iPhone.*
        options:
          deviceType: TABLET

`private`

| OPTIONAL | BOOLEAN | Real Devices Only |

Request that the matching device is from your organization's private pool.

suites:
  - name: My Saucy Test
    devices:
      - name: iPhone.*
        options:
          private: true

`env`

| OPTIONAL | OBJECT | Virtual Devices Only |

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:
    FOO: bar

`testOptions`

| OPTIONAL | OBJECT |

A set of parameters allowing you to provide additional details about which test class should be run for the suite and how to apply them.

suites:
  - name: My Saucy Test
    testOptions:
      class:
         # Devices
        - SwagLabsMobileAppUITests.LoginTests/testSuccessfulLogin
        - SwagLabsMobileAppUITests.LoginTests/testNoUsernameLogin
        - SwagLabsMobileAppUITests.LoginTests
        # Simulators
        - SwagLabsMobileAppUITests/LoginTests/testSuccessfulLogin
        - SwagLabsMobileAppUITests/LoginTests/testNoUsernameLogin
        - SwagLabsMobileAppUITests/LoginTests
      notClass:
        # Devices
        - SwagLabsMobileAppUITests.SwagLabsFlow/testCompleteFlow
        # Simulators
        - SwagLabsMobileAppUITests/SwagLabsFlow/testCompleteFlow

`class`

| OPTIONAL | ARRAY |

Instructs saucectl to only run the specified classes for this test suite.

note

The class annotation for Real Devices is different from the one for Simulators.

For Real Devices, the format is TestTarget.TestClass/TestMethod.
For Simulators, the format is TestTarget/TestClass/testMethod.

suites:
  - name: My Saucy Test
    testOptions:
      class:
         # Devices
        - SwagLabsMobileAppUITests.LoginTests/testSuccessfulLogin
        - SwagLabsMobileAppUITests.LoginTests/testNoUsernameLogin
        - SwagLabsMobileAppUITests.LoginTests
        # Simulators
        - SwagLabsMobileAppUITests/LoginTests/testSuccessfulLogin
        - SwagLabsMobileAppUITests/LoginTests/testNoUsernameLogin
        - SwagLabsMobileAppUITests/LoginTests

`notClass`

| OPTIONAL | ARRAY |

Instructs saucectl to run all classes for the suite except those specified here.

note

The notClass annotation for Real Devices is different from the one for Simulators.

For Real Devices, the format is TestTarget.TestClass/TestMethod.
For Simulators, the format is TestTarget/TestClass/testMethod.

suites:
  - name: My Saucy Test
    testOptions:
      notClass:
        # Devices
        - SwagLabsMobileAppUITests.SwagLabsFlow/testCompleteFlow
        # Simulators
        - SwagLabsMobileAppUITests/SwagLabsFlow/testCompleteFlow

`testTimeoutsEnabled`

| OPTIONAL | string | Simulators Only |

By default there is no timeout, if enabled, then the timeout is 600 seconds. The values can be Yes or No. The timeout itself can be changed by adding the defaultTestExecutionTimeAllowance value. See also executionTimeAllowance | Apple Developer Documentation

suites:
  - name: My Saucy Test
    testOptions:
      testTimeoutsEnabled: "Yes"

`defaultTestExecutionTimeAllowance`

| OPTIONAL | integer | Simulators Only |

The default execution time an individual test is given to execute if testTimeoutsEnabled is enabled. The value is in seconds and rounds up the value you supply to the nearest minute. See also executionTimeAllowance | Apple Developer Documentation

suites:
  - name: My Saucy Test
    testOptions:
      defaultTestExecutionTimeAllowance: 200

`maximumTestExecutionTimeAllowance`

| OPTIONAL | integer | Simulators Only |

The maximum execution time an individual test is given to execute, regardless of the test's preferred allowance. The value is in seconds and rounds up the value you supply to the nearest minute. See also executionTimeAllowance | Apple Developer Documentation

suites:
  - name: My Saucy Test
    testOptions:
      maximumTestExecutionTimeAllowance: 300

`testLanguage`

| OPTIONAL | string | Simulators Only |

Specifies ISO 639-1 language during testing. See also ISO 639-2 Language Code List - Codes for the representation of names of languages (Library of Congress)

caution

While it's possible to change the test language, it's not always guaranteed to work depending on your specific setup. Programmatically changing the launchArguments in your test itself is often a more reliable method (Example). If the command line arguments continue to not work as expected, it would be worth reaching out to Apple's developer support for more guidance.

suites:
  - name: My Saucy Test
    testOptions:
      testLanguage: "de"

`testRegion`

| OPTIONAL | integer | Simulators Only |

Specifies ISO 3166-1 region during testing with the format {shortNameCode}_(alpha2Code}. See also ISO 639-2 Language Code List - Codes for the representation of names of languages (Library of Congress)

caution

While it's possible to change the test region, it's not always guaranteed to work depending on your specific setup. Programmatically changing the launchArguments in your test itself is often a more reliable method (Example). If the command line arguments continue to not work as expected, it would be worth reaching out to Apple's developer support for more guidance.

suites:
  - name: My Saucy Test
    testOptions:
      testRegion: "de_DE"

`shard`

| OPTIONAL | STRING |

Configures saucectl to automatically split the tests of a suite to run in parallel. Valid values are concurrency and testList.

In concurrency mode, saucectl will use the provided testListFile and automatically split those tests into several groups (the number of groups is determined by the concurrency setting). Each group will then run as an individual job.

In testList mode, saucectl will use the provided testListFile and run each entry defined there in parallel.

note

When sharding is enabled, the class setting is automatically ignored.

suites:
  - name: "I am sharded"
    shard: concurrency

`testListFile`

| OPTIONAL | STRING |

The file containing a list of tests is used when sharding tests. It's a txt file and each line contains a test. Read the Sharding XCUITest introduction to see how to generate this file.

# Devices
SwagLabsMobileAppUITests.LoginTests/testSuccessfulLogin
SwagLabsMobileAppUITests.LoginTests/testNoUsernameLogin
SwagLabsMobileAppUITests.LoginTests
# Simulators
SwagLabsMobileAppUITests/LoginTests/testSuccessfulLogin
SwagLabsMobileAppUITests/LoginTests/testNoUsernameLogin
SwagLabsMobileAppUITests/LoginTests

Advanced Configuration Considerations

The configuration file is flexible enough to allow for any customizations and definitions that are required for any of the supported frameworks. The following sections describe some of the most common configurations.

Setting up a Proxy

If you need to go through a proxy server, you can set it through the following variables:

HTTP_PROXY: Proxy to use to access HTTP websites
HTTPS_PROXY: Proxy to use to access HTTPS websites

PS> $Env:HTTP_PROXY=http://my.proxy.org:3128/
PS> $Env:HTTPS_PROXY=http://my.proxy.org:3128/

$> export HTTP_PROXY=http://my.proxy.org:3128/
$> export HTTPS_PROXY=http://my.proxy.org:3128/

Setting an Alternative Configuration File​

Example Configuration​

apiVersion​

kind​

showConsoleLog​

defaults​

timeout​

sauce​

region​

metadata​

concurrency​

retries​

tunnel​

name​

owner​

launchOrder​

env​

reporters​

spotlight​

junit​

json​

enabled​

webhookURL​

filename​

artifacts​

cleanup​

download​

when​

match​

directory​

xcuitest​

app​

appDescription​

testApp​

testAppDescription​

otherApps​

suites​

name​

app​

appDescription​

testApp​

testAppDescription​

timeout​

passThreshold​

smartRetry​

failedOnly​

failedClassesOnly​

appSettings​

resigningEnabled​

instrumentation​

vitals​

networkCapture​

biometrics​

groupDirectory​

sysAlertsDelay​

imageInjection​

simulators​

name​

orientation​

armRequired​

platformVersions​

devices​

id​

name​

platformVersion​

options​

carrierConnectivity​

deviceType​

private​

env​

testOptions​

class​

notClass​

testTimeoutsEnabled​

defaultTestExecutionTimeAllowance​

maximumTestExecutionTimeAllowance​

testLanguage​

testRegion​

shard​

testListFile​

Setting an Alternative Configuration File

Example Configuration

`apiVersion`

`kind`

`showConsoleLog`

`defaults`

`timeout`

`sauce`

`region`

`metadata`

`concurrency`

`retries`

`tunnel`

`name`

`owner`

`launchOrder`

`env`

`reporters`

`spotlight`

`junit`

`json`

`enabled`

`webhookURL`

`filename`

`artifacts`

`cleanup`

`download`

`when`

`match`

`directory`

`xcuitest`

`app`

`appDescription`

`testApp`

`testAppDescription`

`otherApps`

`suites`

`name`

`app`

`appDescription`

`testApp`

`testAppDescription`

`timeout`

`passThreshold`

`smartRetry`

`failedOnly`

`failedClassesOnly`

`appSettings`

`resigningEnabled`

`instrumentation`

`vitals`

`networkCapture`

`biometrics`

`groupDirectory`

`sysAlertsDelay`

`imageInjection`

`simulators`

`name`

`orientation`

`armRequired`

`platformVersions`

`devices`

`id`

`name`

`platformVersion`

`options`

`carrierConnectivity`

`deviceType`

`private`

`env`

`testOptions`

`class`

`notClass`

`testTimeoutsEnabled`

`defaultTestExecutionTimeAllowance`

`maximumTestExecutionTimeAllowance`

`testLanguage`

`testRegion`

`shard`

`testListFile`