interface TestScope : CoroutineScope

A coroutine scope that for launching test coroutines.

The scope provides the following functionality:

The usual way to access a TestScope is to call runTest, but it can also be constructed manually, in order to use it to initialize the components that participate in the test.

Differences from the deprecated TestCoroutineScope

  • This doesn't provide an equivalent of TestCoroutineScope.cleanupTestCoroutines, and so can't be used as a standalone mechanism for writing tests: it does require that runTest is eventually called. The reason for this is that a proper cleanup procedure that supports using non-test dispatchers and arbitrary coroutine suspensions would be equivalent to runTest, but would also be more error-prone, due to the potential for forgetting to perform the cleanup.

  • TestCoroutineScope.advanceTimeBy also calls TestCoroutineScheduler.runCurrent after advancing the virtual time.

  • No support for dispatcher pausing, like DelayController allows. TestCoroutineDispatcher, which supported pausing, is deprecated; now, instead of pausing a dispatcher, one can use withContext to run a dispatcher that's paused by default, like StandardTestDispatcher.

  • No access to the list of unhandled exceptions.


Link copied to clipboard
abstract val backgroundScope: CoroutineScope

A scope for background work.

Link copied to clipboard
abstract val testScheduler: TestCoroutineScheduler

The delay-skipping scheduler used by the test dispatchers running the code in this scope.


Link copied to clipboard
fun TestScope.advanceTimeBy(delayTimeMillis: Long)

Moves the virtual clock of this dispatcher forward by the specified amount, running the scheduled tasks in the meantime.

Link copied to clipboard
fun TestScope.advanceUntilIdle()

Advances the testScheduler to the point where there are no tasks remaining.

Link copied to clipboard
val TestScope.currentTime: Long

The current virtual time on testScheduler.

Link copied to clipboard
fun TestScope.runBlockingTest(block: suspend TestScope.() -> Unit)

Convenience method for calling runBlockingTestOnTestScope on an existing TestScope.

Link copied to clipboard
fun TestScope.runCurrent()

Run any tasks that are pending at the current virtual time, according to the testScheduler.

Link copied to clipboard
fun TestScope.runTest(dispatchTimeoutMs: Long = DEFAULT_DISPATCH_TIMEOUT_MS, testBody: suspend TestScope.() -> Unit): TestResult

Performs runTest on an existing TestScope.

Link copied to clipboard