Test Coroutine Dispatcher

A TestDispatcher is a special CoroutineDispatcher provided by the kotlinx-coroutines-test module that allows developers to control its virtual clock and skip delays.

A TestDispatcher supports the following operations:

• currentTime gets the current virtual time.
• runCurrent() runs the tasks that are scheduled at this point of virtual time.
• advanceUntilIdle() runs all enqueued tasks until there are no more.
• advanceTimeBy(timeDelta) runs the enqueued tasks until the current virtual time advances by timeDelta.

To use a TestDispatcher for a test, you can enable coroutineTestScope in test config:

class TestDispatcherTest : FunSpec() {
   init {
      test("foo").config(coroutineTestScope = true) {
         // this test will run with a test dispatcher
      }
   }
}

Inside this test, you can retrieve a handle to the scheduler through the extension val testCoroutineScheduler. Using this scheduler, you can then manipulate the time:

import io.kotest.core.test.testCoroutineScheduler

class TestDispatcherTest : FunSpec() {
   init {
      test("advance time").config(coroutineTestScope = true) {
        val duration = 1.days
        // launch a coroutine that would normally sleep for 1 day
        launch {
          delay(duration.inWholeMilliseconds)
        }
        // move the clock on and the delay in the above coroutine will finish immediately.
        testCoroutineScheduler.advanceTimeBy(duration.inWholeMilliseconds)
        val currentTime = testCoroutineScheduler.currentTime
      }
   }
}

You can enable a test dispatcher for all tests in a spec by setting coroutineTestScope to true at the spec level:

class TestDispatcherTest : FunSpec() {
   init {
      coroutineTestScope = true
      test("this test uses a test dispatcher") {
      }
      test("and so does this test!") {
      }
   }
}

Finally, you can enable test dispatchers for all tests in a module by using ProjectConfig:

class ProjectConfig : AbstractProjectConfig() {
  override var testCoroutineDispatcher = true
}