Android configuration parameters for the Gradle Plugin

When running your Android instrumentation tests with the Perfecto Gradle Plugin, you can add configuration information for the test execution at three levels:

• Configuration file (recommended): A JSON-formatted file listing parameter assignments. For a full configuration file example, see the fullConfigFile.json in our Espresso project on GitHub.
• Within the module's build.gradle file: In the perfectoGradleSettings clause, include Authentication parameters and indicate the location of the configuration file.
• On the command-line: Include any of the parameters in the format: -P<paramName>="<paramvalue>"

The following sections list the parameters for the different categories:

• Android configuration parameters for the Gradle Plugin
• Perfecto Lab authentication parameters
• Device selection parameters
• Network virtualization parameters
• Location mock
• Application parameters
• Selective testing parameters
• Pre-execution and post-execution parameters
• Screenshot parameters
• Reporting parameters
• Location of the configuration file

Perfecto Lab authentication parameters

These parameters may be set:

• In the configuration file, in the following format:

  Copy

  "cloudURL": "mobilecloud.perfectomobile.com", 
  "securityToken": "AAABNg0ODAoPeNqtkT1PwzAQhnf/CkssM...JxQ3HEI8NsX02ff",

• In the build.gradle file, in the following format:

  Copy

  perfectoGradleSettings { 
      cloudURL "mobilecloud.perfectomobile.com" 
      securityToken "AAABNg0ODAoPeNqtkT1PwzAQhnf/CkssM...JxQ3HEI8NsX02ff" 
  } 

• In the command-line in the following format:

  Copy

  > gradle perfecto-android-inst -PcloudURL="mobilecloud.perfectomobile.com" -PsecurityToken="AAABNg0ODAoPeNqtkT1PwzAQhnf/CkssM...JxQ3HEI8NsX02ff"

Device selection parameters

You can select specific devices or specify a number of random devices.

Select specific devices

You can select to use the following parameters to specify a list of devices. Obtain the values for the following parameters based on the information on the My Devices tab in the Manual Testing view, as listed for the specific devices to select, where:

• Device model is the value for model
• OS is the value for platformName and platformVersion
• Location is the value for location
• Device ID is the value for deviceName

To retrieve the value for network, select a device and click the information icon  to view device details in the right pane. Then click More details to view network information.

These parameters may be set in the configuration file, in the following format:

"devices": {
    "platformName" : "Android",
    "platformVersion": "^[678].*",
    "manufacturer" : "Samsung"
}

In the following example, four devices are selected. The fourth device in this example ({}) is chosen randomly from all available Android devices.

"devices" : [
    {
        "deviceName" : "FA6BR0304878"
    },
    {
        "platformName" : "Android",
        "platformVersion": "^[678].*",
        "manufacturer" : "Samsung"
    },
    {
        "model": "HTC One",
        "location": "US-MA-BOS",
        "network": "AT&T, Verizon"
    },
    {}
]

Specify a number of random devices

When using Espresso, you can use the following parameter, in place of the devices clause, to indicate that the specified number of Android devices should be selected and the Espresso tests run on the devices in parallel.

This parameters may be set in either the configuration file, the perfectoGradleSettings clause of the build.gradle file, or on the command line, in the following format:

"numOfDevices" : 45

Selection Retry parameters

If the plugin was unsuccessful in allocating the device, you can use the following parameters to configure a retry mechanism built into the plugin:

These parameters may be set in either the configuration file, the perfectoGradleSettings clause of the build.gradle file, or on the command line, in the following format:

"acquireDeviceRetryNumber" : 5,
"acquireDeviceRetryInterval" : 45

perfectoGradleSettings { 
    ...
    acquireDeviceRetryNumber  5
    acquireDeviceRetryInterval  45 
} 

gradle perfecto-android-inst ... -PacquireDeviceRetryNumber=5 -PacquireDeviceRetryInterval=45

Network virtualization parameters

The Gradle plugin supports configuration of a virtual network environment to execute the Espresso/Robotium tests.

Use the networkVirtualization clause in your configuration file or build.gradle file to define the parameters to define the characteristics of the emulated network. The virtual network can be configured using the same parameters supported by the Perfecto Network virtualization start command. The following is the list of parameters supported:

These parameters may be set:

• In the configuration file, in the following format:

  Copy

  "networkVirtualization": {
      "latency": 89,
      "packetLoss": 7,
      "bandwidthIn": 5,
      "bandwidthOut": 40,
      "generateHarFile": true
   }

• In the perfectoGradleSettings clause of the build.gradle file:

  Copy

  perfectoGradleSettings { 
      ...
      networkVirtualization {
          packetLoss 5
          profile    4g_lte_good
      }
      ...
  }

Location mock

The Gradle plugin supports providing a location for the device when executing Espresso tests.

Use the locationMock clause in your configuration file or build.gradle file to define the parameters to define the characteristics of the emulated location. The following is the list of parameters supported. Only one of the options should be provided. Use either the "address" clause or the "latitude", "longitude" clauses, but not both.

Examples:

• For setting the location of the device to Amal St 13, Rosh Haayin, Israel, use the following configuration:

  Copy

  "locationMock" : {"address" : "Amal St 13, Rosh Haayin, Israel"}

• For setting the location of the device to the explicit coordinates 32.106710, 34.969384, use the following configuration:

  Copy

  "locationMock" : {"latitude" : "32.106710", "longitude" : "34.969384"}

Troubleshooting

If the Set device location command does not work:

• Open, close, and reopen the application in which the location is set.

On Android devices, verify the following settings in the device:

• Allow mock locations:

  Go to: Settings > Developer options > Allow mock locations
  

• High accuracy:

  Go to: Setting > Location > Mode > High accuracy

Application parameters

"instrumentationArgs" : ["key=value","key=value",...]

-PinstrumentationArgs="key=value;key=value;..."

When activating the plugin:

• Within an Android Studio project, supply the apkName parameter.
• As a standalone activation, supply both the apkPath and testApkPath parameters or the androidAppPath and testApkPath parameters, depending on whether you work with an APK file or an Android application bundle.

Format of apkPath, testApkPath, and androidAppPath values

The path parameters indicate the location of the APK or AAB files of the application and the test-application. These may be located in either the local workstation storage or in the Perfecto Repository. To differentiate between these locations, use the following format to indicate a location in the Repository:

repository://[PUBLIC | PRIVATE]:/<app name>

Repository items must have .apk or .aab type indicator.

The "repository://" prefix is mandatory for Repository locations.

Selective testing parameters

In addition, there are filter parameters that limit the test scenarios executed during the run:

"testClassNames":["Class","Class",...]

-PtestClassNames="Class;Class;..."

"testMethodNames":["Class#Method","Class#Method",...]

-PtestMethodNames="Class#Method;Class#Method;..."

These parameters may be set as shown in the following sample codes snippets:

"testApkPath": "Users/usern/AndroidStudioProjects/Playground/app/build/outputs/apk/androidTest/debug/app-debug-AndroidTest.apk",
"apkPath": "Users/usern/AndroidStudioProjects/Playground/app/build/outputs/apk/debug/app-debug.apk",
"testSize": "small",
"testMethodNames": [
      "com.perfectomobile.com.DemoClass#demoMethod",
      "com.perfectomobile.com.DemoClass#demoMethod2"
],
"androidOrchestrator" : true

perfectoGradleSettings { 
    ...
    testApkPath "Users/usern/AndroidStudioProjects/Playground/app/build/outputs/apk/androidTest/debug/app-debug-AndroidTest.apk"
    apkPath "Users/usern/AndroidStudioProjects/Playground/app/build/outputs/apk/androidTest/debug/app-debug.apk" 
} 

gradle perfecto-android-inst ... -PapkPath="Users/usern/AndroidStudioProjects/Playground/app/build/outputs/apk/androidTest/debug/app-debug.apk" -PtestSize="large" -PandroidOrchestrator=true

"testApkPath": "Users/usern/AndroidStudioProjects/Playground/app/build/outputs/apk/androidTest/debug/app-debug-AndroidTest.apk",
"androidAppPath": "Users/usern/AndroidStudioProjects/Playground/app/build/outputs/bundle/debug/app-debug.aab",
"testSize": "small",
"testMethodNames": [
      "com.perfectomobile.com.DemoClass#demoMethod",
      "com.perfectomobile.com.DemoClass#demoMethod2"
],
"androidOrchestrator" : true

perfectoGradleSettings { 
    ...
    testApkPath "Users/usern/AndroidStudioProjects/Playground/app/build/outputs/apk/androidTest/debug/app-debug-AndroidTest.apk"
    androidAppPath "Users/usern/AndroidStudioProjects/Playground/app/build/outputs/bundle/debug/app-debug.aab" 
} 

gradle perfecto-android-inst ... -PandroidAppPath="Users/usern/AndroidStudioProjects/Playground/app/build/outputs/bundle/debug/app-debug.aab" -PtestSize="large" -PandroidOrchestrator=true

Pre-execution and post-execution parameters

The following parameters control whether the application and test apk files are uninstalled from the devices, either prior to installing the latest version or at the end of the tests:

These parameters may be configured as shown in the following sample code snippets:

"installationDetails" : { "preCleanUp" : true},
"postExecution" : { "uninstall" : false },
"preExecution" : { "screenOrientation" : "PORTRAIT" }

perfectoGradleSettings { 
    ...
    postExecution {
        uninstall false
    }
    installationDetails {
        preCleanUp true
    }
 } 

Screenshot parameters

Screenshots are an important tool for analyzing the test actions, these may be snapped by the Espresso test code, or the plugin can be configured to add screenshots when the test run ends.  The following parameters specify when the plugin takes a screenshot:

These parameters may be set in the configuration file, build.gradle file, or the command-line.

Reporting parameters

The following parameters are used by Smart Reporting to classify the execution report and make it easy to identify the reports for the execution.

These parameters may be set as shown in the following sample code snippets:

"tags" : [
       "plugin",
        "espresso",
        "demo"
],
"projectName": "playground",
"projectVersion": "1.5",
"jobName": "newFeature",
"jobNumber": "45"

perfectoGradleSettings { 
    ...
    projectName "playground"
    projectVersion "1.5"
} 

gradle perfecto-android-inst ... -Ptags="plugin;espresso;demo" -PjobName="newFeature"

Export the execution report

The Perfecto toolset generates a test execution report that can be exported for analysis. It is recommended to:

1. Use these configuration parameters to define tags, jobName, and jobNumber for the test execution.
2. Export the report data using these information items with the Smart Reporting Public API.

Location of the configuration file

The plugin execution reads the configuration file whose location is indicated by the configFileLocation parameter that may be supplied as follows:

perfectoGradleSettings { 
    ...
    configFileLocation "C:\temp\Espresso\ConfigFile.json" 
} 

gradle perfecto-android-inst ... -PconfigFileLocation="C:\temp\Espresso\ConfigFile.json"

If the parameter is not supplied:

• If running in Android Studio project - default location is <project dir>/src/main/assets/perfecto/instrumentedTest/configFile.json
• If running in Standalone mode or the file is not found at the default location, then tests will run on a randomly selected available Android device.
• The application and test-application identification parameters (apkPath and testApkPath) must be supplied in either the build.gradle file or on the command line.