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

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

  • Be familiar with Espresso
  • 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 Espresso Tests for applications.
  • 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 Espresso application and test files are available in the local disk storage.

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 .apk 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:

Important: This document includes references to a third-party product, Android Studio. The user interface and usage of third-party products are subject to change without notice. For the latest published information about Android Studio, see


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, as follows:


1 | Get started

The starting point is a local Android Studio project without Perfecto configuration: Android Studio projects are integrated with Gradle and include several build.gradle files – one at the project level and one for each application. In the local sample project: 

  • The project-level build.gradle file is located here:


    Local sample project build.gradle file

    // Top-level build file where you can add configuration options common to all sub-projects/modules.

    buildscript {
        repositories {
        dependencies {
            classpath ''
            // NOTE: Do not place your application dependencies here; they belong
            // in the individual module build.gradle files

    allprojects {
        repositories {

    task clean(type: Delete) {
        delete rootProject.buildDir
  • The app-level build.gradle file is located here:


    Local sample app build.gradle file

    apply plugin: ''

    android {
        compileSdkVersion 26
        buildToolsVersion '28.0.3'

        defaultConfig {
            applicationId "com.example.perfecto.tipcalculator"
            minSdkVersion 14
            targetSdkVersion 26
            versionCode 1
            versionName "1.0"
            testInstrumentationRunner ''
        buildTypes {
            release {
                minifyEnabled false
                proguardFiles getDefaultProguardFile('proguard-android.txt'), ''

    dependencies {
        implementation fileTree(dir: 'libs', include: ['*.jar'])
        testImplementation 'junit:junit:4.12'
        implementation ''
        androidTestImplementation '', {
            exclude group: '', module: 'support-annotations'

To get started: 

  1. Clone the project:
  2. Open Android Studio.
  3. Select the LocalEspresso workspace.
  4. Go to File > Settings > Android SDK > SDK Tools and select Show Package Details.

  5. Install Android SDK Build-Tools and set the installed version number to buildToolsVersion in the app’s build.gradle file.

  6. Right-click the project and select Synchronize LocalEspresso.
  7. Fix any Gradle-related issues, such as creating a file under base project to set the sdk.dir and ndk.dir.

2 | Configure the project for Perfecto

In this step, we update both build.gradle files with the required Perfecto dependencies. We also create a JSON 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: The following procedure walks you through the configuration.

Expand a step to view its content.

3 | Run the plugin and view the report

This step walks you through running the Perfecto Gradle plugin and viewing the test report in Perfecto.

Restriction: Not all reporting features are available for tests run with Espresso. In particular:
  • The report only includes a single test step and a single screenshot.
  • 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, you can 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-android-inst -DconfigFileLocation=configFile.json -Dhttp.proxyHost= -Dhttp.proxyPort=8800 -Dhttp.proxyUser=someUserName -Dhttp.proxyPassword=somePassword
  • As parameters defined explicitly in the file. For example:


Samples of plugin use

The Perfecto GitHub repository includes different samples that demonstrate how you can use the Perfecto Gradle plugin for the following different modes/configurations:

  • defaultAndroidProjectSample: An Android project with the plugin Json config file located in the default place
  • localJarSample: An Android project configured to run with the Perfecto plugin jar file locally
  • pluginConfigurationSample: An Android project with the cloudURL/security token configured in the build.gradle file
  • remoteRunSample: A sample showing how to run the plugin without the source code, only with .apk files
  • configFileSamplesDifferent examples of configuring the plugin using a .json file. Except for devices, all parameters can be overriden by the command line.