kotlin-test-architecture

name	kotlin-test-architecture
description	Use this skill to statically review Kotlin/coroutine/Compose/Android/KMP test architecture and determinism: `runTest` and virtual-time usage, `StandardTestDispatcher` vs `UnconfinedTestDispatcher` choice and advance-call discipline, `Dispatchers.setMain`/`resetMain` hygiene and dispatcher injection, Turbine Flow-testing idioms, Compose UI semantics-based testing, and the Robolectric-vs-instrumented boundary. Reads test source and build config only; it never runs the suite or a device/emulator.
allowed-tools	Read Grep Glob
metadata	{"author":"github: Raishin","version":"0.1.0","updated":"2026-07-21","category":"delivery","lifecycle":"experimental"}

kotlin-test-architecture

Purpose

This skill decides whether Kotlin/coroutine/Compose/Android/KMP tests are architected to be deterministic rather than flaky. A test suite is safe only when suspend tests use runTest with virtual time (never runBlocking), dispatchers are injected so tests can substitute a test dispatcher, Dispatchers.Main overrides are always reset, StandardTestDispatcher tests explicitly advance before asserting, Flow tests via Turbine consume every emission, Compose UI tests use semantics matchers, and the Robolectric/instrumented choice matches what the test actually needs.

Trigger conditions

• A user provides coroutine, Flow, Compose, or Android test source and asks whether it is deterministic or why it is flaky.
• A user is choosing between StandardTestDispatcher and UnconfinedTestDispatcher, or between a Robolectric and an instrumented test.
• A user is writing or reviewing a Turbine Flow test or a Compose UI test and wants the idiom checked.

When not to use

• The concern is generic JVM test mechanics (JUnit5 lifecycle, Testcontainers, ArchUnit) — route to java-test-architecture-agent.
• The concern is coroutine or Flow production correctness rather than test determinism — route to kotlin-coroutines-flow-reliability-agent.
• The concern is generic QA strategy (test-pyramid policy, coverage targets) rather than test architecture — route to the qa board.
• The task requires actually running the test suite or an instrumented test on a device/emulator — this skill is static-review only.

Lean operating rules

• CRITICAL — a suspend-function test that uses runBlocking instead of runTest (kotlinx-coroutines-test) loses virtual-time control and executes real delays, making the test slow and potentially flaky under load; require runTest for any test exercising suspend/coroutine code.
• CRITICAL — production code that references Dispatchers.IO/Dispatchers.Default/Dispatchers.Main directly (hardcoded) instead of receiving an injected CoroutineDispatcher cannot be swapped for a test dispatcher, forcing tests to either run on real dispatchers (non-deterministic) or skip coverage; require dispatcher injection via constructor/parameter for anything under test.
• CRITICAL — a test that overrides Dispatchers.Main via Dispatchers.setMain(...) without a matching Dispatchers.resetMain() in teardown (or a rule/extension that guarantees it) leaks the override into subsequent tests, causing order-dependent flakiness; require the reset be guaranteed.
• HIGH — a StandardTestDispatcher-based test that asserts an outcome without first calling advanceUntilIdle(), runCurrent(), or advanceTimeBy() is asserting against a coroutine that has not actually run to the point being checked; require the appropriate advance call before every assertion that depends on queued coroutine work.
• HIGH — choosing UnconfinedTestDispatcher for a test that needs to assert ordering or intermediate state between two dispatches is a mismatch — it runs children eagerly to their first suspension point, which can hide ordering bugs that StandardTestDispatcher would surface; require the dispatcher choice match what the test is actually verifying.
• HIGH — a Turbine test {} block that does not consume every emitted item before awaitComplete()/cancelAndIgnoreRemainingEvents() can hang or fail with an unconsumed-events error; require every emission be explicitly consumed or the remainder explicitly ignored. Turbine's test {}/awaitItem() already applies a finite default timeout, so a test that simply relies on that default is fine — flag only a timeout that has been disabled or set excessively long, or a Turbine configuration/version where no finite default timeout applies.
• MEDIUM — a Compose UI test that asserts on tree structure or index position instead of a semantics-based matcher (onNodeWithText, onNodeWithTag, content description) is brittle to layout changes unrelated to the behavior under test; require semantics-based matchers.

References

Load these only when needed:

• runTest And Dispatcher Control
• Turbine Flow Testing
• Compose UI Testing And The Robolectric/Instrumented Boundary
• Official Sources
• Safety Checklist

Response minimum

• A verdict (pass / pass-with-conditions / block) and the test framework/dispatcher versions assumed.
• runTest/virtual-time, dispatcher-injection/setMain-resetMain, StandardTestDispatcher/UnconfinedTestDispatcher, Turbine, and Compose/Robolectric-boundary findings, each with an evidence-basis label.
• A severity-labelled finding list plus safe next actions and open questions, including any flake the user must reproduce to confirm root cause.