kotlinx-coroutines-test

Test utilities for kotlinx.coroutines.

Overview

This package provides utilities for efficiently testing coroutines.

NameDescription
runTestRuns the test code, automatically skipping delays and handling uncaught exceptions.
TestCoroutineSchedulerThe shared source of virtual time, used for controlling execution order and skipping delays.
TestScopeA CoroutineScope that integrates with runTest, providing access to TestCoroutineScheduler.
TestDispatcherA CoroutineDispatcher that whose delays are controlled by a TestCoroutineScheduler.
Dispatchers.setMainMocks the main dispatcher using the provided one. If mocked with a TestDispatcher, its TestCoroutineScheduler is used everywhere by default.

Provided TestDispatcher implementations:

NameDescription
StandardTestDispatcherA simple dispatcher with no special behavior other than being linked to a TestCoroutineScheduler.
UnconfinedTestDispatcherA dispatcher that behaves like Dispatchers.Unconfined.

Using in your project

Add kotlinx-coroutines-test to your project test dependencies:

dependencies {
testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.6.0'
}

Do not depend on this project in your main sources, all utilities here are intended and designed to be used only from tests.

Dispatchers.Main Delegation

Dispatchers.setMain will override the Main dispatcher in test scenarios. This is helpful when one wants to execute a test in situations where the platform Main dispatcher is not available, or to replace Dispatchers.Main with a testing dispatcher.

On the JVM, the ServiceLoader mechanism is responsible for overwriting Dispatchers.Main with a testable implementation, which by default will delegate its calls to the real Main dispatcher, if any.

The Main implementation can be overridden using setMain method with any CoroutineDispatcher implementation, e.g.:

class SomeTest {

private val mainThreadSurrogate = newSingleThreadContext("UI thread")

@Before
fun setUp() {
Dispatchers.setMain(mainThreadSurrogate)
}

@After
fun tearDown() {
Dispatchers.resetMain() // reset the main dispatcher to the original Main dispatcher
mainThreadSurrogate.close()
}

@Test
fun testSomeUI() = runBlocking {
launch(Dispatchers.Main) { // Will be launched in the mainThreadSurrogate dispatcher
// ...
}
}
}

Calling setMain or resetMain immediately changes the Main dispatcher globally.

If Main is overridden with a TestDispatcher, then its TestCoroutineScheduler is used when new TestDispatcher or TestScope instances are created without TestCoroutineScheduler being passed as an argument.

runTest

runTest is the way to test code that involves coroutines. suspend functions can be called inside it.

IMPORTANT: in order to work with on Kotlin/JS, the result of runTest must be immediately return-ed from each test. The typical invocation of runTest thus looks like this:

Test utilities for kotlinx.coroutines.

Overview

This package provides utilities for efficiently testing coroutines.

NameDescription
runTestRuns the test code, automatically skipping delays and handling uncaught exceptions.
TestCoroutineSchedulerThe shared source of virtual time, used for controlling execution order and skipping delays.
TestScopeA CoroutineScope that integrates with runTest, providing access to TestCoroutineScheduler.
TestDispatcherA CoroutineDispatcher that whose delays are controlled by a TestCoroutineScheduler.
Dispatchers.setMainMocks the main dispatcher using the provided one. If mocked with a TestDispatcher, its TestCoroutineScheduler is used everywhere by default.

Provided TestDispatcher implementations:

NameDescription
StandardTestDispatcherA simple dispatcher with no special behavior other than being linked to a TestCoroutineScheduler.
UnconfinedTestDispatcherA dispatcher that behaves like Dispatchers.Unconfined.

Using in your project

Add kotlinx-coroutines-test to your project test dependencies:

dependencies {
testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.6.0'
}

Do not depend on this project in your main sources, all utilities here are intended and designed to be used only from tests.

Dispatchers.Main Delegation

Dispatchers.setMain will override the Main dispatcher in test scenarios. This is helpful when one wants to execute a test in situations where the platform Main dispatcher is not available, or to replace Dispatchers.Main with a testing dispatcher.

On the JVM, the ServiceLoader mechanism is responsible for overwriting Dispatchers.Main with a testable implementation, which by default will delegate its calls to the real Main dispatcher, if any.

The Main implementation can be overridden using setMain method with any CoroutineDispatcher implementation, e.g.:

class SomeTest {

private val mainThreadSurrogate = newSingleThreadContext("UI thread")

@Before
fun setUp() {
Dispatchers.setMain(mainThreadSurrogate)
}

@After
fun tearDown() {
Dispatchers.resetMain() // reset the main dispatcher to the original Main dispatcher
mainThreadSurrogate.close()
}

@Test
fun testSomeUI() = runBlocking {
launch(Dispatchers.Main) { // Will be launched in the mainThreadSurrogate dispatcher
// ...
}
}
}

Calling setMain or resetMain immediately changes the Main dispatcher globally.

If Main is overridden with a TestDispatcher, then its TestCoroutineScheduler is used when new TestDispatcher or TestScope instances are created without TestCoroutineScheduler being passed as an argument.

runTest

runTest is the way to test code that involves coroutines. suspend functions can be called inside it.

IMPORTANT: in order to work with on Kotlin/JS, the result of runTest must be immediately return-ed from each test. The typical invocation of runTest thus looks like this:

Test utilities for kotlinx.coroutines.

Overview

This package provides utilities for efficiently testing coroutines.

NameDescription
runTestRuns the test code, automatically skipping delays and handling uncaught exceptions.
TestCoroutineSchedulerThe shared source of virtual time, used for controlling execution order and skipping delays.
TestScopeA CoroutineScope that integrates with runTest, providing access to TestCoroutineScheduler.
TestDispatcherA CoroutineDispatcher that whose delays are controlled by a TestCoroutineScheduler.
Dispatchers.setMainMocks the main dispatcher using the provided one. If mocked with a TestDispatcher, its TestCoroutineScheduler is used everywhere by default.

Provided TestDispatcher implementations:

NameDescription
StandardTestDispatcherA simple dispatcher with no special behavior other than being linked to a TestCoroutineScheduler.
UnconfinedTestDispatcherA dispatcher that behaves like Dispatchers.Unconfined.

Using in your project

Add kotlinx-coroutines-test to your project test dependencies:

dependencies {
testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.6.0'
}

Do not depend on this project in your main sources, all utilities here are intended and designed to be used only from tests.

Dispatchers.Main Delegation

Dispatchers.setMain will override the Main dispatcher in test scenarios. This is helpful when one wants to execute a test in situations where the platform Main dispatcher is not available, or to replace Dispatchers.Main with a testing dispatcher.

On the JVM, the ServiceLoader mechanism is responsible for overwriting Dispatchers.Main with a testable implementation, which by default will delegate its calls to the real Main dispatcher, if any.

The Main implementation can be overridden using setMain method with any CoroutineDispatcher implementation, e.g.:

class SomeTest {

private val mainThreadSurrogate = newSingleThreadContext("UI thread")

@Before
fun setUp() {
Dispatchers.setMain(mainThreadSurrogate)
}

@After
fun tearDown() {
Dispatchers.resetMain() // reset the main dispatcher to the original Main dispatcher
mainThreadSurrogate.close()
}

@Test
fun testSomeUI() = runBlocking {
launch(Dispatchers.Main) { // Will be launched in the mainThreadSurrogate dispatcher
// ...
}
}
}

Calling setMain or resetMain immediately changes the Main dispatcher globally.

If Main is overridden with a TestDispatcher, then its TestCoroutineScheduler is used when new TestDispatcher or TestScope instances are created without TestCoroutineScheduler being passed as an argument.

runTest

runTest is the way to test code that involves coroutines. suspend functions can be called inside it.

IMPORTANT: in order to work with on Kotlin/JS, the result of runTest must be immediately return-ed from each test. The typical invocation of runTest thus looks like this:

Test utilities for kotlinx.coroutines.

Overview

This package provides utilities for efficiently testing coroutines.

NameDescription
runTestRuns the test code, automatically skipping delays and handling uncaught exceptions.
TestCoroutineSchedulerThe shared source of virtual time, used for controlling execution order and skipping delays.
TestScopeA CoroutineScope that integrates with runTest, providing access to TestCoroutineScheduler.
TestDispatcherA CoroutineDispatcher that whose delays are controlled by a TestCoroutineScheduler.
Dispatchers.setMainMocks the main dispatcher using the provided one. If mocked with a TestDispatcher, its TestCoroutineScheduler is used everywhere by default.

Provided TestDispatcher implementations:

NameDescription
StandardTestDispatcherA simple dispatcher with no special behavior other than being linked to a TestCoroutineScheduler.
UnconfinedTestDispatcherA dispatcher that behaves like Dispatchers.Unconfined.

Using in your project

Add kotlinx-coroutines-test to your project test dependencies:

dependencies {
testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.6.0'
}

Do not depend on this project in your main sources, all utilities here are intended and designed to be used only from tests.

Dispatchers.Main Delegation

Dispatchers.setMain will override the Main dispatcher in test scenarios. This is helpful when one wants to execute a test in situations where the platform Main dispatcher is not available, or to replace Dispatchers.Main with a testing dispatcher.

On the JVM, the ServiceLoader mechanism is responsible for overwriting Dispatchers.Main with a testable implementation, which by default will delegate its calls to the real Main dispatcher, if any.

The Main implementation can be overridden using setMain method with any CoroutineDispatcher implementation, e.g.:

class SomeTest {

private val mainThreadSurrogate = newSingleThreadContext("UI thread")

@Before
fun setUp() {
Dispatchers.setMain(mainThreadSurrogate)
}

@After
fun tearDown() {
Dispatchers.resetMain() // reset the main dispatcher to the original Main dispatcher
mainThreadSurrogate.close()
}

@Test
fun testSomeUI() = runBlocking {
launch(Dispatchers.Main) { // Will be launched in the mainThreadSurrogate dispatcher
// ...
}
}
}

Calling setMain or resetMain immediately changes the Main dispatcher globally.

If Main is overridden with a TestDispatcher, then its TestCoroutineScheduler is used when new TestDispatcher or TestScope instances are created without TestCoroutineScheduler being passed as an argument.

runTest

runTest is the way to test code that involves coroutines. suspend functions can be called inside it.

IMPORTANT: in order to work with on Kotlin/JS, the result of runTest must be immediately return-ed from each test. The typical invocation of runTest thus looks like this:

Packages

kotlinx.coroutines.test
Link copied to clipboard
common
js
native