Skip to end of metadata
Go to start of metadata

XCUITest is a testing framework for running user interface tests on iOS devices. Developed by Apple, it is built on the XCTest framework, and is included as part of the iOS Xcode development tools. Tests are written in ObjectiveC/Swift, and are built as .ipa file, which is loaded and executed on the device along with the application you're testing. 

Sauce Labs offers the option to run XCUITest against our real device cloud using our test runner, which is parameterized with options for use in CI/CD environments. You can run tests against one or more devices in parallel, with test reporting that includes video, screenshots, and logs of your tests. 

One Hour Test Limit

The execution time for a single XCUITest test is one hour. Our recommended best practice is to keep all tests "Small, Atomic, and Autonomous," with maximum execution times in minutes or seconds, so you can get the most efficiency for your builds.

Prerequisites

  • To access XCUITest contact your Customer Success Manager or support@saucelabs.com
  • You must be running Java 8.x, as shown in the usage examples, to use the test runner
  • Download the latest version of the Sauce Labs Runner

     

Building Your App for Use with the Test Runner

When you are ready to build the .ipa file for your app to use with the test runner, you need to make sure that the iOS version you set for the iOS Deployment Target for both the application and your test runner match. If these don’t match, your tests will run locally, but fail when you run them against the Sauce Labs real devices. You can set this for both Projects and Targets of your application in the Xcode Build Settings.  

Project

Select the Project you want to build, and under Build Settings, set the iOS Deployment Target to the iOS operating system version you want to use in your test. All target outputs of this project, including the application and your test runner, will be set to the same operating system version. 

Target

Select the Target for your Project, and under Build Settings, set the iOS Deployment Target to the iOS operating system version you want to use in your test. This will also overwrite the Build Settings at the Project level to that operating system version, so if you use this method, be aware that your Targets can become out of synch with each other and the Project settings, and your tests will break. If you change the iOS version for one target output, you may want to build the Project again to make sure all your targets are in synch.


Test Runner Parameters

Use these parameters to configure the Sauce Labs test runner to run tests using real devices. You can set the parameters as environment variables that can be referenced in your testing scripts, or pass them as command line parameters, which will take precedence over parameters set as environment variables. 

Parameter Command Line Options

Use these options to configure the Sauce Labs test runner to run tests using real devices.

General Usage

JAVA_HOME=$(/usr/libexec/java_home --version 8) java -jar runner.jar  <options> <command> <command options>

Options

OptionDescription
--helpShow help documentation
--versionShow version

Commands and Command Options

RequiredCommandOptionDescription
Xxcui Use the XCUI command to execute iOS tests.
X --apikeyThe API key for your Sauce Labs real device cloud account.
X --usernameThe username for your real device cloud account.
X --appThe path to the *.ipa file of the application under test.
X --testThe path to the *.ipa file of the test.
X --datacenterThe data center, either in the US or EU, to use in your tests.
X --deviceFor static allocation of a device, provide the ID for the type of device to use in your tests, such as 'iPhone_5_real'. You can find the IDs for devices on the Live Testing page in the Sauce Labs web interface. Under the Real Devices tab, search for the type of device you want to use, and then click the Details link in the device description to see the device ID.
  --testname

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

  --tunnelIdentifierIf you are using Sauce Connect Proxy, provide the identifier of the tunnel you want to use.
  --checkFrequencyInterval in seconds to check test results. Default is 30.
  --timeoutTest timeout in minutes. Default is 60.
  --xmlFolderThe folder for the JUnit XML output.
  --urlProvide the URL of an alternative REST endpoint to use. Default is https://app.testobject.com/api/rest.
  --platformVersionFor dynamic allocation of a device, provide an operating system version to use. For example, use '9' to allocate a device running major version 9 and arbitrary versions of the OS, or '9.3.3' for a specific version.
  --privateDeviceIf this option is set, only devices from the private device pool will be used.
  --tabletOnlyIf this option is set, only tablet devices will be used.
  --eUse this option to pass test options in the form of key:value pairs, for example --e <key> <value>. Default is [].

Example with all Required Parameters and Setting the Data Center Option to US

java -jar runner.jar xcui --test DummyTestingApp-Runner.ipa --app DummyTestingApp.ipa --username <username> --apikey <apikey> --datacenter US --device <device_id>
  • No labels