Better readme

Author: jacek-marchwicki

README.md

@@ -8,6 +8,7 @@
 Firebase is actually the most popular developer tool platform, wchich handles almost every aspect of the app. It also gives possibility to run Android Tests on physical or virtual devices hosted in a Google data center through [Firebase Test Lab](https://firebase.google.com/docs/test-lab/). In order to fully exploit the potential of this tool I've created plugin to simplify process of creating tests configurations. It allows to run tests locally as well as on you CI server. 
 
 #### Available features
+- Automatic installation of `gcloud` command line tool
 - Creating tasks for testable `buildType`[By default it is `debug`. If you want to change it use `testBuildType "buildTypeName"`]
 - Creating tasks for every defined device and configuration separetly [ including Instrumented / Robo tests ]
 - Creating tasks which runs all configurations at once
@@ -22,52 +23,116 @@ Firebase is actually the most popular developer tool platform, wchich handles al
 
 #### Setup 
 
-``` Groovy
-buildscript {
-  repositories {
-    maven {
-      url "https://plugins.gradle.org/m2/"
+1. If you don't have a Firebase project for your app, go to the []Firebase console](https://console.firebase.google.com/) and click Create New Project to create one now. You will need ownership or edit permissions in your project.
+2. Create a service account related with your firebase project with an Editor role in the [Google Cloud Platform console - IAM/Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts/)
+3. Copy `Project ID` from [Google Cloud Platform console - HOME](https://console.cloud.google.com/home)
+4. Add plugin to your root project `build.gradle`:
+   ```grovy
+   buildscript {
+       repositories {
+           maven { url 'https://jitpack.io' }
+       }
+       dependencies {
+           classpath 'com.github.jacek-marchwicki:FirebaseTestLab-Android:<version_from_github_releases_tab'
+       }
+   }
+   ```
+5. Add configuration in your project `build.gradle`:
+    ```groovy
+    apply plugin: 'firebase.test.lab'
+ 
+    firebaseTestLab {
+        keyFile = file("test-lab-key.json")
+        googleProjectId = "your-project-app-id"
+        devices {
+            nexusEmulator {
+                deviceIds = ["Nexus6"]
+                androidApiLevels = [26]
+            }
+        }
     }
-  }
-  dependencies {
-    classpath "gradle.plugin.firebase.test.lab:plugin:1.0.4"
-  }
-}
+    ```
+    List of available [devices](https://firebase.google.com/docs/test-lab/images/gcloud-device-list.png)
+6. Run your instrumentations tests
+    
+    ```bash
+    ./gradlew firebaseTestLabExecuteDebugInstrumentation
+    ```
+    
+    Or run robo tests
+    
+    ```bash
+    ./gradlew firebaseTestLabExecuteDebugRobo 
+    ```
+
+#### Advanced configuration
+
+You can 
+``` Goovy
+// Setup firebase test lab plugin
+firebaseTestLab {
+    // REQUIRED obtain service key as described inside README
+    keyFile = file("test-lab-key.json")
+    // REQUIRED setup google project id ad described inside README
+    googleProjectId = "your-project-app-id"
 
-apply plugin: "firebase.test.lab"
-```
-``` Groovy
-//For gradle 2.1+
-plugins {
-  id "firebase.test.lab" version "1.0.4"
-}
-```
+    // If you want you can ignore test failures
+    // ignoreFailures = true
 
-#### How to use it
+    // If you prefer you can use your custom google storage bucket for storing build sources and results
+    // cloudBucketName = "your-custome-google-storage-bucket-name"
+    // cloudDirectoryName = "your-custome-directory-name"
 
-Add devices configurations inside `build.gradle`
-List of available [devices](https://firebase.google.com/docs/test-lab/images/gcloud-device-list.png)
+    // If you prefer to install gcloud tool manually you can set path by
+    // cloudSdkPath = "/user/cloud-sdk/bin"
 
-``` Goovy
-firebaseTestLab {
-    keyFile = file("keys.json")
-    googleProjectId = "your-project-id"
-    cloudSdkPath = "/user/cloud-sdk/bin"
-    cloudBucketName = "bucket-test"
-    cloudDirectoryName = "androidTests"
-    clearDirectoryBeforeRun = true
+    // If you want to change default gcloud installation path (default is in build/gcloud directory)
+    // you can set environment variable `export CLOUDSDK_INSTALL_DIR=`/cache/your_directory/`
 
+    // REQUIRED
     devices {
-        galaxyS7 {
-            androidApiLevels = [23]
-            deviceIds = ["herolte"]
+        // REQUIRED add at least one device
+        nexusEmulator {
+            // REQUIRED Choose at least one device id
+            // you can list all available via `gcloud firebase test android models list` or look on https://firebase.google.com/docs/test-lab/images/gcloud-device-list.png
+            deviceIds = ["Nexus6"]
+
+            // REQUIRED Choose at least one API level
+            // you can list all available via `gcloud firebase test android models list` for your device model
+            androidApiLevels = [26]
+
+            // You can test app in landscape and portrait
+            // screenOrientations = [com.appunite.firebasetestlabplugin.model.ScreenOrientation.PORTRAIT, com.appunite.firebasetestlabplugin.model.ScreenOrientation.LANDSCAPE]
+
+            // Choose language (default is `en`)
+            // you can list all available via `gcloud firebase test android locales list`
+            // locales = ["en"]
+
+            // If you are using ABI splits you can filter selected abi
+            // filterAbiSplits = true
+            // abiSplits = ["armeabi-v7a", "arm64-v8a", "x86", "x86_64"]
+
+            // If you are using ABI splits you can remove testing universal APK
+            // testUniversalApk = false
+
+            // You can set timeout (in seconds) for test
+            // timeout = 6000
+        }
+        // You can define more devices
+        someOtherDevices {
+            deviceIds = ["hammerhead", "shamu"]
+            androidApiLevels = [21]
         }
     }
 }
 ```
 
+For more precise test selection run
 
+```bash
+./gradlew tasks 
+```
 
-
+to discover all available test options
 
 

plugin/src/main/java/com/appunite/firebasetestlabplugin/FirebaseTestLabPlugin.kt

@@ -6,9 +6,9 @@ import com.android.build.gradle.api.BaseVariantOutput
 import com.android.build.gradle.api.TestVariant
 import com.appunite.firebasetestlabplugin.cloud.CloudTestResultDownloader
 import com.appunite.firebasetestlabplugin.cloud.FirebaseTestLabProcessCreator
+import com.appunite.firebasetestlabplugin.cloud.TestType
 import com.appunite.firebasetestlabplugin.model.Device
 import com.appunite.firebasetestlabplugin.model.TestResults
-import com.appunite.firebasetestlabplugin.model.TestType
 import com.appunite.firebasetestlabplugin.utils.Constants
 import org.apache.tools.ant.taskdefs.condition.Os
 import org.gradle.api.*
@@ -194,29 +194,32 @@ internal class FirebaseTestLabPlugin : Plugin<Project> {
 
             (project.extensions.findByName(ANDROID) as AppExtension).apply {
                 testVariants.toList().forEach { testVariant ->
-                    createGroupedTestLabTask(TestType.INSTRUMENTATION, devices, testVariant, firebaseTestLabProcessCreator, ignoreFailures, downloader)
-                    createGroupedTestLabTask(TestType.ROBO, devices, testVariant, firebaseTestLabProcessCreator, ignoreFailures, downloader)
+                    createGroupedTestLabTask(devices, testVariant, firebaseTestLabProcessCreator, ignoreFailures, downloader)
                 }
             }
 
 
         }
     }
 
+    data class DeviceAppMap(val device: Device, val apk: BaseVariantOutput)
+
     data class Test(val device: Device, val apk: BaseVariantOutput, val testApk: BaseVariantOutput)
 
     private fun createGroupedTestLabTask(
-            testType: TestType,
             devices: List<Device>,
             variant: TestVariant,
             firebaseTestLabProcessCreator: FirebaseTestLabProcessCreator,
             ignoreFailures: Boolean,
             downloader: CloudTestResultDownloader?) {
         val variantName = variant.testedVariant?.name?.capitalize() ?: ""
 
-        val cleanTask = "firebaseTestLabClean${variantName.capitalize()}${testType.toString().toLowerCase().capitalize()}"
-        val runTestsTask = "firebaseTestLabExecute${variantName.capitalize()}${testType.toString().toLowerCase().capitalize()}"
-        val downloadTask = "firebaseTestLabDownload${variantName.capitalize()}${testType.toString().toLowerCase().capitalize()}"
+        val cleanTask = "firebaseTestLabClean${variantName.capitalize()}"
+
+        val runTestsTask = "firebaseTestLabExecute${variantName.capitalize()}"
+        val runTestsTaskInstrumentation = "${runTestsTask}Instrumentation"
+        val runTestsTaskRobo = "${runTestsTask}Robo"
+        val downloadTask = "firebaseTestLabDownload${variantName.capitalize()}"
 
         if (downloader != null) {
             project.task(cleanTask, closureOf<Task> {
@@ -229,7 +232,7 @@ internal class FirebaseTestLabPlugin : Plugin<Project> {
             })
         }
 
-        val tasks = combineAll(devices, variant.testedVariant.outputs, variant.outputs, ::Test)
+        val appVersions = combineAll(devices, variant.testedVariant.outputs, ::DeviceAppMap)
                 .filter {
                     val hasAbiSplits = it.apk.filterTypes.contains(VariantOutput.ABI)
                     if (hasAbiSplits) {
@@ -243,35 +246,55 @@ internal class FirebaseTestLabPlugin : Plugin<Project> {
                         it.device.testUniversalApk
                     }
                 }
+        val roboTasks = appVersions
+                .map {
+                    test ->
+                    val devicePart = test.device.name.capitalize()
+                    val apkPart = dashToCamelCase(test.apk.name).capitalize()
+                    val taskName = "$runTestsTaskRobo$devicePart$apkPart"
+                    project.task(taskName, closureOf<Task> {
+                        inputs.files(test.apk.outputFile)
+                        group = Constants.FIREBASE_TEST_LAB
+                        description = "Run Robo test for ${test.device.name} device on $variantName/${test.apk.name} in Firebase Test Lab"
+                        if (downloader != null) {
+                            mustRunAfter(cleanTask)
+                        }
+                        dependsOn(taskSetup)
+                        dependsOn(arrayOf(test.apk.assemble))
+                        doLast {
+                            val result = firebaseTestLabProcessCreator.callFirebaseTestLab(test.device, test.apk.outputFile, TestType.Robo)
+                            processResult(result, ignoreFailures)
+                        }
+                    })
+                }
+
+        val instrumentationTasks = combineAll(appVersions, variant.outputs, {deviceAndMap, testApk -> Test(deviceAndMap.device, deviceAndMap.apk, testApk)})
                 .map {
                     test ->
                     val devicePart = test.device.name.capitalize()
                     val apkPart = dashToCamelCase(test.apk.name).capitalize()
                     val testApkPart = test.testApk.let { if (it.filters.isEmpty()) "" else dashToCamelCase(it.name).capitalize() }
-                    val taskName = "$runTestsTask$devicePart$apkPart$testApkPart"
+                    val taskName = "$runTestsTaskInstrumentation$devicePart$apkPart$testApkPart"
                     project.task(taskName, closureOf<Task> {
                         inputs.files(test.testApk.outputFile, test.apk.outputFile)
                         group = Constants.FIREBASE_TEST_LAB
-                        description = "Run Android Tests in Firebase Test Lab"
+                        description = "Run Instrumentation test for ${test.device.name} device on $variantName/${test.apk.name} in Firebase Test Lab"
                         if (downloader != null) {
                             mustRunAfter(cleanTask)
                         }
                         dependsOn(taskSetup)
-                        dependsOn(* when (testType) {
-                            TestType.INSTRUMENTATION -> arrayOf(test.apk.assemble, test.testApk.assemble)
-                            TestType.ROBO -> arrayOf(test.apk.assemble)
-                        })
+                        dependsOn(arrayOf(test.apk.assemble, test.testApk.assemble))
                         doLast {
-                            val result = firebaseTestLabProcessCreator.callFirebaseTestLab(testType, test.device, test.apk.outputFile, test.testApk.outputFile)
+                            val result = firebaseTestLabProcessCreator.callFirebaseTestLab(test.device, test.apk.outputFile, TestType.Instrumentation(test.testApk.outputFile))
                             processResult(result, ignoreFailures)
                         }
                     })
                 }
 
-        project.task(runTestsTask, closureOf<Task> {
+        val allInstrumentation = project.task(runTestsTaskInstrumentation, closureOf<Task> {
             group = Constants.FIREBASE_TEST_LAB
-            description = "Run Android Tests in Firebase Test Lab"
-            dependsOn(tasks)
+            description = "Run all Instrumentation tests for $variantName in Firebase Test Lab"
+            dependsOn(instrumentationTasks)
 
             doFirst {
                 if (devices.isEmpty()) throw IllegalStateException("You need to set et least one device in:\n" +
@@ -285,10 +308,37 @@ internal class FirebaseTestLabPlugin : Plugin<Project> {
                         "  } " +
                         "}")
 
-                if (tasks.isEmpty()) throw IllegalStateException("Nothing match your filter")
+                if (instrumentationTasks.isEmpty()) throw IllegalStateException("Nothing match your filter")
             }
         })
 
+        val allRobo = project.task(runTestsTaskRobo, closureOf<Task> {
+            group = Constants.FIREBASE_TEST_LAB
+            description = "Run all Robo tests for $variantName in Firebase Test Lab"
+            dependsOn(roboTasks)
+
+            doFirst {
+                if (devices.isEmpty()) throw IllegalStateException("You need to set et least one device in:\n" +
+                        "firebaseTestLab {" +
+                        "  devices {\n" +
+                        "    nexus6 {\n" +
+                        "      androidApiLevels = [21]\n" +
+                        "      deviceIds = [\"Nexus6\"]\n" +
+                        "      locales = [\"en\"]\n" +
+                        "    }\n" +
+                        "  } " +
+                        "}")
+
+                if (roboTasks.isEmpty()) throw IllegalStateException("Nothing match your filter")
+            }
+        })
+
+        project.task(runTestsTask, closureOf<Task> {
+            group = Constants.FIREBASE_TEST_LAB
+            description = "Run all tests for $variantName in Firebase Test Lab"
+            dependsOn(allRobo, allInstrumentation)
+        })
+
         if (downloader != null) {
             project.task(downloadTask, closureOf<Task> {
                 group = Constants.FIREBASE_TEST_LAB
@@ -309,16 +359,17 @@ internal class FirebaseTestLabPlugin : Plugin<Project> {
             project.logger.lifecycle(result.message)
         } else {
             if (ignoreFailures) {
-                project.logger.error(Constants.ERROR + result.message)
+                project.logger.error("Error: ${result.message}")
             } else {
                 throw GradleException(result.message)
             }
         }
     }
 }
 
-private fun <T1, T2, T3, R> combineAll(l1: Collection<T1>, l2: Collection<T2>, l3: Collection<T3>, func: (T1, T2, T3) -> R): List<R> =
-        l1.flatMap { t1 -> l2.flatMap { t2 -> l3.map { t3 -> func(t1, t2, t3) } } }
+
+private fun <T1, T2, R> combineAll(l1: Collection<T1>, l2: Collection<T2>, func: (T1, T2) -> R): List<R> =
+        l1.flatMap { t1 -> l2.map { t2 -> func(t1, t2)} }
 
 private fun dashToCamelCase(dash: String): String =
         dash.split('-', '_').joinToString("") { it.capitalize() }

plugin/src/main/java/com/appunite/firebasetestlabplugin/cloud/CloudTestResultDownloader.kt

@@ -2,7 +2,6 @@ package com.appunite.firebasetestlabplugin.cloud
 
 import com.appunite.firebasetestlabplugin.FirebaseTestLabPlugin
 import com.appunite.firebasetestlabplugin.model.ResultTypes
-import com.appunite.firebasetestlabplugin.utils.Constants
 import com.appunite.firebasetestlabplugin.utils.asCommand
 import org.gradle.api.GradleException
 import org.gradle.api.logging.Logger
@@ -22,7 +21,7 @@ internal class CloudTestResultDownloader(
             return
         }
         val gCloudFullPath = "$gCloudBucketName/$gCloudDirectory"
-        logger.lifecycle(Constants.DOWNLOAD_PHASE + "Downloading results from $gCloudFullPath")
+        logger.lifecycle("DOWNLOAD: Downloading results from $gCloudFullPath")
 
         prepareDownloadDirectory()
         downloadTestResults()