AWS 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.gradle file. This is usually app/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 devicefarmUpload task. ( ./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()`` oruseRuby()`.

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.

Prepare Your Android Calabash Tests

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.
1. 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.
2. 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.