Instrumented test suites

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.application or com.android.library module
  • 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:

  1. Set the android.experimental.androidTest.coverage.useOnDeviceAgent=true property in your gradle.properties file.
  2. Set the codeCoverage property to true on the suite.
  3. If multiple devices are connected, target one device with the ANDROID_SERIAL environment 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