# Migration to the new kotlinx-coroutines-test API In version 1.6.0, the API of the test module changed significantly. This is a guide for gradually adapting the existing test code to the new API. This guide is written step-by-step; the idea is to separate the migration into several sets of small changes. ## Remove custom `UncaughtExceptionCaptor`, `DelayController`, and `TestCoroutineScope` implementations We couldn't find any code that defined new implementations of these interfaces, so they are deprecated. It's likely that you don't need to do anything for this section. ### `UncaughtExceptionCaptor` If the code base has an `UncaughtExceptionCaptor`, its special behavior as opposed to just `CoroutineExceptionHandler` was that, at the end of `runBlockingTest` or `cleanupTestCoroutines` (or both), its `cleanupTestCoroutines` procedure was called. We currently don't provide a replacement for this. However, `runTest` follows structured concurrency better than `runBlockingTest` did, so exceptions from child coroutines are propagated structurally, which makes uncaught exception handlers less useful. If you have a use case for this, please tell us about it at the issue tracker. Meanwhile, it should be possible to use a custom exception captor, which should only implement `CoroutineExceptionHandler` now, like this: ```kotlin @Test fun testFoo() = runTest { val customCaptor = MyUncaughtExceptionCaptor() launch(customCaptor) { // ... } advanceUntilIdle() customCaptor.cleanupTestCoroutines() } ``` ### `DelayController` We don't provide a way to define custom dispatching strategies that support virtual time. That said, we significantly enhanced this mechanism: * Using multiple test dispatchers simultaneously is supported. For the dispatchers to have a shared knowledge of the virtual time, either the same `TestCoroutineScheduler` should be passed to each of them, or all of them should be constructed after `Dispatchers.setMain` is called with some test dispatcher. * Both a simple `StandardTestDispatcher` that is always paused, and unconfined `UnconfinedTestDispatcher` are provided. If you have a use case for `DelayController` that's not covered by what we provide, please tell us about it in the issue tracker. ### `TestCoroutineScope` This scope couldn't be meaningfully used in tandem with `runBlockingTest`: according to the definition of `TestCoroutineScope.runBlockingTest`, only the scope's `coroutineContext` is used. So, there could be two reasons for defining a custom implementation: * Avoiding the restrictions on placed `coroutineContext` in the `TestCoroutineScope` constructor function. These restrictions consisted of requirements for `CoroutineExceptionHandler` being an `UncaughtExceptionCaptor`, and `ContinuationInterceptor` being a `DelayController`, so it is also possible to fulfill these restrictions by defining conforming instances. In this case, follow the instructions about replacing them. * Using without `runBlockingTest`. In this case, you don't even need to implement `TestCoroutineScope`: nothing else accepts a `TestCoroutineScope` specifically as an argument. ## Remove usages of `TestCoroutineExceptionHandler` and `TestCoroutineScope.uncaughtExceptions` It is already illegal to use a `TestCoroutineScope` without performing `cleanupTestCoroutines`, so the valid uses of `TestCoroutineExceptionHandler` include: * Accessing `uncaughtExceptions` in the middle of the test to make sure that there weren't any uncaught exceptions *yet*. If there are any, they will be thrown by the cleanup procedure anyway. We don't support this use case, given how comparatively rare it is, but it can be handled in the same way as the following one. * Accessing `uncaughtExceptions` when the uncaught exceptions are actually expected. In this case, `cleanupTestCoroutines` will fail with an exception that is being caught later. It would be better in this case to use a custom `CoroutineExceptionHandler` so that actual problems that could be found by the cleanup procedure are not superseded by the exceptions that are expected. An example is shown below. ```kotlin val exceptions = mutableListOf() val customCaptor = CoroutineExceptionHandler { ctx, throwable -> exceptions.add(throwable) // add proper synchronization if the test is multithreaded } @Test fun testFoo() = runTest { launch(customCaptor) { // ... } advanceUntilIdle() // check the list of the caught exceptions } ``` ## Auto-replace `TestCoroutineScope` constructor function with `createTestCoroutineScope` This should not break anything, as `TestCoroutineScope` is now defined in terms of `createTestCoroutineScope`. If it does break something, it means that you already supplied a `TestCoroutineScheduler` to some scope; in this case, also pass this scheduler as the argument to the dispatcher. ## Replace usages of `pauseDispatcher` and `resumeDispatcher` with a `StandardTestDispatcher` * In places where `pauseDispatcher` in its block form is called, replace it with a call to `withContext(StandardTestDispatcher(testScheduler))` (`testScheduler` is available as a field of `TestCoroutineScope`, or `scheduler` is available as a field of `TestCoroutineDispatcher`), followed by `advanceUntilIdle()`. This is not an automatic replacement, as there can be tricky situations where the test dispatcher is already paused when `pauseDispatcher { X }` is called. In such cases, simply replace `pauseDispatcher { X }` with `X`. * Often, `pauseDispatcher()` in a non-block form is used at the start of the test. Then, attempt to remove `TestCoroutineDispatcher` from the arguments to `createTestCoroutineScope`, if a standalone `TestCoroutineScope` or the `scope.runBlockingTest` form is used, or pass a `StandardTestDispatcher` as an argument to `runBlockingTest`. This will lead to the test using a `StandardTestDispatcher`, which does not allow pausing and resuming, instead of the deprecated `TestCoroutineDispatcher`. * Sometimes, `pauseDispatcher()` and `resumeDispatcher()` are employed used throughout the test. In this case, attempt to wrap everything until the next `resumeDispatcher()` in a `withContext(StandardTestDispatcher(testScheduler))` block, or try using some other combinations of `StandardTestDispatcher` (where dispatches are needed) and `UnconfinedTestDispatcher` (where it isn't important where execution happens). ## Replace `advanceTimeBy(n)` with `advanceTimeBy(n); runCurrent()` For `TestCoroutineScope` and `DelayController`, the `advanceTimeBy` method is deprecated. It is not deprecated for `TestCoroutineScheduler` and `TestScope`, but has a different meaning: it does not run the tasks scheduled *at* `currentTime + n`. There is an automatic replacement for this deprecation, which produces correct but inelegant code. Alternatively, you can wait until replacing `TestCoroutineScope` with `TestScope`: it's possible that you will not encounter this edge case. ## Replace `runBlockingTest` with `runTest(UnconfinedTestDispatcher())` This is a major change, affecting many things, and can be done in parallel with replacing `TestCoroutineScope` with `TestScope`. Significant differences of `runTest` from `runBlockingTest` are each given a section below. ### It works properly with other dispatchers and asynchronous completions. No action on your part is required, other than replacing `runBlocking` with `runTest` as well. ### It uses `StandardTestDispatcher` by default, not `TestCoroutineDispatcher`. By now, calls to `pauseDispatcher` and `resumeDispatcher` should be purged from the code base, so only the unpaused variant of `TestCoroutineDispatcher` should be used. This version of the dispatcher has the property of eagerly entering `launch` and `async` blocks: code until the first suspension is executed without dispatching. There are two common ways in which this property is useful. #### `TestCoroutineDispatcher` for the top-level coroutine Some tests that rely on `launch` and `async` blocks being entered immediately have a form similar to this: ```kotlin runTest(TestCoroutineDispatcher()) { launch { updateSomething() } checkThatSomethingWasUpdated() launch { updateSomethingElse() } checkThatSomethingElseWasUpdated() } ``` If the `TestCoroutineDispatcher()` is simply removed, `StandardTestDispatcher()` will be used, which will cause the test to fail. In these cases, `UnconfinedTestDispatcher()` should be used. We ensured that, when run with an `UnconfinedTestDispatcher`, `runTest` also eagerly enters `launch` and `async` blocks. Note though that *this only works at the top level*: if a child coroutine also called `launch` or `async`, we don't provide any guarantees about their dispatching order. #### `TestCoroutineDispatcher` for testing intermediate emissions Some code tests `StateFlow` or channels in a manner similar to this: ```kotlin @Test fun testAllEmissions() = runTest(TestCoroutineDispatcher()) { val values = mutableListOf() val stateFlow = MutableStateFlow(0) val job = launch { stateFlow.collect { values.add(it) } } stateFlow.value = 1 stateFlow.value = 2 stateFlow.value = 3 job.cancel() // each assignment will immediately resume the collecting child coroutine, // so no values will be skipped. assertEquals(listOf(0, 1, 2, 3), values) } ``` Such code will fail when `TestCoroutineDispatcher()` is not used: not every emission will be listed. In this particular case, none will be listed at all. The reason for this is that setting `stateFlow.value` (as is sending to a channel, as are some other things) wakes up the coroutine waiting for the new value, but *typically* does not immediately run the collecting code, instead simply dispatching it. The exceptions are the coroutines running in dispatchers that don't (always) go through a dispatch, `Dispatchers.Unconfined`, `Dispatchers.Main.immediate`, `UnconfinedTestDispatcher`, or `TestCoroutineDispatcher` in the unpaused state. Therefore, a solution is to launch the collection in an unconfined dispatcher: ```kotlin @Test fun testAllEmissions() = runTest { val values = mutableListOf() val stateFlow = MutableStateFlow(0) val job = launch(UnconfinedTestDispatcher(testScheduler)) { // <------ stateFlow.collect { values.add(it) } } stateFlow.value = 1 stateFlow.value = 2 stateFlow.value = 3 job.cancel() // each assignment will immediately resume the collecting child coroutine, // so no values will be skipped. assertEquals(listOf(0, 1, 2, 3), values) } ``` Note that `testScheduler` is passed so that the unconfined dispatcher is linked to `runTest`. Also, note that `UnconfinedTestDispatcher` is not passed to `runTest`. This is due to the fact that, *inside* the `UnconfinedTestDispatcher`, there are no execution order guarantees, so it would not be guaranteed that setting `stateFlow.value` would immediately run the collecting code (though in this case, it does). #### Other considerations Using `UnconfinedTestDispatcher` as an argument to `runTest` will probably lead to the test being executed as it did, but it's still possible that the test relies on the specific dispatching order of `TestCoroutineDispatcher`, so it will need to be tweaked. If some code is expected to have run at some point, but it hasn't, use `runCurrent` to force the tasks scheduled at this moment of time to run. For example, the `StateFlow` example above can also be forced to succeed by doing this: ```kotlin @Test fun testAllEmissions() = runTest { val values = mutableListOf() val stateFlow = MutableStateFlow(0) val job = launch { stateFlow.collect { values.add(it) } } runCurrent() stateFlow.value = 1 runCurrent() stateFlow.value = 2 runCurrent() stateFlow.value = 3 runCurrent() job.cancel() // each assignment will immediately resume the collecting child coroutine, // so no values will be skipped. assertEquals(listOf(0, 1, 2, 3), values) } ``` Be wary though of this approach: using `runCurrent`, `advanceTimeBy`, or `advanceUntilIdle` is, essentially, simulating some particular execution order, which is not guaranteed to happen in production code. For example, using `UnconfinedTestDispatcher` to fix this test reflects how, in production code, one could use `Dispatchers.Unconfined` to observe all emitted values without conflation, but the `runCurrent()` approach only states that the behavior would be observed if a dispatch were to happen at some chosen points. It is, therefore, recommended to structure tests in a way that does not rely on a particular interleaving, unless that is the intention. ### The job hierarchy is completely different. - Structured concurrency is used, with the scope provided as the receiver of `runTest` actually being the scope of the created coroutine. - Not `SupervisorJob` but a normal `Job` is used for the `TestCoroutineScope`. - The job passed as an argument is used as a parent job. Most tests should not be affected by this. In case your test is, try explicitly launching a child coroutine with a `SupervisorJob`; this should make the job hierarchy resemble what it used to be. ```kotlin @Test fun testFoo() = runTest { val deferred = async(SupervisorJob()) { // test code } advanceUntilIdle() deferred.getCompletionExceptionOrNull()?.let { throw it } } ``` ### Only a single call to `runTest` is permitted per test. In order to work on JS, only a single call to `runTest` must happen during one test, and its result must be returned immediately: ```kotlin @Test fun testFoo(): TestResult { // arbitrary code here return runTest { // ... } } ``` When used only on the JVM, `runTest` will work when called repeatedly, but this is not supported. Please only call `runTest` once per test, and if for some reason you can't, please tell us about in on the issue tracker. ### It uses `TestScope`, not `TestCoroutineScope`, by default. There is a `runTestWithLegacyScope` method that allows migrating from `runBlockingTest` to `runTest` before migrating from `TestCoroutineScope` to `TestScope`, if exactly the `TestCoroutineScope` needs to be passed somewhere else and `TestScope` will not suffice. ## Replace `TestCoroutineScope.cleanupTestCoroutines` with `runTest` Likely can be done together with the next step. Remove all calls to `TestCoroutineScope.cleanupTestCoroutines` from the code base. Instead, as the last step of each test, do `return scope.runTest`; if possible, the whole test body should go inside the `runTest` block. The cleanup procedure in `runTest` will not check that the virtual time doesn't advance during cleanup. If a test must check that no other delays are remaining after it has finished, the following form may help: ```kotlin runTest { testBody() val timeAfterTest = currentTime() advanceUntilIdle() // run the remaining tasks assertEquals(timeAfterTest, currentTime()) // will fail if there were tasks scheduled at a later moment } ``` Note that this will report time advancement even if the job scheduled at a later point was cancelled. It may be the case that `cleanupTestCoroutines` must be executed after de-initialization in `@AfterTest`, which happens outside the test itself. In this case, we propose that you write a wrapper of the form: ```kotlin fun runTestAndCleanup(body: TestScope.() -> Unit) = runTest { try { body() } finally { // the usual cleanup procedures that used to happen before `cleanupTestCoroutines` } } ``` ## Replace `runBlockingTest` with `runBlockingTestOnTestScope`, `createTestCoroutineScope` with `TestScope` Also, replace `runTestWithLegacyScope` with just `runTest`. All of this can be done in parallel with replacing `runBlockingTest` with `runTest`. This step should remove all uses of `TestCoroutineScope`, explicit or implicit. Replacing `runTestWithLegacyScope` and `runBlockingTest` with `runTest` and `runBlockingTestOnTestScope` should be straightforward if there is no more code left that requires passing exactly `TestCoroutineScope` to it. Some tests may fail because `TestCoroutineScope.cleanupTestCoroutines` and the cleanup procedure in `runTest` handle cancelled tasks differently: if there are *cancelled* jobs pending at the moment of `TestCoroutineScope.cleanupTestCoroutines`, they are ignored, whereas `runTest` will report them. Of all the methods supported by `TestCoroutineScope`, only `cleanupTestCoroutines` is not provided on `TestScope`, and its usages should have been removed during the previous step. ## Replace `runBlocking` with `runTest` Now that `runTest` works properly with asynchronous completions, `runBlocking` is only occasionally useful. As is, most uses of `runBlocking` in tests come from the need to interact with dispatchers that execute on other threads, like `Dispatchers.IO` or `Dispatchers.Default`. ## Replace `TestCoroutineDispatcher` with `UnconfinedTestDispatcher` and `StandardTestDispatcher` `TestCoroutineDispatcher` is a dispatcher with two modes: * ("unpaused") Almost (but not quite) unconfined, with the ability to eagerly enter `launch` and `async` blocks. * ("paused") Behaving like a `StandardTestDispatcher`. In one of the earlier steps, we replaced `pauseDispatcher` with `StandardTestDispatcher` usage, and replaced the implicit `TestCoroutineScope` dispatcher in `runBlockingTest` with `UnconfinedTestDispatcher` during migration to `runTest`. Now, the rest of the usages should be replaced with whichever dispatcher is most appropriate. ## Simplify code by removing unneeded entities Likely, now some code has the form ```kotlin val dispatcher = StandardTestDispatcher() val scope = TestScope(dispatcher) @BeforeTest fun setUp() { Dispatchers.setMain(dispatcher) } @AfterTest fun tearDown() { Dispatchers.resetMain() } @Test fun testFoo() = scope.runTest { // ... } ``` The point of this pattern is to ensure that the test runs with the same `TestCoroutineScheduler` as the one used for `Dispatchers.Main`. However, now this can be simplified to just ```kotlin @BeforeTest fun setUp() { Dispatchers.setMain(StandardTestDispatcher()) } @AfterTest fun tearDown() { Dispatchers.resetMain() } @Test fun testFoo() = runTest { // ... } ``` The reason this works is that all entities that depend on `TestCoroutineScheduler` will attempt to acquire one from the current `Dispatchers.Main`.