organizing-test-source-sets

Organizing Test Source Sets — src/test/, src/androidTest/, and the KMP Split

Where a test file lives determines which JVM runs it, which dependencies it sees, and whether it ships in the test APK. Most modules need only src/test/ and src/androidTest/. Modules that share helpers between host and device tests historically used src/sharedTest/ (a Codelab convention, not Google-documented as such), which broke on AGP 7.2+ and pushed Compose itself to the KMP-style androidHostTest / androidDeviceTest split. This skill encodes the matrix so the agent can place a test file with confidence.

When to use this skill

The user asks "where do I put my tests" or "src/test/ or src/androidTest/".
The user asks "what's testImplementation vs androidTestImplementation vs debugImplementation".
The user reports Unresolved reference: createComposeRule and the agent suspects the dependency is on the wrong configuration.
The user is migrating off src/sharedTest/ after AGP 7.2+ broke their sourceSets { test.java.srcDir(...) } block.
The user mentions androidHostTest / androidDeviceTest and asks how to set them up in a non-KMP module.
The user asks "why is my Robolectric test in src/androidTest/" — it should be in src/test/.

When NOT to use this skill

The user is wiring Gradle dependencies for Compose test (ui-test-junit4, ui-test-manifest) — use ../../../compose/setup/configuring-test-dependencies/SKILL.md.
The user is choosing test scope (small/medium/big) — use ../../concepts/understanding-the-testing-pyramid/SKILL.md.
The user is configuring AndroidJUnitRunner itself — use ../../../instrumentation/runner/running-instrumented-tests-with-androidjunit4/SKILL.md.
The user is configuring a JUnit4 runner for JVM tests — use ../../../jvm-tests/runner/configuring-junit4-on-android/SKILL.md.

Prerequisites

A module with the Android Gradle Plugin (com.android.application or com.android.library).
Familiarity with Gradle configuration names (testImplementation, androidTestImplementation, debugImplementation).
An understanding that JVM tests run on the host's JVM and instrumented tests run on a device/emulator. (See ../../concepts/understanding-the-testing-pyramid/SKILL.md.)

The two source sets Google documents

`src/test/` — local JVM tests

Per /training/testing/local-tests:

"By default, the source files for local unit tests are placed in module-name/src/test/. This directory already exists when you create a new project using Android Studio." — developer.android.com/training/testing/local-tests

"A local test runs directly on your own workstation, rather than an Android device or emulator. As such, it uses your local Java Virtual Machine (JVM)." — developer.android.com/training/testing/local-tests

Driven by testImplementation. Runs via ./gradlew test or ./gradlew testDebugUnitTest. No Android device, no emulator. The Android framework is unavailable unless Robolectric simulates it.

`src/androidTest/` — instrumented tests

Per /training/testing/instrumented-tests:

"In your Android Studio project, you store the source files for instrumented tests in module-name/src/androidTest/java/. This directory already exists when you create a new project and contains an example instrumented test." — developer.android.com/training/testing/instrumented-tests

Driven by androidTestImplementation. Runs via ./gradlew connectedAndroidTest or ./gradlew connectedDebugAndroidTest. Requires a connected device or emulator. Uses AndroidJUnitRunner per CORPUS §H.2.

The page is also explicit on the testImplementation vs androidTestImplementation split:

"Note: testImplementation adds dependencies for local tests and androidTestImplementation adds dependencies for Instrumented tests." — developer.android.com/training/testing/local-tests

The configuration matrix

Configuration                Source set        Variant       Ships in
-----------------------------------------------------------------------------------
implementation               main              all           release + debug + tests
api                          main              all           release + debug + tests
debugImplementation          debug only        debug         debug APK + androidTest APK
releaseImplementation        release only      release       release APK only
testImplementation           src/test/         all (host)    JVM test classpath
testDebugImplementation      src/test/         debug (host)  JVM test classpath, debug only
androidTestImplementation    src/androidTest/  all (device)  androidTest APK
androidTestUtil              n/a               all           orchestrator/util install (NOT classpath)

Three configurations the agent must keep straight:

testImplementation — JVM (host) tests. Includes Mockito, MockK, Robolectric, kotlinx-coroutines-test, Turbine.
androidTestImplementation — instrumented (device) tests. Includes Espresso, UiAutomator, AndroidJUnitRunner, Compose ui-test-junit4.
debugImplementation — main debug variant. Used by androidx.compose.ui:ui-test-manifest and androidx.fragment:fragment-testing-manifest because the test APK is built on top of the debug APK and needs the manifest entries merged in.

androidx.compose.ui:ui-test-manifest MUST go on debugImplementation, not androidTestImplementation — see ../../../compose/setup/configuring-test-dependencies/SKILL.md for the lint check (TestManifestGradleConfiguration) that enforces this.

`src/sharedTest/` — community convention, NOT Google-documented

Per tasks/research/R8-android-fundamentals.md:

src/sharedTest/ is not mentioned by name on any of the six in-scope developer.android.com/training/testing/... pages or on the fetched Hilt-testing / rules pages.

It originated in Google's own Architecture Blueprints sample and the Advanced Android Testing Codelab. The pattern uses Gradle sourceSets to inject the same Java/Kotlin folder into BOTH test and androidTest:

// pre-AGP 7.2 — the classic sharedTest wiring
android {
    sourceSets {
        getByName("test").java.srcDir("src/sharedTest/java")
        getByName("androidTest").java.srcDir("src/sharedTest/java")
    }
}

Why it existed: write a test once, run it as a fast Robolectric host test in CI and as a high-fidelity instrumented test on emulator. The test class uses androidx.test.ext.junit.runners.AndroidJUnit4 (which dispatches correctly in both environments per CORPUS §G.6).

Why it broke: AGP 7.2+ enforces that the same source directory cannot be shared across multiple source sets at build time — the build itself refuses, with an error pointing at the duplicated srcDir(...) call. (The mode of failure is build-time refusal in AGP, not a runtime LinkageError.) Tracked at https://github.com/robolectric/robolectric/issues/7432 (Robolectric maintainer thread, with reproductions and AGP-version table). Many modules either:

Stopped sharing tests and accepted duplication.
Migrated to a separate Gradle sub-module (:core-testing) that ships test helpers via testImplementation and androidTestImplementation.
Adopted KMP-style source set names (androidHostTest / androidDeviceTest).

KMP-style `androidHostTest` / `androidDeviceTest`

Compose UI tests internally use this layout, per CORPUS §C ("Source set conventions (KMP)"):

commonTest
└── androidCommonTest          (helpers shared by host + device)
    ├── androidDeviceTest      (instrumentation APK on emulator/device)
    └── androidHostTest        (Robolectric on JVM)

Real androidx evidence: compose/ui/ui-test/src/androidHostTest/kotlin/androidx/compose/ui/test/RobolectricComposeTest.kt is a host (Robolectric) test, while compose/material3/material3/src/androidDeviceTest/.../SwitchTest.kt is a device test. Both compile against commonTest for shared helpers.

For non-KMP Android-only modules, the same effect can be approximated with separate sub-modules:

// :feature:home/build.gradle.kts — production module
plugins { id("com.android.library") }

dependencies {
    testImplementation(project(":feature:home-testing"))
    androidTestImplementation(project(":feature:home-testing"))
}

// :feature:home-testing/build.gradle.kts — pure Kotlin or Android-library "test fixtures"
plugins { id("java-library") }   // or com.android.library if Android types needed

The :feature:home-testing module hosts FakeUserRepository, MainDispatcherRule, custom matchers — anything both host and device tests want.

Alternative: AGP 7.0+ testFixtures flag (android { testFixtures { enable = true } }), which exposes testFixtures() Gradle artifacts for testFixturesImplementation and is consumable from sibling modules' testImplementation / androidTestImplementation.

MUST NOT cite developer.android.com/training/testing/... for sharedTest — none of those pages document it. MUST cite the Architecture Blueprints repo or tasks/research/R8-android-fundamentals.md instead.

File placement decision tree

Where does this test go?
│
├── Pure Kotlin/JVM logic, no Android framework      → src/test/
│   (testImplementation deps)
│
├── Robolectric (Android framework simulated on JVM) → src/test/
│   (testImplementation deps + Robolectric)
│   NOT src/androidTest/.
│
├── ViewModel + coroutines + fakes                   → src/test/
│
├── Real Room database integration                    → src/androidTest/
│   (small instrumented test per /fundamentals)
│
├── Espresso UI test                                  → src/androidTest/
├── UiAutomator cross-app test                        → src/androidTest/
├── Compose UI test against real Activity            → src/androidTest/
│   + debugImplementation("...:ui-test-manifest")
│
├── Compose UI test on Robolectric                    → src/test/
│   (testImplementation("...:ui-test-junit4") + Robolectric)
│
├── Test helper (FakeRepository, MainDispatcherRule)  → :core-testing module OR src/sharedTest/
│   (with the AGP 7.2+ caveats above)

Patterns

Pattern: WRONG vs RIGHT — `testImplementation` vs `androidTestImplementation`

// WRONG — Espresso on testImplementation
dependencies {
    testImplementation("androidx.test.espresso:espresso-core:3.7.0")
    testImplementation("androidx.test.ext:junit:1.3.0")
}
// WRONG because: Espresso requires a real or simulated Android device. testImplementation
// only puts the JAR on the JVM classpath. The test compiles but ClassNotFoundException /
// IllegalStateException at runtime when Espresso looks for an Instrumentation instance.

// RIGHT — Espresso on androidTestImplementation
dependencies {
    androidTestImplementation("androidx.test.espresso:espresso-core:3.7.0")
    androidTestImplementation("androidx.test.ext:junit:1.3.0")
}

Pattern: WRONG vs RIGHT — Robolectric in `src/androidTest/`

// WRONG
// src/androidTest/java/com/example/SomeRobolectricTest.kt
@RunWith(RobolectricTestRunner::class)
class SomeRobolectricTest { /* ... */ }
// WRONG because: Robolectric is a JVM Android simulator (per /fundamentals: "Big local test:
// You can use an Android simulator that runs locally, such as Robolectric"). It belongs in
// src/test/. Putting it in src/androidTest/ either fails to find Robolectric (which is on
// testImplementation) or runs it on the device JVM where its shadow mechanism does not work.

// RIGHT
// src/test/java/com/example/SomeRobolectricTest.kt
@RunWith(AndroidJUnit4::class)         // dispatches to Robolectric on JVM
@Config(sdk = [Build.VERSION_CODES.UPSIDE_DOWN_CAKE])
class SomeRobolectricTest { /* ... */ }

Pattern: WRONG vs RIGHT — `ui-test-manifest` configuration

// WRONG
dependencies {
    androidTestImplementation("androidx.compose.ui:ui-test-junit4")
    androidTestImplementation("androidx.compose.ui:ui-test-manifest")  // wrong config
}
// WRONG because: ui-test-manifest contributes <activity android:name="ComponentActivity">
// to the merged debug APK manifest. On androidTestImplementation, the merger does not pick
// it up; createComposeRule() crashes with ActivityNotFoundException. Lint also flags this
// as TestManifestGradleConfiguration (WARNING).

// RIGHT
dependencies {
    androidTestImplementation("androidx.compose.ui:ui-test-junit4")
    debugImplementation("androidx.compose.ui:ui-test-manifest")
}

See ../../../compose/setup/configuring-test-dependencies/SKILL.md for the lint detail.

Pattern: AGP 7.2+ `sharedTest` migration

// BROKE on AGP 7.2+
android {
    sourceSets {
        getByName("test").java.srcDir("src/sharedTest/java")
        getByName("androidTest").java.srcDir("src/sharedTest/java")
    }
}

// MIGRATION OPTION A — extract a :core-testing sub-module
// :core-testing/build.gradle.kts
plugins { id("java-library") }
// classes here are consumed by both test sourcesets in dependent modules

// :feature:home/build.gradle.kts
dependencies {
    testImplementation(project(":core-testing"))
    androidTestImplementation(project(":core-testing"))
}

// MIGRATION OPTION B — testFixtures
android {
    testFixtures { enable = true }
}
// src/testFixtures/java/...    contains FakeUserRepository, MainDispatcherRule

// dependent module
dependencies {
    testImplementation(testFixtures(project(":core")))
    androidTestImplementation(testFixtures(project(":core")))
}

// MIGRATION OPTION C — KMP source-set naming
// In a KMP Android module:
kotlin {
    androidTarget {
        compilations.getByName("debug") { /* ... */ }
    }
    sourceSets {
        val androidHostTest by getting          // Robolectric, JVM
        val androidDeviceTest by getting        // emulator/device
        val androidCommonTest by getting        // helpers shared by both
        androidHostTest.dependsOn(androidCommonTest)
        androidDeviceTest.dependsOn(androidCommonTest)
    }
}

Compose itself uses Option C internally (per CORPUS §B "Source set conventions").

Module-level Gradle sample

plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

android {
    namespace = "com.example.feature.home"
    compileSdk = 35
    defaultConfig {
        minSdk = 23
        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }
    testOptions {
        unitTests.isIncludeAndroidResources = true   // required for Robolectric
        animationsDisabled = true                    // hermetic instrumented tests
    }
}

dependencies {
    // production
    implementation("androidx.activity:activity-compose")

    // host (JVM) tests — src/test/
    testImplementation("junit:junit:4.13.2")
    testImplementation("androidx.test:core:1.7.0")
    testImplementation("androidx.test.ext:junit:1.3.0")
    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.0")
    testImplementation("org.mockito:mockito-core:5.13.0")
    testImplementation("org.mockito.kotlin:mockito-kotlin:5.4.0")
    testImplementation("org.robolectric:robolectric:4.13")
    testImplementation("app.cash.turbine:turbine:1.1.0")

    // instrumented (device) tests — src/androidTest/
    androidTestImplementation("androidx.test.ext:junit:1.3.0")
    androidTestImplementation("androidx.test.espresso:espresso-core:3.7.0")
    androidTestImplementation("androidx.compose.ui:ui-test-junit4")

    // debug-only — merged manifest entries for test scaffolds
    debugImplementation("androidx.compose.ui:ui-test-manifest")
    debugImplementation("androidx.fragment:fragment-testing-manifest:1.8.5")

    // orchestrator (note: androidTestUtil, not androidTestImplementation)
    androidTestUtil("androidx.test:orchestrator:1.6.1")
}

Mandatory rules

MUST put pure Kotlin / JVM tests in src/test/ with testImplementation deps.
MUST put Robolectric tests in src/test/. Robolectric is a JVM Android simulator, not an instrumented runner.
MUST put real-device / emulator tests in src/androidTest/ with androidTestImplementation deps.
MUST put androidx.compose.ui:ui-test-manifest and androidx.fragment:fragment-testing-manifest on debugImplementation, never androidTestImplementation.
MUST NOT cite developer.android.com/training/testing/... as the source for src/sharedTest/. It is not documented there. Cite the Architecture Blueprints repo or tasks/research/R8-android-fundamentals.md.
MUST NOT add Espresso, UiAutomator, or ui-test-junit4 to testImplementation. They will compile but fail at runtime when no Instrumentation is present.
PREFERRED: for shared test helpers, extract a :core-testing Gradle sub-module or use android.testFixtures.enable = true rather than the AGP-7.2-fragile sharedTest source set.
PREFERRED: in KMP modules, follow Compose's lead — androidCommonTest for helpers, androidHostTest for Robolectric, androidDeviceTest for emulator tests.
PREFERRED: name backtick test methods freely in src/test/; restrict to API 30+ devices in src/androidTest/ per /training/testing/instrumented-tests.

Verification

No Robolectric test exists under src/androidTest/. Run find src/androidTest -name '*.kt' -exec grep -l 'org.robolectric' {} +; expect empty output.
No Espresso / UiAutomator import exists under src/test/. Run find src/test -name '*.kt' -exec grep -l 'androidx.test.espresso\|androidx.test.uiautomator' {} +; expect empty output.
androidx.compose.ui:ui-test-manifest is declared exactly on debugImplementation. Run ./gradlew :<module>:lint; expect no TestManifestGradleConfiguration warning.
./gradlew :<module>:testDebugUnitTest runs JVM tests without invoking connectedDebugAndroidTest.
./gradlew :<module>:connectedDebugAndroidTest invokes only tests under src/androidTest/ (verify with --info output).
If shared helpers exist, they live in a :core-testing sub-module, in testFixtures, or in androidCommonTest — never in a literal src/sharedTest/ folder wired via sourceSets { ... srcDir(...) }.
testOptions.unitTests.isIncludeAndroidResources = true is set when any host test references R.*.

References

developer.android.com/training/testing/local-tests — src/test/, testImplementation, "local test runs directly on your own workstation".
developer.android.com/training/testing/instrumented-tests — src/androidTest/, androidTestImplementation, AndroidJUnitRunner, backtick caveat.
developer.android.com/training/testing/fundamentals — "Big local test: You can use an Android simulator that runs locally, such as Robolectric".
tasks/research/R8-android-fundamentals.md — verbatim quotes; documents that src/sharedTest/ is NOT on any of the six in-scope /training/testing/... pages.
Architecture Blueprints (origin of the sharedTest pattern): https://github.com/android/architecture-samples
AGP source-set documentation: https://developer.android.com/build/build-variants#sourcesets
testFixtures flag: https://developer.android.com/build/dependencies#test-fixtures
CORPUS §C "Source set conventions (KMP)" — Compose's internal androidHostTest / androidDeviceTest layout.
compose/ui/ui-test/src/androidHostTest/kotlin/androidx/compose/ui/test/RobolectricComposeTest.kt — canonical host-test skeleton in androidx.
compose/material3/material3/src/androidDeviceTest/.../SwitchTest.kt — canonical device-test skeleton.
Sibling skills: ../../concepts/understanding-the-testing-pyramid/SKILL.md, ../../concepts/choosing-what-to-test/SKILL.md, ../../doubles/picking-test-doubles/SKILL.md, ../applying-testing-strategies/SKILL.md.
Cross-category: ../../../compose/setup/configuring-test-dependencies/SKILL.md, ../../../jvm-tests/runner/configuring-junit4-on-android/SKILL.md, ../../../jvm-tests/robolectric/using-robolectric-correctly/SKILL.md, ../../../instrumentation/runner/running-instrumented-tests-with-androidjunit4/SKILL.md, ../../../adb/tests/running-instrumented-tests-via-adb/SKILL.md.

About this skill