skip to content

How do you make StandardTestDispatcher and UnconfinedTestDispatcher cooperate on the same virtual timeline inside a runTest block, and why does sharing the TestCoroutineScheduler matter?

level: middleimportance: should knowfreq 40%

answer

  1. Scheduler owns virtual time + task queue
  2. Pass testScheduler to every extra TestDispatcher
  3. No-arg constructor = fresh isolated scheduler = de-sync
  4. One advanceUntilIdle drives all shared dispatchers
  5. Mix Standard (test body) + Unconfined (collaborator)

basics

~10 s

Construct both dispatchers from the same scheduler, usually runTest's testScheduler. Then delays and advances are coordinated on one shared clock, so coroutines on either dispatcher stay in sync instead of running on separate timelines.

solid answer

~50 s

Each TestDispatcher is backed by a TestCoroutineScheduler that owns the virtual clock and the pending-task queue. To keep multiple dispatchers on one timeline, build them from the *same* scheduler instance. Inside runTest you grab it via the testScheduler property: `UnconfinedTestDispatcher(testScheduler)` or `StandardTestDispatcher(testScheduler)`. If you accidentally create a dispatcher with no-arg constructors, each gets its own fresh scheduler and its own clock, so advanceUntilIdle()/advanceTimeBy() on one won't move the other and delays won't coordinate — a common source of hanging or non-deterministic tests. Sharing the scheduler means a single advanceUntilIdle() drives all coroutines across both dispatchers, delay() durations are measured on one clock, and ordering is well-defined. This is essential when, for example, the test body runs on the default StandardTestDispatcher but a collaborator (a ViewModel, a flow collector) is injected with an UnconfinedTestDispatcher for eager start.

code

kotlin · 9 lines
kotlin
@Test
fun forkedSchedulerHangs() = runTest {
    // WRONG: no-arg creates its own scheduler
    val isolated = UnconfinedTestDispatcher()
    var done = false
    launch(isolated) { delay(10); done = true }
    advanceUntilIdle()   // drives testScheduler, NOT isolated's clock
    // 'done' may still be false depending on eager prefix vs delay
}

go deeper

for a junior

Knows to use the same dispatcher type but may not articulate the scheduler.

for a middle

Explains that the scheduler is the shared clock/queue and how to pass testScheduler.

for a senior

Diagnoses hang/de-sync bugs from forked schedulers and explains the mixed Standard+Unconfined pattern.

for a principal

Designs test infrastructure so collaborators always receive the shared scheduler, preventing whole classes of flaky tests.

## The scheduler is the timeline `TestCoroutineScheduler` is the single source of truth for: (a) the current **virtual time**, and (b) the **queue** of scheduled continuations (tasks waiting to run, each with a due time). A `TestDispatcher` is just the routing layer that hands work to that scheduler. ## Sharing vs. forking the scheduler The key invariant: **dispatchers coordinate only if they share one scheduler instance.** ```kotlin @Test fun shared() = runTest { // creates ONE scheduler val eager = UnconfinedTestDispatcher(testScheduler) // shares it val standard = StandardTestDispatcher(testScheduler) // shares it val log = mutableListOf<String>() launch(eager) { delay(100); log += "eager-100" } launch(standard) { delay(50); log += "std-50" } advanceUntilIdle() // one clock drives BOTH assertEquals(listOf("std-50", "eager-100"), log) // ordered by virtual time } ``` If instead you wrote `UnconfinedTestDispatcher()` (no argument), it would spin up a **separate** scheduler with its own clock. Then: - `advanceUntilIdle()` on `testScheduler` would not run that coroutine. - Delays would not be ordered relative to the rest of the test. - The test may hang or assert against stale state. ## How to obtain the shared scheduler - Inside `runTest { ... }`: use the `testScheduler` property of the `TestScope` receiver. - Outside: create one explicitly, `val scheduler = TestCoroutineScheduler()`, and pass it everywhere, including to `runTest(scheduler) { }` or a `TestScope(scheduler)`. ## Why mix the two dispatchers at all? A realistic pattern: the **test body** runs on the default `StandardTestDispatcher` (deterministic, manual), while a **collaborator under test** (e.g. a `ViewModel` that launches a flow collector in `init`) is injected an `UnconfinedTestDispatcher` so its initialization work runs eagerly and is observable before your first assertion — yet both still share the clock so `advanceTimeBy` and `delay` remain coordinated. ## Practical rule Always pass `testScheduler` when constructing extra test dispatchers inside `runTest`. Never rely on no-arg test-dispatcher constructors inside a `runTest` block unless you deliberately want an isolated clock.

  • What happens if you use the no-arg UnconfinedTestDispatcher() inside runTest?
    It creates a separate scheduler with its own clock, so advanceUntilIdle on testScheduler won't drive it and time won't coordinate.
  • How do you get the scheduler from runTest?
    The TestScope receiver exposes a testScheduler property; pass it to any TestDispatcher you build.

saying these in an interview costs you the question

  • Using no-arg test-dispatcher constructors inside runTest and expecting coordination
  • Believing each dispatcher always has its own independent clock
  • Thinking advanceUntilIdle is per-dispatcher rather than per-scheduler
  • Not knowing testScheduler exists
  • Assuming sharing requires the same dispatcher type

context

resolving links…