runTest и виртуальное время: тесты корутин без Thread.sleep

Тест на код с задержками обычно пишут так: вызвали, подождали Thread.sleep, проверили. Он проходит на машине разработчика и падает в CI, где всё медленнее. Или не падает, но прогон занимает минуты.

Для корутин это решается не терпением, а виртуальным временем: задержки не выжидаются, а проматываются.

Подключение

Нужна библиотека kotlinx-coroutines-test — той же версии, что и kotlinx-coroutines-core, иначе будут странные ошибки инициализации:

testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.1")

runTest и виртуальные часы

runTest — это билдер корутин, как launch или runBlocking, но с собственным представлением о времени. Внутри доступно свойство currentTime — показания виртуальных часов:

@Test
fun `задержка проматывается`() = runTest {
    val start = currentTime
    delay(1000)
    val end = currentTime
    assertEquals(1000, end - start)
}

Тест утверждает, что прошла секунда, и проходит за доли секунды. Увидев delay(1000), тестовый планировщик просто перевёл стрелки вперёд, ничего не ожидая по-настоящему.

Стрелки можно двигать и руками:

  • advanceTimeBy(ms) — промотать на указанное число миллисекунд и выполнить всё, что было запланировано на этот промежуток;
  • runCurrent() — выполнить задачи, назначенные ровно на текущий момент;
  • advanceUntilIdle() — промотать до тех пор, пока не закончится вся отложенная работа.

Про границу интервала стоит знать заранее, иначе час уйдёт на недоумение. advanceTimeBy(1000) выполняет задачи, запланированные строго до 1000-й миллисекунды. Задача, назначенная ровно на 1000, не выполнится — для неё нужен ещё и runCurrent(). В большинстве тестов проще не считать миллисекунды, а вызвать advanceUntilIdle().

Два тестовых диспетчера

StandardTestDispatcher стоит в runTest по умолчанию. Он складывает задачи в очередь и ждёт, пока вы сами проматаете время. Это даёт полный контроль над порядком выполнения.

UnconfinedTestDispatcher выполняет корутины сразу до первой точки приостановки, без очереди и без гарантий порядка. Удобен, когда важен результат, а не последовательность:

@Test
fun `сумма не зависит от порядка`() = runTest(UnconfinedTestDispatcher()) {
    val calc = Calculator()
    calc.addNumbers(listOf(10, 20, 30))
    advanceUntilIdle()
    assertEquals(60, calc.sum)
}

Подводный камень: исключения в дочерних корутинах

Вот это стоит прочитать до того, как потратить вечер. runTest собирает все исключения своих потомков. Любое исключение из дочерней корутины поднимается по дереву, и runTest его обнаруживает — тест падает.

Поэтому assertFailsWith работает только тогда, когда исключение выброшено прямо в его лямбде, то есть в самом теле теста:

@Test
fun `делить на ноль нельзя`() = runTest {
    assertFailsWith<ArithmeticException> {
        divideByZero()          // прямой вызов — работает
    }
}

А вот так не сработает: корутина, запущенная через launch, отдаст исключение родителю раньше, чем до него доберётся проверка.

Не спасёт ни supervisorScope, ни ленивый старт, ни попытка сохранить исключение в переменную. Если нужно проверить ошибку именно из дочерней корутины, try/catch придётся занести внутрь неё:

@Test
fun `ошибка в launch`() = runTest {
    var message: String? = null
    val job = launch {
        try {
            delay(10)
            throw IllegalStateException("Ошибка в launch")
        } catch (e: IllegalStateException) {
            message = e.message
        }
    }
    job.join()
    assertEquals("Ошибка в launch", message)
}

Пойманное внутри исключение к родителю не уходит, и тест проходит.

Что запомнить

  • Thread.sleep в тестах корутин не нужен никогда;
  • advanceUntilIdle() — ответ по умолчанию, когда тест «не дождался»;
  • правая граница у advanceTimeBy не включается;
  • assertFailsWith ловит только то, что брошено в теле теста.

Тестирование — одна из тем руководства по корутинам.