Sauce Runner for Real Devices YAML File Configuration

Real Devices Only

As an alternative to setting up real device tests using the Sauce Runner for Real Devices CLI, you can also create a runner YAML configuration file. This topic outlines the YAML-specific parameters needed to set up your Espresso and XCUITest tests.

note

All examples in this page assume knowledge of Sauce Runner General Usage. Please review before proceeding.

Required#

The below flags are required when writing your YAML file.

app#

Description: the path to the *.ipa or *.apk file of the app under test, or the ID number of an already uploaded app. In your command line, refer to the location where you have downloaded the runner.jar file and run the command from the folder from where you downloaded the runner.

Example:

app: ExampleTestApp.ipa

test#

Description: the path to the *.ipa or *.apk file of the test.

Examples:

test: ExampleTestApp-Runner.ipa

--datacenter#

Description: specifies the Data Center to use in your tests. Possible values: US or EU.

Example:

- datacenter: US

Basic Example (minimum required options only)

Minimum configuration example needed to run a test.

real-devices/runner-ex1.yml
loading...
See full example on GitHub
tip

Go to our GitHub repository for example scripts, plus demo apps and tests.

Device Allocation (Optional)#

Here are some additional options you can use to configure your YAML file.

device#

Description: specifies the exact device to use in your tests by providing the Device ID. See Static Device Allocation for detailed instructions.

Examples:

  • Minimal Configuration: defines a list of devices on which the tests should be executed. Only specify a DC (either EU or US).

    devices:
    - datacenter: EU
  • Static Allocation: specify a device descriptor for static allocation, for example iPhone_8_real_us.

    devices:
    - datacenter: US
    device: iPhone_8_real_us
  • Dynamic Allocation: specify a device name or regex for dynamic allocation (e.g.,iPhone 5, iPad.*).

    devices:
    - datacenter: US
    deviceNameQuery: iPhone 5
    platformVersion: 11.4
    # Optional parameters
    phoneOnly: false
    tabletOnly: false
    privateDevicesOnly: false

devices#

Description: use this option to specify a group of devices on which to run parallel tests with static allocation (exact Device ID) or dynamic allocation (using regex). For detailed instructions, see Static and Dynamic Device Allocation. As an option, you can run a select set of tests against a specific device using testsToRun.

Examples:

devices:
- datacenter: US
devices: iPhone_11_13_5_real_us,iPhone_5
Default Device Allocation

If you don't specify a --device/--devices for your test, one is assigned to your tests based on the AUT (application under test) platform type.

testname#

Description: Set a custom test name to appear on the UI. Default is Test.

Examples:

devices:
- datacenter: US
device: iPhone_11_13_5_real_us
testname: MyTestName

tunnelIdentifier#

Description: If you are using Sauce Connect Proxy, provide the identifier of the tunnel you want to use.

Example:

tunnelIdentifier: <your-tunnel-name>

checkFrequency#

Description: Interval in seconds to check test results. Default is 30.

Example:

checkFrequency: 15

timeout#

Description: sets your test timeout (unit = minutes). Test duration cannot exceed 60 minutes. Default value is 60.

Example:

timeout: 10

xmlFolder#

Description: specifies the folder for the JUnit XML output.

Example:

xmlFolder: ./tmp

url#

Description: specifies the URL of an alternative REST endpoint to use. For a list of endpoints, see Data Center Endpoints for further details.

Example:

url: <rest-endpoint-url>

platformVersion#

Description: specifies an operating system version to use for dynamic allocation of a device. For example, use 9 to allocate a device running major version 9 and arbitrary versions of the OS; use 9.3.3 for a specific minor version.

Example:

devices:
- datacenter: US
platformVersion: 9.3.3

privateDevicesOnly#

Description: if set, only private devices will be queried.

Example:

devices:
- datacenter: US
privateDevicesOnly: true

phoneOnly#

Description: if set, only phones will be queried.

Examples:

devices:
- datacenter: US
phoneOnly: true

--tabletOnly#

Description: if set, only tablets will be queried.

Example:

devices:
- datacenter: US
tabletOnly: true

deviceNameQuery#

Description: for dynamic allocation of a device, provide the device name you would like to dynamically allocate. For example, use iPhone.*Plus to allocate any iPhone Plus device.

Example:

devices:
- datacenter: US
deviceNameQuery: iPhone 8.*

testsToRun#

xcuitest only

Description: specifies the device name you would like to dynamically allocate for dynamic allocation of a device. For example, use iPhone.*Plus to allocate any iPhone Plus device. For more information, see the examples under --devices.

Example: Execute all tests in ClassA and only methodC of ClassB.

- datacenter: EU
testname: MyTestName4
testsToRun:
- testClass: ClassA
- testClass: ClassB
testMethod: methodC

Test Run Specification (Optional)#

Run a Subset of Tests#

Provide a list of test cases or test classes. If you want to run all tests of a class, provide only the class name. If you want to run a specific method of a class, provide the class name and method name.

devices:
- datacenter: EU
testsToRun:
- testClass: SampleTestCase
- testClass: SampleTestCase2
testMethod: testItWorks

Executing Your YAML File#

  1. Open a new command line terminal window.
  2. Add the config command, followed by the --path <your path to your .yml file> and --accessKey <your Sauce access key> parameters.
java -jar runner.jar config --path ./MyFile.yml --accessKey ab015c1e-xxxx-xxxx-xxxx-xxxxxxxxxxx

NOTE: Sauce Runner RDC CLI Options are not compatible with YAML-specific flags. Once you pass the config YAML command to the runner, you can only use --path and --accessKey.

This will launch your test. To see your results, go to Sauce Labs > Automated > Test Results > Real Devices.

Last updated on by Kim