kotlinx.coroutines – Kotlin Programming Language (original) (raw)

A coroutine scope that for launching test coroutines.

The scope provides the following functionality:

• The coroutineContext includes a coroutine dispatcher that supports delay-skipping, using a TestCoroutineScheduler for orchestrating the virtual time. This scheduler is also available via the testScheduler property, and some helper extension methods are defined to more conveniently interact with it: see TestScope.currentTime, TestScope.runCurrent, TestScope.advanceTimeBy, and TestScope.advanceUntilIdle.
• When inside runTest, uncaught exceptions from the child coroutines of this scope will be reported at the end of the test. It is invalid for child coroutines to throw uncaught exceptions when outside the call to TestScope.runTest: the only guarantee in this case is the best effort to deliver the exception.

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.