A Gradle plugin that allows for the execution of JUnit 5 tests in Android environments using Android Gradle Plugin 3.0.0 or later.
The JUnit Platform team provides a Gradle plugin for running JUnit 5 on the JVM. However,
that plugin is tailored to the needs of a "purely Java" application, and doesn't work in
the context of the multi-variant world that we live in on Android. As a result, android-junit5
was born.
This plugin configures a junitPlatformTest
task for each registered build variant of a project.
Furthermore, it automatically attaches both the Jupiter & Vintage Engines
during the execution phase of your tests as well, so there's very little configuration
necessary to get your project up-and-running on the JUnit Platform.
Instructions on how to write JUnit 5 tests can be found in their User Guide. Furthermore, this repository provides a small showcase of the functionality provided by JUnit 5 here.
buildscript {
dependencies {
classpath "de.mannodermaus.gradle.plugins:android-junit5:1.0.31"
}
}
Snapshots of the development version are available through Sonatype's snapshots
repository.
apply plugin: "com.android.application"
apply plugin: "de.mannodermaus.android-junit5"
dependencies {
// (Required) Writing and executing Unit Tests on the JUnit Platform.
testImplementation junit5.unitTests()
// (Optional) If you need "Parameterized Tests".
testImplementation junit5.parameterized()
// (Optional) For running tests inside Android Studio 3
// Please refer to the "Android Studio Workarounds" section for more insight on this.
testCompileOnly junit5.unitTestsRuntime()
// (Optional) Writing and executing Instrumented Tests with the JUnit Platform Runner.
//
// IMPORTANT:
// By declaring this dependency, you have to use a minSdkVersion
// of at least 26, since the nature of JUnit 5 relies on APIs that aren't
// available on Android devices before then.
// Consider creating a product flavor for this - see the sample project for details.
androidTestImplementation junit5.instrumentationTests()
}
The plugin extends your module's android.testOptions
with more options, wrapped in a container called junitPlatform
.
Inside it, you can use all properties available through the default JUnit 5 Gradle plugin.
Additionally, there are a few more parameters that allow for more customization of the JUnit Platform
in your Android project. These are detailed below, alongside their default values:
android.testOptions {
// Configuration closure added by the plugin;
// all configurable parameters related to JUnit 5 can be found here
junitPlatform {
// The JUnit Jupiter dependency version to use
jupiterVersion "5.0.3"
// The JUnit Vintage Engine dependency version to use
vintageVersion "4.12.2"
// Options related to running unit tests with JUnit 5.
unitTests.all { test ->
// Configure custom jvmArgs, system properties and environment variables
jvmArgs "--my-argument"
systemProperty "my.system.property", "true"
environment "MY_ENVIRONMENT", "development"
}
// Options related to running instrumented tests with JUnit 5.
// This is an incubating feature which utilizes the backwards-compatibility
// of the JUnit Platform in order to enhance the default Test Instrumentation Runner
// with new power. As of version 1.0.31, instrumentation test support is provided by default,
// but it's up to you to include the JUnit 5 dependencies and write some tests with it.
instrumentationTests {
// Enable instrumentation tests (default: true)
enabled true
// The Android-Instrumentation-Test dependency version to use (default: latest)
version "0.2.1"
}
// Configuration of companion tasks for JaCoCo Reports,
// associated with each JUnit 5 task generated by the plugin.
// Just like the companion tasks themselves, these properties
// will only have an effect if your module declares the "jacoco" plugin as well.
// For each of the available report types, you can toggle the availability
// and destination folders that they write to.
jacocoOptions {
// Additional exclusion rules for Code Coverage Reports -
// by default, R.class & BuildConfig.class are excluded.
excludedClasses += []
excludedSources += []
// By default, Jacoco tasks will be generated by the plugin
// if the project also applies the Jacoco plugin.
// To disable completely, use this flag
taskGenerationEnabled = true
// If instead, you want to generate Jacoco tasks only for certain variants,
// this can be specified here. By default, tasks are generated for all variants
onlyGenerateTasksForVariants "debug", "release"
// Configuration for generated Code Coverage reports
xml {
enabled true
destination project.file()
}
html {
enabled true
destination project.file()
}
csv {
enabled true
destination project.file()
}
}
}
}
All versions up to Android Studio 3.1 Canary 6 are built on a version of IntelliJ IDEA that depends on outdated JUnit 5 APIs. Therefore, your tests will fail with an Exception similar to the following when you try to launch your tests from inside the IDE (using an Android JUnit Run Configuration):
Exception in thread "main" java.lang.NoSuchMethodError: org.junit.platform.launcher.Launcher.execute(Lorg/junit/platform/launcher/LauncherDiscoveryRequest;)V
at com.intellij.junit5.JUnit5IdeaTestRunner.startRunnerWithArgs(JUnit5IdeaTestRunner.java:42)
...
To work around this, there is a separate dependency you can add to the test scope of your project in Android Studio 3. It provides its own copy of the JUnit 5 Runtime provided by a more recent build of IntelliJ, overriding the one embedded in Android Studio.
To use this, add the following line alongside the other junit5
dependencies:
dependencies {
testCompileOnly junit5.unitTestsRuntime()
}
The plugin's minimum required version of Gradle has increased over time to maximize its leverage with new APIs and performance. The chart describes the evolution of this requirement. If you can't use the latest version of this plugin due to your project's Gradle version, please refer to the following table to find the corresponding plugin that works for you.
Plugin Version | Minimum Gradle Version |
---|---|
1.0.30 | 2.5 |
1.0.31 | 4.3 |
Copyright 2000-2016 JetBrains s.r.o.
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.
See also the full License text.
Copyright 2017-2018 Marcel Schnelle
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.
See also the full License text.