Instrumented test suites package device tests into isolated
testApk APKs outside your module's default src/androidTest/
directory. Configure them with the Android Gradle plugin (AGP) test
suites DSL to separate UI, integration, or end-to-end checks with
dedicated dependencies, variants, and device targets.
Requirements
To use instrumented 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 - A device or emulator connected through Android Debug Bridge (adb) or a build-managed device definition
For more information about preview version matching, see Compatibility with Android Gradle plugin previews.
Set up an instrumented test suite
To add an instrumented 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 testApk and
useJunitEngine blocks and
AgpTestSuiteInputParameters enum values:
import com.android.build.api.dsl.AgpTestSuiteInputParameters
android {
testOptions {
// Optional: define build-managed virtual devices and device groups.
managedDevices {
localDevices {
create("api34Atd") {
// Use a device profile from Android Studio.
device = "Pixel 6"
apiLevel = 34
systemImageSource = "aosp-atd"
}
}
groups {
create("ciPhones") {
targetDevices.add(allDevices.getByName("api34Atd"))
}
}
}
customSuites {
create("androidSuite") {
targetVariants += listOf("debug")
testApk {
dependencies {
implementation("junit:junit:4.13.2")
implementation("androidx.test.ext:junit:1.2.1")
implementation("androidx.test:runner:1.6.2")
}
}
useJunitEngine {
includeEngines += listOf("android-test-engine")
// Match the engine and listener versions to your AGP
// version.
enginesDependencies.add(
"com.android.tools.androidtest:" +
"android-test-engine:9.6.0-alpha03"
)
enginesDependencies.add(
"com.android.tools.androidtest:" +
"android-test-engine-result-listener:9.6.0-alpha03"
)
enginesDependencies.add(
"org.junit.platform:junit-platform-launcher:1.10.2"
)
inputs += listOf(
// Omit TESTED_APKS in com.android.library modules.
AgpTestSuiteInputParameters.TESTED_APKS,
AgpTestSuiteInputParameters.TEST_APKS,
AgpTestSuiteInputParameters.ADB_EXECUTABLE,
AgpTestSuiteInputParameters.AAPT2_EXECUTABLE,
)
}
targets {
// Runs on connected adb devices.
create("default")
// Optional: runs on build-managed devices or groups in
// targetDevices.
create("managed") {
targetDevices += listOf("ciPhones")
}
}
}
}
}
}
AGP configures the AndroidJUnitRunner test runner and package IDs
automatically without inheriting dependencies from the
androidTestImplementation configuration. To use a custom runner, set the
android:name attribute on the instrumentation element in your
src/{suiteName}/AndroidManifest.xml file.
Create tests
Put your instrumented tests in the {module}/src/{suiteName}/kotlin/ or java/
directory, along with any optional res/ or assets/ directories or an
AndroidManifest.xml file. For example, create the
app/src/androidSuite/kotlin/com/example/myapp/AppContextSuiteTest.kt file:
package com.example.myapp
import androidx.test.ext.junit.runners.AndroidJUnit4
import androidx.test.platform.app.InstrumentationRegistry
import org.junit.Assert.assertEquals
import org.junit.Test
import org.junit.runner.RunWith
@RunWith(AndroidJUnit4::class)
class AppContextSuiteTest {
@Test
fun useAppContext() {
val appContext =
InstrumentationRegistry.getInstrumentation().targetContext
assertEquals("com.example.myapp", appContext.packageName)
}
}
Combine unit and instrumented tests
To run local JVM tests and instrumented device tests in a single Gradle task,
declare both the hostJar and testApk blocks in one suite. Place
host tests in the src/{suiteName}/test/ directory and device tests in the
src/{suiteName}/androidTest/ directory:
import com.android.build.api.dsl.AgpTestSuiteInputParameters
android {
testOptions {
customSuites {
create("combinedSuite") {
targetVariants += listOf("debug")
hostJar {
dependencies {
implementation(
"org.junit.jupiter:junit-jupiter-api:5.10.2"
)
}
}
testApk {
dependencies {
implementation("junit:junit:4.13.2")
implementation("androidx.test.ext:junit:1.2.1")
implementation("androidx.test:runner:1.6.2")
}
}
useJunitEngine {
includeEngines += listOf(
"junit-jupiter",
"android-test-engine",
)
enginesDependencies.add(
"org.junit.jupiter:junit-jupiter-engine:5.10.2"
)
enginesDependencies.add(
"com.android.tools.androidtest:" +
"android-test-engine:9.6.0-alpha03"
)
enginesDependencies.add(
"com.android.tools.androidtest:" +
"android-test-engine-result-listener:9.6.0-alpha03"
)
enginesDependencies.add(
"org.junit.platform:junit-platform-launcher:1.10.2"
)
inputs += listOf(
// Omit TESTED_APKS in com.android.library modules.
AgpTestSuiteInputParameters.TESTED_APKS,
AgpTestSuiteInputParameters.TEST_APKS,
AgpTestSuiteInputParameters.ADB_EXECUTABLE,
AgpTestSuiteInputParameters.AAPT2_EXECUTABLE,
)
}
targets {
create("default")
}
}
}
}
}
Run tests and collect coverage
Use Gradle to run instrumented suites, filter test cases, and generate coverage reports.
Run on connected or build-managed devices
Run a connected target on every online adb device, or run a target configured
with the targetDevices property:
# Run on connected adb devices. ./gradlew :app:testDebugAndroidSuiteDefaultTestSuite# Run on the ciPhones build-managed device group. ./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite
Filter instrumented tests
Filter tests with Gradle's --tests option
or AndroidJUnitRunner arguments:
./gradlew :app:testDebugAndroidSuiteDefaultTestSuite \
--tests "com.example.myapp.AppContextSuiteTest.useAppContext"You can also pass AndroidJUnitRunner arguments on the command line with a
project property such as
-Pandroid.testInstrumentationRunnerArguments.size=small. To set default runner
arguments in the useJunitEngine block, call the addInputProperty method,
such as addInputProperty("android-test.instrumentation-args", "size=small").
Collect on-device code coverage
On-device code coverage requires a debuggable build and a device that runs Android 9 (API level 28) or higher. To collect coverage for an instrumented or mixed suite, complete the following steps:
- Set the
android.experimental.androidTest.coverage.useOnDeviceAgent=trueproperty in yourgradle.propertiesfile. - Set the
codeCoverageproperty totrueon the suite. - If multiple devices are connected, target one device with the
ANDROID_SERIALenvironment variable.
For more information about agent requirements, see View code coverage reports (with on-device agent).
Inspect reports
After a test run completes, AGP generates outputs at the following paths:
- HTML test report:
{module}/build/reports/tests/{taskName}/index.html - JUnit XML results:
{module}/build/test-results/{taskName}/ - Per-device XML and logcat:
{module}/build/intermediates/{variant}/{taskName}/results/ - Code coverage report:
{module}/build/reports/coverage/{suiteName}/index.html