JarCastingAWS Device Farm Gradle Plugin
AWS Device Farm integration with the Android Gradle Build system
This plugin provides AWS Device Farm functionality from your Android gradle environment, allowing you to kick off tests on real Android phones and tablets hosted in the AWS Cloud.
For more information see the AWS Device Farm Developer Guide.
Usage
- Add the Device Farm plugin artifact. Paste the following into your top-level
build.gradle.
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'com.amazonaws:aws-devicefarm-gradle-plugin:1.3'
}
}
- Configure the Device Farm plugin in your module’s
build.gradlefile. This is usuallyapp/build.gradle.
Minimal configuration
This will do the following:
- Start a Run under the Project "My Project"
- Use the "Top Devices" curated Device Pool
- Run your instrumentation tests under
androidTest
apply plugin: 'devicefarm'
devicefarm {
// Required. The Project must already exist. You can create a project in the AWS console.
projectName "My Project"
// Required. You must specify either accessKey and secretKey OR roleArn. roleArn takes precedence.
authentication {
accessKey "aws-iam-user-accesskey"
secretKey "aws-iam-user-secretkey"
// OR
roleArn "My role arn"
}
}
Advanced configuration
apply plugin: 'devicefarm'
devicefarm {
// Required. The Project must already exist. You can create a project in the AWS console.
projectName "My Project" // required: Must already exist.
// Optional. Defaults to "Top Devices"
devicePool "My Device Pool Name"
// Optional. Default is 150 minutes
executionTimeoutMinutes 150
// Optional. Set to "off" if you want to disable device video recording during a run. Default is "on"
videoRecording "on"
// Optional. Set to "off" if you want to disable device performance monitoring during a run. Default is "on"
performanceMonitoring "on"
// Optional. Add this if you have a subscription and want to use your unmetered slots
useUnmeteredDevices()
// Required. You must specify either accessKey and secretKey OR roleArn. roleArn takes precedence.
authentication {
accessKey "aws-iam-user-accesskey"
secretKey "aws-iam-user-secretkey"
// OR
roleArn "My role arn"
}
// Optional block. Radios default to 'on' state, all parameters are optional
devicestate {
extraDataZipFile file("path/to/zip") // or ‘null’ if you have no extra data. Default is null.
auxiliaryApps files(file("path/to/app"), file("path/to/app2")) // or ‘files()’ if you have no auxiliary apps. Default is an empty list.
wifi "on"
bluetooth "off"
gps "off"
nfc "on"
latitude 47.6204 // default
longitude -122.3491 // default
}
// Optional. Set the test type. Default is instrumentation.
// You can only set one test type.
// See "Test Type configuration" below for configuration details
// Fuzz
fuzz {
}
// Instrumentation
instrumentation {
// Optional. See the AWS Developer docs for filter rules
filter "my-filter"
}
// Calabash
calabash {
tests file("path-to-features.zip")
}
}
- Run your configured test on Device Farm with the
devicefarmUploadtask. (./gradlew devicefarmUpload) - The build output will print out a link to the AWS Device Farm console where you can monitor your test execution.
Generating a proper IAM user:
- Log into your AWS web console UI.
- Click "Identity & Access Management".
- On the left-hand side of the screen, click "Users".
- Click "Create New Users".
- Enter a user name of your choice.
- Leave the "Generate an access key for each user" checkbox checked.
- Click "Create".
- View or optionally download the User security credentials that were created; you will them them later.
- Click "Close" to return to the IAM screen.
- Click your user name in the list.
- Under the Inline Policies header, click the "click here" link to create a new inline policy.
- Select the "Custom Policy" radio button.
- Click "Select".
- Give your policy a name under "Policy Name".
- Copy/paste the following policy into "Policy Document"
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "DeviceFarmAll",
"Effect": "Allow",
"Action": [ "devicefarm:*" ],
"Resource": [ "*" ]
}
]
}
- Click "Apply Policy".
Test Type configuration
Appium
Device Farm provides support for Appium Java TestNG , Appium Java JUnit, Appium python, Appium Node.js and Appium Ruby for Android.
You can choose to useTestNG() or useJUnit() or usePython() or useNode()`` or useRuby()`.
JUnit is the default and does not need to be explicitly specified.
appium {
tests file("path to zip file") // Required
useTestNG() // or useJUnit() or usePython() or useNode() or useRuby()
testSpecName "My Test Spec Name" // if you want to use Custom Mode // Optional for TestNG, JUnit and Python
}
Built-in: Explorer
Use AWS Device Farm's app explorer to test user flows through your app without writing custom test scripts. A username and password may be specified in the event your app requires account log-in.
appexplorer {
username "my-username"
password "my-password"
}
Built-in: Fuzz
Device Farm provides a built-in fuzz test type.
The built-in fuzz test randomly sends user interface events to devices and then reports results.
fuzz {
eventThrottle 50 // Optional. Default is 50
eventCount 6000 // Optional. Default is 6000
randomizerSeed 1234 // Optional. Default is blank
}
Calabash
Device Farm provides support for Calabash for Android.
calabash {
tests file("path to zip file") // Required
tags "my tags" // Optional. Calabash tags
profile "my profile" // Optional. Calabash profile
}
Instrumentation
Device Farm provides support for Instrumentation (JUnit, Espresso, Robotium, or any Instrumentation-based tests) for Android.
When running an instrumentation test in gradle the apk generated from your androidTest directory will be used as the source of your tests.
instrumentation {
filter "test filter per developer docs" // Optional
testSpecName "My Test Spec Name" // if you want to use Custom Mode // Optional
}
UI Automator
Upload your app as well as your UI Automator based tests packaged in a jar file
uiautomator {
tests file("path to uiautomator jar file") // Required
filter "test filter per developer docs" // Optional
}
Building the plugin
Building the plugin is optional. The plugin is published through Maven Central.
- Clone the GitHub repository.
- Clean, assemble and test the plugin using
./gradlew clean build - Install the plugin into your local maven directory using
./gradlew install. - The plugin will be installed to your local maven repository.
Adding New Frameworks
As Device Farm supports additional test types the plugin must be extended to enable them into the DSL.
- Define what the DSL should look like.
- Create a class in the com.amazonaws.devicefarm.extension package to support the DSL, it must extend the ConfiguredTest abstract class.
- If the test type requires a test artifact package to be uploaded in addition to the app then make sure the new class extends the TestPackageProvider trait.
- If the test type supports the 'filter' parameter extend the HasFilter trait.
- Modify DeviceFarmExtension to add a method for the new test type, like so:
void mynewtesttype(final Closure closure) {
NewTestType newTest = new NewTestType()
project.configure newTest, closure
test = newTest
}
- This will enable the configuration of the new test type within the devicefarm plugin.
