composer-gradle-plugin

Gradle task type and plugin for running gojuno/composer from gradle.

Installation & Usage

In the appropriate build.gradle file add the jitpack repository and classpath dependency.

buildscript {
    repositories {
        maven { url "https://jitpack.io" }
    }
    dependencies {
        classpath 'com.github.trevjonez.composer-gradle-plugin:plugin:0.9.0'
    }
}

This repo can be consumed in two ways, via a android variant aware plugin or as a pre-provided task type.

Plugin Usage

apply plugin: 'composer'

The above should be all you need to get started and will create a task for each testable variant in the project.

The tasks that are created will be of the form testFlavorTypeComposer

If you want to limit the variants that get tasks or provide custom configuration you can do so via the composer DSL block:

composer {
  variants "redDebug" // optional, variant names to create composer tasks for. If empty all testable variants will receive a task.
  
  //These dsl functions are combined with variant specific config additively
  instrumentationArgument('key1', 'value1') 
  instrumentationArgument('key2', 'value2')
  instrumentationArgument('keyN', 'valueN')
  
  device 'emulator-5558'
  devices(['emulator-5558', 'emulator-5559'])
      
  //These dsl functions are overwritten by variant specific config if any exists
  withOrchestrator true
  shard false
  verboseOutput false
  keepOutput true
  devicePattern 'somePattern'
  apkInstallTimeout 90
 

  configs { 
    redDebug {
      apk "build/outputs/apk/debug/example-debug.apk" //optional override, string paths are evaluated as per {@link org.gradle.api.Project#file(Object)}.
      testApk = new File(buildDir, "outputs/apk/androidTest/debug/example-debug-androidTest.apk") //optional override
      outputDirectory 'artifacts/composer-output' //optional override. default 'build/reports/composer/redDebug'
      withOrchestrator false // optional, default false
      shard true //optional. default true
      instrumentationArgument('key1', 'value1') //optional, additive
      instrumentationArgument('key2', 'value2')
      instrumentationArgument('keyN', 'valueN')
      verboseOutput false //optional default false
      keepOutput true //optional, default false
      device 'emulator-5554' //optional, additive
      device 'emulator-5558'
      devices(['emulator-5554', 'emulator-5558']) //optional, additive
      devicePattern 'somePattern' //optional
      apkInstallTimeout 90 //optional, timeout in seconds default 120
    }
  }
}

Core Usage

Manual task creation looks something like this:

task customTaskName(type: ComposerTask) {
  apk "build/outputs/apk/example-debug.apk" //required
  testApk "build/outputs/apk/example-debug-androidTest.apk" //required
  withOrchestrator true // optional
  shard true //optional
  outputDirectory 'artifacts/composer-output' //optional
  instrumentationArgument('key1', 'value1') //optional
  instrumentationArgument('key2', 'value2')
  instrumentationArgument('keyN', 'valueN')
  verboseOutput false //optional
  device 'emulator-5554' //optional
  device 'emulator-5558'
  devices('emulator-5554', 'emulator-5558') //optional
  devicePattern 'somePattern' //optional
  apkInstallTimeout 90 //optional
}

Advanced Configuration

Instrumentation Arguments

In some cases you may want to only run a sub set of tests or filter based on annotations etc. Composer already supports passing custom arguments to the instrumentation runner and the configuration DSL for both core and plugin use cases can take advantage of that.

Lets say you want to add the ability to pass gradle a property for a class name to run:

composer {
  if(project.hasProperty("composerClassTarget")) {
    instrumentationArgument('class', project.getProperty("composerClassTarget"))
  }
}

Invocation should look something like this:

./gradlew app:testCiDebugComposer -PcomposerClassTarget=com.foo.your.test.FullClassName

Another common use case is to always have the test runner ignore tests that should not be ran by handled by composer. An example of this would be to ignore Kontrast screenshot tests:

composer {
  instrumentationArgument('notAnnotation', 'com.trevjonez.kontrast.KontrastTest')
}

When you use it with Orchestrator you may want to enable clearPackageData, you can do it adding an instrumentationArgument like this:

composer {
  withOrchestrator true
  instrumentationArgument("clearPackageData","true")
}

As always I recommend you read the wealth of information available on d.android.com.

Or specifically the documentation for InstrumentationTestRunner

Dependency Configuration

If you need to use a different version of the composer jar than this plugin uses by default, you can modify the composer configuration with normal gradle strategies.

The composer configuration is automatically added to your project once a ComposerTask has been created or the plugin has been applied to the project.

dependencies {
 composer "com.gojuno.composer:composer:0.5.0"
}

Notes on Compatibility

The plugin is developed against specific version of gradle and the android gradle plugin. In most cases using the latest version of gradle is safe but the minimum supported version of gradle is 4.0 or whatever minimum is mandated by the android gradle plugin.

Composer plugin version	Gradle version	Android plugin version
0.8.1	4.10	3.2.0
0.9.0	4.10	3.2.1

License

Copyright 2017 Trevor Jones

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.