Ha Android Testing

Shared Test Utilities: :testing-unit

Code needed by tests in several modules goes in :testing-unit (which must stay independent from :common). Check it before writing a new helper. It provides among others:

• Main dispatcher swap — replaces Dispatchers.Main with a TestDispatcher. Pick the helper matching the test's framework: MainDispatcherJUnit5Extension for JUnit Jupiter, applied with @ExtendWith(MainDispatcherJUnit5Extension::class) on the class (or @JvmField @RegisterExtension val ext = MainDispatcherJUnit5Extension() on a field); MainDispatcherJUnit4Rule for JUnit 4 / Robolectric, applied with @get:Rule val mainDispatcherRule = MainDispatcherJUnit4Rule(). Both default to a StandardTestDispatcher. Apply the swap only when the code under test actually runs on the Main dispatcher, typically because it launches on viewModelScope (which uses Dispatchers.Main.immediate). Without it those tests throw "Module with the Main dispatcher had failed to initialize" since there is no Android main looper on the JVM. Don't add it to tests that never touch Main (a plain repository, use case, or pure suspend function) — it's noise there. Use the default StandardTestDispatcher; do not use UnconfinedTestDispatcher. Reaching for it to make a test pass hides ordering the test should assert explicitly (advance the scheduler with runTest/advanceUntilIdle), and needing it usually signals a design problem in the code under test — fix that instead.
• FakeClock — controllable kotlin.time.Clock.
• TestSharedFlow — non-suspending SharedFlow test double that avoids cross-scheduler deadlocks.
• stringResource(...) on AndroidComposeTestRule, seedFakeAndroidId(), and fakes for Wear OS clients.

Flows: Turbine

Turbine is available in all modules and must be used for testing Flows:

• Use turbineScope with testIn for multi-collector tests; assert with awaitItem/awaitComplete/expectNoEvents.
• Never synchronize on Flow emissions with CountDownLatch, Thread.sleep, verify(timeout = ...), or raw launch/async.
• Flows wrapped with shareIn never complete — use expectNoEvents() + cancelAndConsumeRemainingEvents() instead of awaitComplete().

Conventions

• Tests mirror the source structure in src/test/kotlin/.
• Name tests with GIVEN-WHEN-THEN sentences:

@Test
fun `Given user authenticated when opening app then show dashboard`() { ... }

• Test public interfaces and behavior, not implementation details. All public APIs and business logic should have unit tests.
• Never widen visibility or use reflection just for a test: don't expose internal functions to test them — test through the public entry point (onCreate, the ViewModel API). When access is truly unavoidable, use @VisibleForTesting (for example a secondary constructor taking a CoroutineScope or Clock).
• Never use Thread.sleep in tests — it makes them slow and flaky. Run coroutines under runTest so the TestDispatcher fakes time.
• In Jupiter, use @ParameterizedTest when tests repeat with only a value change; in JUnit 4, extract a private function and call it from separately named tests. Merge near-duplicate single-assertion tests into one meaningful test, and add a small helper in the test file for repeated setup.
• Keep all of a feature's tests in one class, even when mixing Robolectric-dependent and plain unit tests.
• Screens are tested in isolation: Compose interaction tests verify each interaction invokes the right callback and that elements show/hide per state (see TagReaderScreenTest); prefer matching on visible text over test tags. Screenshot tests cover looks only, never logic — and must render the real composable (not a simplified stand-in) across its meaningful states (loading, empty, error, multi-server). Navigation tests must cover back and forward stack behavior.
• Test concurrency with TestDispatcher — see the ha-android-concurrency skill.