# AgpTestSuite
[View Source](https://cs.android.com/search?q=file:com/android/build/api/dsl/AgpTestSuite.kt+class:com.android.build.api.dsl.AgpTestSuite) Added in 9.6.0-alpha03
```
@Incubating
interface AgpTestSuite : TestSuite
```
*** ** * ** ***
A test suite that runs with the Android Gradle Plugin.
An `https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuite` can run against a single or multiple variants. Users should use `https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuite#targetVariants()` to identify the final list of variants that will be tested.
Although this is not strictly necessary, if the test suite has source code, it will be recompiled for each variant it targets. This is to ensure the compatibility of the test suite with each variant individually.
Defines how different types of source files are organized and declared for a test suite within the Android Gradle Plugin. Test suites can incorporate various kinds of sources, each serving a distinct purpose and following specific conventions.
All sources for a given test suite (e.g., one named `myTestSuite`) are typically organized under the `src/myTestSuite/` directory, relative to the module's root. Within this directory, specific source types will reside in conventional subdirectories.
Three primary types of sources can be associated with a test suite using the methods on this interface:
1. **Asset Test Sources (configured via `assets`)**:
- **Content**: A single folder containing static files like XML, JSON, or other declarative resources that describe or support tests. These files are not compiled.
- **Purpose**: Typically interpreted directly by test execution engines (e.g., JUnit).
- **Default Location** : `src//` if it's the only source type in the suite, or `src//assetsTest/` if the suite is mixed (contains multiple source types).
2. **Host Test Sources (configured via `hostJar`)**:
- **Content**: A single folder containing compilable source code (e.g., Kotlin or Java) intended for tests that run on the host machine (JVM).
- **Purpose**: Compiled before test execution. The compiled classes are then used by test engines.
- **Default Location** : `src//` (containing `java/`, `kotlin/`, `resources/`) if it's the only source type, or `src//test/` if the suite is mixed.
3. **Device Test Sources (configured via `testApk`)**:
- **Content** : A standard Android source set structure, including compilable source code (Kotlin/Java), Android resources (`res/`), Android assets (`assets/`), and an AndroidManifest.xml file.
- **Purpose**: Compiled into a test APK that runs on an Android device or emulator.
- **Default Location** : `src//` if it's the only source type, or `src//androidTest/` if the suite is mixed.
**Configuration Notes:**
- A test suite can include one or more of these source types. For example, a suite might define both `hostJar` sources and `assets` sources.
- Currently, it is not possible to declare the same type of source (e.g., two `hostJar` blocks) for a single test suite.
- Future versions of this API may introduce more flexibility, such as allowing multiple instances of the same source type or providing ways to customize the default directory names.
Test execution engines can retrieve the locations or outputs of these configured sources through properties defined in `https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuiteInputParameters` (e.g., `STATIC_FILES`, `TEST_CLASSES`, `TEST_APKS`).
## Summary
| ### Public functions |
|---|---|
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html` | `@https://docs.gradle.org/current/javadoc/org/gradle/api/Incubating.html https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuite#assets(kotlin.Function1)(action: https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/TestSuiteAssetsSpec.() -> https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)` Adds an asset folder to this test suite sources, containing static sources like xml, or json files. |
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html` | `@https://docs.gradle.org/current/javadoc/org/gradle/api/Incubating.html https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuite#configureTestTasks(kotlin.Function2)(action: https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/testing/Test.html.(context: https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/TestTaskContext) -> https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)` Configure the test tasks for all targets in this test suite. |
| `https://docs.gradle.org/current/javadoc/org/gradle/api/NamedDomainObjectContainer.html` | `@https://docs.gradle.org/current/javadoc/org/gradle/api/Incubating.html https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuite#getTargets()()` Targets for this test suite, must be manually created in order to provide the variants this test suite applies to. |
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html` | `@https://docs.gradle.org/current/javadoc/org/gradle/api/Incubating.html https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuite#hostJar(kotlin.Function1)(action: https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/TestSuiteHostJarSpec.() -> https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)` Adds a host test folder to this test suite sources, containing kotlin sources that will be compiled. |
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html` | `@https://docs.gradle.org/current/javadoc/org/gradle/api/Incubating.html https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuite#testApk(kotlin.Function1)(action: https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/TestSuiteTestApkSpec.() -> https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)` Adds a device test source folder to this test suite, containing all necessary sources to create an APK. |
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html` | `@https://docs.gradle.org/current/javadoc/org/gradle/api/Incubating.html https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuite#useJunitEngine(kotlin.Function1)(action: https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/JUnitEngineSpec.() -> https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)` Specifies properties for the JUnit test engines to run in this test suite |
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html` | `@https://docs.gradle.org/current/javadoc/org/gradle/api/Incubating.html https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuite#withTestTaskProviders(kotlin.Function2)(action: https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/TaskProvider.html.(context: https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/TestTaskContext) -> https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)` Runs some action on the Variant's device test task's`https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/TaskProvider.html`. |
| ### Public properties |
|---|---|
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuite#codeCoverage()` Turns on or off the code coverage support. |
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuite#requiresUpdateTask()` Whether this test suite requires an extra update task. |
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-mutable-list/index.html` | `https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuite#targetVariants()` Defines which variant this tests suite targets. |
| `https://docs.gradle.org/current/javadoc/org/gradle/api/NamedDomainObjectContainer.html` | `https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuite#targets()` |
| `https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/JUnitEngineSpec` | `https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuite#useJunitEngine()` Spec to identify the test engine that will be used to run this test suite. |
### Inherited properties
From [org.gradle.api.Named](https://docs.gradle.org/current/javadoc/org/gradle/api/Named.html) `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html` `https://docs.gradle.org/current/javadoc/org/gradle/api/Named.html#name`
## Public functions
### assets
Added in 9.6.0-alpha03
```
@Incubating
fun assets(action: TestSuiteAssetsSpec.() -> Unit): Unit
```
Adds an asset folder to this test suite sources, containing static sources like xml, or json files.
The folder will be located at `src//` by default if it's the only source type, or `src//assetsTest/` if the suite is mixed (contains multiple source types).
No compilation of the sources will be performed and the sources files will be provided to the configured junit engines using the `https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuiteInputParameters#STATIC_FILES`
### configureTestTasks
Added in 9.6.0-alpha03
```
@Incubating
fun configureTestTasks(action: Test.(context: TestTaskContext) -> Unit): Unit
```
Configure the test tasks for all targets in this test suite.
There can be one to many instances of `https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/testing/Test.html` tasks for a particular test suite target. For instance, if the test suite targets more than one device, AGP may decide to create one `https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/testing/Test.html` instance per device.
The configuration block can use the `https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuite#configureTestTasks(kotlin.Function2)`'s context parameter to disambiguate between each `https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/testing/Test.html` task instance.
Do not make assumption about how AGP decides to allocate `https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/testing/Test.html` task instances per device, as each AGP version can potentially change it in future release, always use the context object to determine what the `https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/testing/Test.html` task applies to.
| Parameters |
|---|---|
| `action: https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/testing/Test.html.(context: https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/TestTaskContext) -> https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html` | a block to configure the `https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/testing/Test.html` tasks associated with this test suite. |
### getTargets
Added in 9.6.0-alpha03
```
@Incubating
fun getTargets(): NamedDomainObjectContainer
```
Targets for this test suite, must be manually created in order to provide the variants this test suite applies to.
### hostJar
Added in 9.6.0-alpha03
```
@Incubating
fun hostJar(action: TestSuiteHostJarSpec.() -> Unit): Unit
```
Adds a host test folder to this test suite sources, containing kotlin sources that will be compiled.
The folder will be located at `src//` by default if it's the only source type, or `src//test/` if the suite is mixed. It may contain subfolders like 'java', 'kotlin' and 'resources'.
Configured test engines can retrieve the compiled classes using the `https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuiteInputParameters#TEST_CLASSES` property.
### testApk
Added in 9.6.0-alpha03
```
@Incubating
fun testApk(action: TestSuiteTestApkSpec.() -> Unit): Unit
```
Adds a device test source folder to this test suite, containing all necessary sources to create an APK.
The folder will be located at `src//` by default if it's the only source type, or `src//androidTest/` if the suite is mixed.
The sources will be compiled to produce a test APK that can be retrieved by the test engine using the `https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/AgpTestSuiteInputParameters#TEST_APKS` property.
### useJunitEngine
Added in 9.6.0-alpha03
```
@Incubating
fun useJunitEngine(action: JUnitEngineSpec.() -> Unit): Unit
```
Specifies properties for the JUnit test engines to run in this test suite
### withTestTaskProviders
Added in 9.6.0-alpha03
```
@Incubating
fun withTestTaskProviders(action: TaskProvider.(context: TestTaskContext) -> Unit): Unit
```
Runs some action on the Variant's device test task's`https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/TaskProvider.html`.
There can be one to many instances of `https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/testing/Test.html` tasks for a particular test suite target. For instance, if the test suite targets more than one device, AGP may decide to create one `https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/testing/Test.html` instance per device.
This is particularly useful to set manual tasks dependencies. However, you should avoid calling `https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/TaskProvider.html#get--` as it will automatically configure the task even if it is not scheduled to run, instead use the configureTestTask method
Example :
```
androidComponents {
onVariants { variant ->
variant.suites.forEach { suite ->
// eliminate all test suites that requires a device, only hosts tests should be considered.
if (suite.sources.none { source -> source.type == TestSuiteSourceType.TEST_APK }) {
suite.withTestTaskProvider { testTaskProvider ->
someAnchorTask.dependsOn(testTaskProvider)
}
}
}
}
}
```
| Parameters |
|---|---|
| `action: https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/TaskProvider.html.(context: https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/TestTaskContext) -> https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html` | on the test task `https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/TaskProvider.html`. |
## Public properties
### codeCoverage
Added in 9.6.0-alpha03
```
var codeCoverage: Boolean
```
Turns on or off the code coverage support.
By default, the code coverage is disabled.
### requiresUpdateTask
Added in 9.6.0-alpha03
```
var requiresUpdateTask: Boolean
```
Whether this test suite requires an extra update task.
### targetVariants
Added in 9.6.0-alpha03
```
val targetVariants: MutableList
```
Defines which variant this tests suite targets.
### targets
Added in 9.6.0-alpha03
```
val targets: NamedDomainObjectContainer
```
### useJunitEngine
Added in 9.6.0-alpha03
```
val useJunitEngine: JUnitEngineSpec
```
Spec to identify the test engine that will be used to run this test suite. Do not call this method if the test suite should use a dedicated test task. Calling this method will direct AGP to create a `https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/testing/Test.html` task and configure it using the returned `https://developer.android.com/reference/tools/gradle-api/9.6/com/android/build/api/dsl/JUnitEngineSpec`