Test suites in the Android Gradle plugin

The Android Gradle plugin (AGP) lets you organize tests into named test suites in your module's testOptions block. Each suite defines its own source sets, dependencies, JUnit Platform test engines, and target build variants.

Why use test suites

By default, an Android module provides one test source set for local unit tests and one androidTest source set for instrumented tests. Test suites decouple test organization from those two source sets so that you can do the following:

  • Separate tests by purpose: Keep unit, Robolectric, UI, screenshot, and backup tests in dedicated src/{suiteName}/ directories instead of mixing them in the src/test/ or src/androidTest/ directories.
  • Isolate dependencies and engines: Configure each suite's classpath and JUnit Platform test engine without adding dependencies to your app or the testImplementation and androidTestImplementation configurations.
  • Target specific variants and devices: Select build variants and devices per suite so that fast checks run locally and longer suites run in continuous integration.

Suite types

AGP includes built-in test suites for specialized workflows and the AgpTestSuite interface for custom suites. The following table lists the available suite types:

Suite type DSL container Purpose
Unit test suites testOptions.customSuites Run JUnit 5, JUnit 4, or Robolectric tests on the local JVM with the hostJar block.
Instrumented test suites testOptions.customSuites Run device tests on connected or build-managed devices with the testApk block and the android-test-engine test engine.
Screenshot testing with test suites testOptions.screenshotTests Render and compare @PreviewTest Compose previews on the host.
Automated backup and restore testing testOptions.backupTests Verify app data across local, cloud, and device-to-device transfers.
Journeys for Android Studio testOptions.customSuites Run AI-driven XML user journeys on connected devices.
Custom asset or mixed suites testOptions.customSuites Run static test definitions with a custom engine or combine the hostJar, testApk, and assets blocks in one suite.

Requirements

To use custom 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

Test suites aren't supported in com.android.kotlin.multiplatform.library or com.android.test modules. For more information about preview version matching, see Compatibility with Android Gradle plugin previews.

Set up a custom test suite

For step-by-step setup guides, see Unit test suites and Instrumented test suites. To define your own custom suite, first enable test suites in your project's gradle.properties file:

android.experimental.testSuiteSupport=true

Next, declare a suite in the testOptions.customSuites block of your module's build.gradle.kts file. Specify the targetVariants property, one or more source blocks, the useJunitEngine block, and at least one target in the targets block:

import com.android.build.api.dsl.AgpTestSuiteInputParameters

android {
    testOptions {
        customSuites {
            create("mySuite") {
                // Exact variant names to test, such as "debug" or "demoDebug".
                targetVariants += listOf("debug")

                // Add one or more blocks: hostJar {}, testApk {}, or assets {}.
                assets {}

                useJunitEngine {
                    includeEngines += listOf("my-custom-engine")
                    enginesDependencies.add(
                        "com.example:my-custom-junit-engine:1.0.0"
                    )
                    enginesDependencies.add(
                        "org.junit.platform:junit-platform-launcher:1.10.2"
                    )

                    // Request build and SDK artifacts read by your engine.
                    inputs += listOf(
                        AgpTestSuiteInputParameters.STATIC_FILES,
                        // Omit TESTED_APKS in com.android.library modules.
                        AgpTestSuiteInputParameters.TESTED_APKS,
                        AgpTestSuiteInputParameters.ADB_EXECUTABLE,
                    )
                }

                targets {
                    create("default")
                }
            }
        }
    }
}

Inside a custom TestEngine implementation, use the TestSuiteExecutionClient.default property to read AgpTestSuiteInputParameters enum values and standard TestEngineInputProperty constants such as SERIAL_IDS and RESULTS_DIR.

Source set directories

Each suite's directory layout depends on whether it declares one source block or combines multiple source blocks. The following table lists the default paths under the {module}/src/{suiteName}/ directory:

Source block Single-source suite Mixed suite
hostJar kotlin/, java/, resources/ test/kotlin/, test/java/, test/resources/
testApk kotlin/, java/, res/, assets/, AndroidManifest.xml androidTest/kotlin/, androidTest/java/, androidTest/res/, androidTest/assets/, androidTest/AndroidManifest.xml
assets Suite root directory assetsTest/

Don't reuse built-in source set, flavor, build type, or variant names such as main, androidTest, or debug as a suite name.

Control targets per variant

To enable or disable a suite target for specific variants, configure the TestSuiteTargetBuilder interface through the HasTestSuitesBuilder.suites property in the beforeVariants block:

androidComponents {
    beforeVariants { variantBuilder ->
        if (variantBuilder.buildType == "release") {
            variantBuilder.suites["mySuite"]
                ?.targets
                ?.get("default")
                ?.enable = false
        }
    }
}

Run suites and inspect reports

AGP creates a Gradle task for each combination of variant, suite, and target. The following table lists the task patterns:

Task type Naming pattern Example command
Standard suite target test{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:testDebugMySuiteDefaultTestSuite
Target with the targetDevices property test{Variant}{SuiteName}{Target}{Devices}TestSuite ./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite
Baseline update (requiresUpdateTask = true) update{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:updateDebugScreenshotTestDefaultTestSuite
Module report aggregation testAllSuites ./gradlew :app:testAllSuites
Module and dependency aggregation testAllSuitesWithDependencies ./gradlew :app:testAllSuitesWithDependencies

The test, connectedCheck, and check tasks don't run custom suites unless you wire them with the withTestTaskProviders method. To enable the testAllSuites and testAllSuitesWithDependencies tasks, set the android.experimental.reportAggregationSupport=true property in your gradle.properties file.

Each suite run writes outputs to the following locations:

  • HTML test report: {module}/build/reports/tests/{taskName}/index.html
  • JUnit XML results: {module}/build/test-results/{taskName}/
  • Code coverage report: {module}/build/reports/coverage/{suiteName}/index.html
  • Aggregated reports: {module}/build/reports/{aggregationTask}/test-report/index.html and coverage-report/index.html

To generate code coverage reports, set the codeCoverage property to true on the suite. For Compose screenshot suites, configure the suite in your build.gradle.kts file with testOptions.customSuites.named("{suiteName}") { codeCoverage = true }.

Known issues and limitations

Test suites have the following limitations:

  • IDE integration: Android Studio support for custom test suites isn't available. The code editor might show unresolved reference errors in suite source files even when your build is configured properly. Build and run test suites from the command line using Gradle instead.
  • Task caching: Test suite tasks always rerun when invoked and aren't loaded from the Gradle build cache. Suites with no test files are skipped with the NO-SOURCE status.