Unit test suites run local JVM tests in isolated hostJar source
sets outside your module's default src/test/ directory. Configure them with
the Android Gradle plugin (AGP) test suites DSL to isolate JUnit
5, JUnit 4, or Robolectric tests per variant.
Requirements
To use unit test suites, make sure that your project meets the following requirements:
- Android Studio Rabbit 3 Canary 3 or higher
- AGP 9.6.0-alpha03 or higher
- Gradle 9.7.1 or higher and JDK 17 or higher
- A
com.android.applicationorcom.android.librarymodule
For more information about preview version matching, see Compatibility with Android Gradle plugin previews.
Set up a unit test suite
To add a unit test suite to an app or library module, complete the following steps:
Enable test suites
In your project's gradle.properties file, enable test suite support:
android.experimental.testSuiteSupport=true
Configure the suite
In your module's build.gradle.kts file, create a suite inside the
testOptions.customSuites block with the hostJar and
useJunitEngine blocks:
android {
testOptions {
customSuites {
create("unitSuite") {
// Exact variant names to test, such as "debug" or "demoDebug".
targetVariants += listOf("debug")
hostJar {
dependencies {
// JUnit 5 API for @org.junit.jupiter.api.Test.
implementation(
"org.junit.jupiter:junit-jupiter-api:5.10.2"
)
// Optional: JUnit 4 API for @org.junit.Test.
implementation("junit:junit:4.13.2")
}
}
useJunitEngine {
// Add "junit-jupiter" (JUnit 5), "junit-vintage" (JUnit 4),
// or both.
includeEngines += listOf("junit-jupiter", "junit-vintage")
enginesDependencies.add(
"org.junit.jupiter:junit-jupiter-engine:5.10.2"
)
enginesDependencies.add(
"org.junit.vintage:junit-vintage-engine:5.10.2"
)
enginesDependencies.add(
"org.junit.platform:junit-platform-launcher:1.10.2"
)
}
targets {
create("default")
}
}
}
}
}
Your suite accesses the target variant's classes and dependencies automatically
without inheriting dependencies from the testImplementation configuration.
Create tests
Put your unit tests in the {module}/src/{suiteName}/kotlin/ or java/
directory and Java test resources in the {module}/src/{suiteName}/resources/
directory. For example, create the
app/src/unitSuite/kotlin/com/example/myapp/CalculatorSuiteTest.kt file:
package com.example.myapp
import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Test
class CalculatorSuiteTest {
@Test
fun addition_isCorrect() {
assertEquals(4, 2 + 2)
}
}
Include Android resources and Robolectric
To access merged Android resources, assets, manifests, and R classes, such as
for Robolectric tests, set the
enableAndroidResources property of the
TestSuiteHostJarSpec interface to true:
android {
testOptions {
customSuites {
create("roboSuite") {
targetVariants += listOf("debug")
hostJar {
enableAndroidResources = true
dependencies {
implementation("junit:junit:4.13.2")
implementation("org.robolectric:robolectric:4.14.1")
implementation("androidx.test:core-ktx:1.6.1")
}
}
useJunitEngine {
includeEngines += listOf("junit-vintage")
enginesDependencies.add(
"org.junit.vintage:junit-vintage-engine:5.10.2"
)
enginesDependencies.add(
"org.junit.platform:junit-platform-launcher:1.10.2"
)
}
targets {
create("default")
}
}
}
}
}
Customize tasks and coverage
Enable JaCoCo coverage on a suite with the codeCoverage
property. To customize Gradle Test options per target, pass a configuration
lambda to the AgpTestSuiteTarget.configureTestTasks
method, which provides a TestTaskContext instance. To
attach verification tasks to the check task, use the
withTestTaskProviders method:
android {
testOptions {
customSuites {
named("unitSuite") {
// Generates JaCoCo HTML and XML coverage reports.
codeCoverage = true
targets.named("default") {
configureTestTasks { context ->
systemProperty("suite.variant", context.targetedVariant)
maxParallelForks = 2
}
}
withTestTaskProviders { context ->
if (!context.isUpdateTask) {
tasks.named("check") {
dependsOn(this@withTestTaskProviders)
}
}
}
}
}
}
}
To apply Test task settings across every target in a suite, call the
AgpTestSuite.configureTestTasks method on the suite
instead.
Run tests and inspect reports
Run your suite from the command line with the generated
test{Variant}{SuiteName}{Target}TestSuite task:
./gradlew :app:testDebugUnitSuiteDefaultTestSuiteTo run a single test class or method, pass Gradle's
--tests option:
./gradlew :app:testDebugUnitSuiteDefaultTestSuite \
--tests "com.example.myapp.CalculatorSuiteTest.addition_isCorrect"After a test run completes, AGP generates reports at the following paths:
- HTML test report:
{module}/build/reports/tests/{taskName}/index.html - JUnit XML results:
{module}/build/test-results/{taskName}/ - JaCoCo coverage report:
{module}/build/reports/coverage/{suiteName}/index.html