runTest y el reloj que no existe

La primera vez que uno escribe un test sobre una función suspendida, el compilador exige un contexto de corrutina y la respuesta obvia es envolverlo en runBlocking, que compila, pasa y parece resolver el problema. Lo que en realidad ha ocurrido es que has aceptado tres cosas sin darte cuenta: que el test va a esperar en tiempo real cada delay que ejecute el código, que va a bloquear un hilo mientras tanto, y que si alguna corrutina hija se queda colgada el test no fallará con un mensaje sino que se quedará parado hasta que alguien mate el proceso. runTest existe para negar esas tres cosas a la vez, y la pieza que lo hace posible es un reloj que no mide nada.

Un reloj que se adelanta en vez de esperar

El corazón de kotlinx-coroutines-test es el planificador de pruebas, una cola de tareas ordenada por el instante virtual en que deben ejecutarse. Cuando una corrutina llama a delay, no se registra un temporizador del sistema: se inserta una entrada en esa cola con la marca tiempoActual + retardo. Y cuando el planificador se queda sin tareas pendientes para el instante presente, en lugar de dormir hace lo único que puede hacer sin mentir, que es mover el reloj hasta la siguiente tarea programada y ejecutarla.

import kotlinx.coroutines.test.runTest
import kotlinx.coroutines.delay
import kotlin.test.Test
import kotlin.test.assertEquals

class ReintentoTest {
    @Test
    fun agotaLosReintentosConEsperaExponencial() = runTest {
        val servicio = ServicioInestable(fallosAntesDeExito = 3)

        val resultado = conReintentos(intentos = 4, baseMs = 1_000) { servicio.pedir() }

        assertEquals("ok", resultado)
        assertEquals(7_000, currentTime)   // 1s + 2s + 4s, sin esperar nada
    }
}

Ese test comprueba una política de reintentos con espera exponencial que en producción tardaría siete segundos, y se ejecuta en menos de un milisegundo. Lo notable no es la velocidad sino que la aserción sobre currentTime convierte el tiempo en un valor observable: puedes afirmar que la espera acumulada fue exactamente la esperada, algo que en tiempo real solo podrías comprobar con tolerancias y que por tanto sería una aserción débil y propensa a fallos intermitentes.

La frontera de ese mecanismo es precisa y hay que tenerla presente. El reloj virtual pertenece al planificador, y el planificador solo gobierna a las corrutinas que se ejecutan en un dispatcher construido sobre él. En cuanto el código bajo prueba salta a un dispatcher real, la suspensión que ocurra allí es una suspensión de verdad, con temporizadores de verdad y espera de verdad.

suspend fun sincronizar() {
    withContext(Dispatchers.IO) {   // fuera del alcance del planificador
        delay(30_000)               // treinta segundos reales, también en el test
    }
}

Por qué runBlocking es la herramienta equivocada

La objeción habitual es que runBlocking funciona. Funciona en el sentido en que un test que pasa es un test que funciona, pero acumula cuatro defectos que solo se manifiestan cuando la suite ya es grande y cambiarla es caro.

runTest responde a los cuatro. Sustituye la espera por el salto de reloj, no bloquea porque en la JVM devuelve tras completar y en JS devuelve una promesa que el runner encadena, espera a que todas las corrutinas hijas del ámbito terminen antes de dar el test por bueno, y ejecuta todo sobre un dispatcher determinista de un solo hilo virtual.

Ese tipo de retorno merece atención porque es la causa de un error frecuente. La función devuelve un TestResult, un tipo cuya representación depende de la plataforma, y en JS y Wasm ese valor es la promesa que el runner necesita para saber cuándo ha terminado el test. Si lo descartas, el test acaba antes de haber empezado.

// Correcto: el TestResult se devuelve al runner
@Test
fun correcto() = runTest { assertEquals(2, sumar(1, 1)) }

// Incorrecto: en JS y Wasm el runner no espera y el test pasa sin comprobar nada
@Test
fun incorrecto() {
    runTest { assertEquals(2, sumar(1, 1)) }
}

flowchart TD
A[Cuerpo del test] --> B[Planificador de pruebas]
B --> C{Hay tareas para el instante actual}
C -->|Si| D[Ejecutar la siguiente tarea]
D --> C
C -->|No| E{Queda alguna tarea futura}
E -->|Si| F[Adelantar el reloj virtual hasta ella]
F --> D
E -->|No| G[Esperar a las corrutinas hijas del ambito]
G --> H[Fallar si alguna sigue viva o el limite real expira]

Terminación, ámbito de fondo y límite real

Al salir del cuerpo del test, runTest no da la prueba por terminada de inmediato: espera a que todas las corrutinas lanzadas en el ámbito del test hayan completado. Esa espera es una comprobación disfrazada, porque una corrutina que nunca termina delata una fuga en el código bajo prueba. Pero hay una categoría legítima de corrutinas que jamás terminan por diseño —un recolector de un flujo infinito, un observador de estado, un bucle de sondeo— y para ellas existe un ámbito distinto.

@Test
fun observaLosCambiosDeEstado() = runTest {
    val vistos = mutableListOf<Estado>()

    // Colector infinito: vive en backgroundScope y se cancela al acabar el test
    backgroundScope.launch(UnconfinedTestDispatcher(testScheduler)) {
        modelo.estado.collect { vistos += it }
    }

    modelo.pulsar()
    advanceUntilIdle()

    assertEquals(listOf(Estado.Inicial, Estado.Pulsado), vistos)
}

La distinción es conceptual y no una comodidad: lo que lanzas en el ámbito del test es trabajo cuya terminación forma parte de lo que estás comprobando; lo que lanzas en el ámbito de fondo es andamiaje que existe para observar y que debe desaparecer sin ceremonia cuando el test acaba.

Queda una última salvaguarda, y esta sí mide tiempo real. runTest acepta un parámetro de límite, con un valor por defecto de diez segundos, que se cuenta con el reloj del sistema y aborta el test si se supera. Existe precisamente porque el tiempo virtual no protege de los bloqueos: si el código bajo prueba se queda esperando en un candado o en una llamada sincrónica, el planificador no puede adelantar nada y sin ese límite el test se colgaría igual que con runBlocking.