Important: This document only applies to real devices. For virtual devices, see the relevant article under Virtual mobile devices.

Learn how to run XCUITest tests with the Perfecto Gradle Plugin against real devices in Perfecto. To run an XCUITest test with Perfecto, you should:

  • Be familiar with XCUITest
  • Have existing tests to work with
  • Be a novice user of Perfecto

The Perfecto Gradle Plugin allows you to:

  • Select a device or multiple devices from the Perfecto Lab to run Apple XCTest/XCUITest.
  • Install the application and test files onto the selected devices.
  • Run the test methods on the devices.
  • See the progress of the test set on the console.
  • Access the Report Library to view the results of the tests.

Setting up the Gradle plugin involves these tasks:

  • Installing the Gradle plugin to prepare the build.gradle file
  • Configuring parameters through a configuration file (recommended).
  • Activating the plugin, understanding the output, and connecting to Smart Reporting execution reports

The following steps assume that the Xcode application and test files are available in the local disk storage. In this example, we use Apple Xcode to prepare the application files.

Each Gradle task supports the following actions:

  • Reading of Perfecto configuration parameters that select the devices to install and run the instrumentation tests
  • Installing the application, testing .app/.ipa files on Perfecto Lab devices, and running the test methods
  • Generating output to the Gradle console and the Perfecto single test report (STR) report

A sample project is available here: https://github.com/PerfectoMobileSA/PerfectoXCUITestProject

Important: This document includes references to a third-party product, Apple Xcode. The user interface and usage of third-party products are subject to change without notice. For the latest published information about Apple Xcode, see https://developer.apple.com/documentation/xcode.


Before you get started, make sure you have installed the following:

In addition, you need access to the Perfecto Gradle plugin. You can download it either automatically, after adding the required lines of code to the build.gradle file, as described in step 2 below, or, if your organization does not permit direct download, by pre-downloading it to a local libs folder (see also Install the Perfecto Gradle plugin manually).


The Perfecto Gradle plugin is not backward compatible. Make sure you always use + in the classpath to get the latest version of the build. Add the following line to the dependencies section in the project-level build.gradle file:

classpath "com.perfectomobile.instrumentedtest.gradleplugin:plugin:+"

1 | Get started

The starting point is a local Xcode project without Perfecto configuration: https://github.com/PerfectoMobileSA/PerfectoXCUITestProject/tree/master/LocalXCUITest.

To get started: 

  1. Clone the project: https://github.com/PerfectoMobileSA/PerfectoXCUITestProject/tree/master/LocalXCUITest
  2. Open Xcode.
  3. Choose the LocalXCUITest workspace.
  4. Perform Product > Clean and Build.
  5. Fix any signing-related issues.

2 | Configure the project for Perfecto

In this step, we prepare the application files and add the following new files to the project:

  • A build.gradle file that will specify the required Perfecto dependencies
  • A JSON configuration file that holds all Perfecto configurations, including security information, the Perfecto cloud name, Smart Reporting information, and test data.

The updated project is located here: https://github.com/PerfectoMobileSA/PerfectoXCUITestProject/tree/master/PerfectoXCUITest. The following procedure walks you through the configuration. 

Expand a step to view its content.

3 | Run the plugin and view the report

In this step, you run the Perfecto Gradle plugin and view the test report in Perfecto.

Restriction: Not all reporting features are available for tests run with XCUITest. The following changes apply:
  • The report only includes a single test step that includes all commands.
  • It is not possible to add custom failure reasons from within tests.
  • The video shown is for one execution, but the report artifact you can download includes all executions. 

For more information on Smart Reporting, see Test analysis with Smart Reporting. For details on the STR, see Single test report (STR).

Expand a step to view its content.

Proxy connection

If you run the Gradle plugin over a proxy connection, supply the proxy information as follows:

  • As Java parameters when activating the plugin. You can use the same Java Proxy parameters also for proxies supporting SSL encryption.

    http.proxyHost: The IP address of the proxy

    http.proxyPort: The IP port used for the connection

    http.proxyUser: The username for connecting to the proxy server

    http.proxyPassword: The password for connecting to the proxy server

    For example:

    gradlew perfecto-xctest -DconfigFileLocation=configFile.json -Dhttp.proxyHost= -Dhttp.proxyPort=8800 -Dhttp.proxyUser=someUserName -Dhttp.proxyPassword=somePassword
  • As parameters defined explicitly in the gradle.properties file. For example:


Samples of plugin use

The Perfecto GitHub repository https://github.com/PerfectoCode/XcTest/tree/master/samples includes different samples that demonstrate how you can use the Perfecto Gradle plugin for the following different modes/configurations:

  • defaultSample: An Xcode project containing the needed files for running the Perfecto XCTest task
  • localJarSample: An Xcode project configured to run the Perfecto .jar file locally
  • buildGradleConfiguration: An Xcode project with the configuration included in the build.gradle file
  • configFilesSamplesDifferent examples of configuring the plugin using a .json file. Except for devices, all parameters can be overridden by the command line.

In addition, this repository includes sample projects for running test methods from EarlGrey and KIF. For more information, see KIF/EarlGrey tests.