Last updated: Nov 12, 2020 10:38
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).
1 | Get started
The starting point is a local Android Studio project without Perfecto configuration: https://github.com/PerfectoMobileSA/PerfectoEspressoProject/tree/master/LocalEspresso. 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:
build.gradlefile is located here: https://github.com/PerfectoMobileSA/PerfectoEspressoProject/blob/master/LocalEspresso/build.gradle
build.gradlefile is located here: https://github.com/PerfectoMobileSA/PerfectoEspressoProject/blob/master/LocalEspresso/app/build.gradle
To get started:
- Clone the project: https://github.com/PerfectoMobileSA/PerfectoEspressoProject
- Open Android Studio.
- Select the LocalEspresso workspace.
Go to File > Settings > Android SDK > SDK Tools and select Show Package Details.Click to view image
Install Android SDK Build-Tools and set the installed version number to
buildToolsVersionin the app’s build.gradle file.
- Right-click the project and select Synchronize LocalEspresso.
- Fix any Gradle-related issues, such as creating a
local.propertiesfile under base project to set the
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: https://github.com/PerfectoMobileSA/PerfectoEspressoProject/tree/master/PerfectoEspresso. The following procedure walks you through the configuration.
Expand a step to view its content.
In this step, we work with build configuration scripts called
build.gradle. Android Studio projects are integrated with Gradle and include several
build.gradle files – one at the project level and one for each application. In our sample project:
build.gradlefile is located here: https://github.com/PerfectoMobileSA/PerfectoEspressoProject/blob/master/PerfectoEspresso/build.gradle
build.gradlefile is located here: https://github.com/PerfectoMobileSA/PerfectoEspressoProject/blob/master/PerfectoEspresso/app/build.gradle
In Android Studio, open your project-level
Add the lines that define the location of the plugin library and the dependency on the plugin to the
build.gradlefile. Gradle will look to verify that the plugin is installed before performing the task.
Do one of the following, depending on whether the plugin library is already downloaded or you want to locate and download the plugin library automatically:
To configure Gradle to automatically locate and download the plugin library, add the following lines to the
If the plugin library is already downloaded to a folder (for example the libs sub-folder), add the following lines to the build.gradle file:
Save the file.
Open the app-level
build.gradlefile and add the lines that defines the plugin task.
Add the following line to load any configurations from the
Save the file.
In this step, you create the JSON text file that contains all configuration settings. This is the recommended practice. Configurations include the URL of the Perfecto lab, the security token to use, which devices to select, which tags to use, and so on.
- Create a configuration file (
configFile.json) as a JSON text file in a known folder.
Add the connection parameters to the configuration file.
cloudURLis the URL of the Perfecto Lab to connect to. For example mobilecloud.perfectomobile.com.
securityTokenis the tester's personal security token for the Perfecto lab. See also Generate security tokens.
itmsServerUrlis the URL of the ITMS server. If blank, the connection by default goes to the ITMS server in the US. To pass a request to another ITMS server, use the value
for Australia or
Add the device selection parameters to the configuration file, as shown in the following examples. For details on platform-specific parameters, see Android configuration parameters for the Gradle Plugin.
For example, add the following to select:
Any available Android device (based on the gradle task):
Specific devices, such as two devices where one is an Android device of version 6.*, 7.*, or 8.* (using a regular expression) and one is randomly selected by the Gradle plugin:
A number of random Android devices:
Add the reporting parameter settings to add tags to the execution report. For more information on adding tags, see Tag-driven reports (RTDD workflow).
is the CI identification of the build, used for classification of the report in the CI Dashboard.
- jobNumberis the CI job number of the build.
- branchis the job branch as reported in the execution context.
- projectNameis the name of the project, for classification.
- projectVersionis the version number assigned to the project for this build.
is the set of tags to associate with the execution.
Add the application parameters to identify where the application files are located.
For our Android application, these are
appPathrefers to the path of the
.apkfile for the application.
testApkPathis the path to the UI test application runner
Save the configuration file.
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.
Expand a step to view its content.
Open a command-line (terminal) window in the folder where you want to execute the plugin.
Execute the plugin using the following command:
Here we also supply the full path to the configuration file created in step 3. You can add other configuration parameters (except for device selection) to the command as needed.
- Select the devices as specified in the Device selection parameters of the configuration file (or a random device if no specification is provided).
- Install the application and test .apk files onto the device.
- Run the test methods (based on the configuration parameters).
- Send output to the console window.
- Generate an execution report that can be viewed in the Test analysis with Smart Reporting interface.
The command-line parameters can set any of the configuration parameters, except for device selection parameters. For more information, see Android configuration parameters for the Gradle Plugin.
For information on running the Gradle plugin over a proxy connection, see Proxy connection.
During the execution, the plugin reports on the progress of the execution and the completion of each test method to the command-line window.
At the end of the execution, the command-line window displays a high-level summary report of the completion status for each device. The report includes:
- Resolution of configuration settings: The configuration file used and the list of the configuration settings for the test run
- Progress notifications as the test is configured, installed, and executed, including notifications of the start and completion of:
- Allocating the device
- Resigning the application
- Installing the application and UI runner files
- Executing the test
- Connecting the video recording
- Completion status for each test method on each device
At the end of the summary report, the plugin provides the URL of the single test report (STR) for the execution run.
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
As parameters defined explicitly in the
gradle.propertiesfile. For example:
Samples of plugin use
The Perfecto GitHub repository https://github.com/PerfectoCode/Espresso 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
- remoteRunSample: A sample showing how to run the plugin without the source code, only with .apk files
- configFileSamples: Different examples of configuring the plugin using a
.jsonfile. Except for devices, all parameters can be overriden by the command line.
The following video demonstrates these steps.