Dispatchers de prueba: el estándar, el no confinado y la inyección

Un dispatcher decide dos cosas: en qué hilo corre una corrutina y cuándo. Los dispatchers de prueba renuncian por completo a la primera —todo ocurre en un único hilo— para tomar el control absoluto de la segunda, y ahí es donde empieza la parte interesante. El estándar convierte el momento de la ejecución en algo que tú decides explícitamente llamando a una función; el no confinado lo elimina como problema ejecutando todo lo que pueda tan pronto como pueda. Elegir entre ambos no es una cuestión de gusto sino de qué propiedad quieres que tu test verifique, y la elección equivocada produce tests que pasan mientras el código está roto.

Dos modelos de ejecución, no dos sabores

El StandardTestDispatcher no ejecuta nada por su cuenta. Cuando alguien lanza una corrutina sobre él, la tarea se deposita en la cola del planificador y el control vuelve inmediatamente a quien llamó. La corrutina solo avanza cuando el hilo del test cede el control, sea porque el cuerpo del test se suspende o porque llamas explícitamente a uno de los verbos del planificador. Ese comportamiento reproduce exactamente lo que ocurre en producción con un dispatcher real: launch programa trabajo, no lo ejecuta.

El UnconfinedTestDispatcher hace lo contrario. Ejecuta la corrutina recién lanzada de inmediato, en el mismo hilo y dentro de la misma llamada a launch, y sigue ejecutándola hasta que se suspende de verdad; en ese punto devuelve el control. El efecto es una ejecución en profundidad que hace que el código parezca sincrónico.

@Test
fun elEstandarNoEjecutaHastaQueSeLoPides() = runTest {
    var visto = false
    launch { visto = true }          // encolada, no ejecutada
    assertFalse(visto)
    runCurrent()                     // ahora sí
    assertTrue(visto)
}

@Test
fun elNoConfinadoEjecutaAlVuelo() = runTest(UnconfinedTestDispatcher()) {
    var visto = false
    launch { visto = true }          // ejecutada dentro del propio launch
    assertTrue(visto)
}

La conclusión práctica es incómoda: el no confinado es cómodo precisamente porque oculta la asincronía, y ocultar la asincronía es la mejor forma de no detectar los errores que la asincronía provoca. Un componente que publica un estado antes de haber terminado de inicializarlo, o que asume que una corrutina lanzada ya ha corrido cuando la siguiente línea se ejecuta, pasará el test con el no confinado y fallará en producción con cualquier dispatcher real.

Inyectar el dispatcher en vez de codificarlo

Ningún dispatcher de prueba sirve de nada si el código bajo prueba escribe Dispatchers.IO en el cuerpo de una función. Ese literal es una dependencia con la infraestructura tan real como una conexión a base de datos, y como toda dependencia con la infraestructura debe entrar por la puerta, no aparecer por dentro. La forma canónica es un parámetro con valor por defecto: la producción no nota nada y el test puede sustituirlo.

// Antes: intestable, el salto es invisible desde fuera
class RepositorioMalo(private val api: Api) {
    suspend fun cargar(id: String): Ficha =
        withContext(Dispatchers.IO) { api.pedir(id) }
}

// Después: la dependencia temporal es explícita y sustituible
class Repositorio(
    private val api: Api,
    private val io: CoroutineDispatcher = Dispatchers.IO,
) {
    suspend fun cargar(id: String): Ficha =
        withContext(io) { api.pedir(id) }
}

@Test
fun cargaLaFicha() = runTest {
    val repo = Repositorio(ApiFalsa(), StandardTestDispatcher(testScheduler))
    assertEquals(Ficha("7"), repo.cargar("7"))
}

Cuando una clase necesita más de un dispatcher —uno para entrada y salida, otro para cálculo, otro para la interfaz— la respuesta no es multiplicar parámetros sino agrupar los tres en una única abstracción con un nombre propio, de modo que la sustitución en los tests sea una sola línea y no tres.

Hay un caso especial que no se resuelve con inyección porque el dispatcher no lo elige tu código: Dispatchers.Main, que en aplicaciones de interfaz lo instala la plataforma y no existe en un entorno de pruebas. Para eso la biblioteca ofrece dos funciones que sustituyen la instancia global, y su uso obliga a devolverla a su estado original al terminar.

class ReglaDelPrincipal(
    private val dispatcher: TestDispatcher = UnconfinedTestDispatcher(),
) : TestWatcher() {
    override fun starting(d: Description) = Dispatchers.setMain(dispatcher)
    override fun finished(d: Description) = Dispatchers.resetMain()
}

Los tres verbos del planificador

Con el dispatcher estándar el test decide cuándo avanza el trabajo, y para eso el planificador expone tres operaciones que no son intercambiables. runCurrent ejecuta todas las tareas programadas para el instante virtual presente y se detiene; no toca el reloj. advanceTimeBy adelanta el reloj una cantidad determinada ejecutando por el camino todo lo programado estrictamente antes del instante de destino, lo que deja pendiente de forma deliberada lo que caiga justo en la frontera. advanceUntilIdle vacía la cola entera, saltando el reloj tantas veces como haga falta hasta que no queda nada.

@Test
fun elDebounceDescartaLasPulsacionesRapidas() = runTest {
    val buscador = Buscador(retardoMs = 300)

    buscador.teclear("k")
    advanceTimeBy(100)      // aún no ha saltado la búsqueda
    buscador.teclear("ko")
    advanceTimeBy(100)
    buscador.teclear("kot")

    runCurrent()
    assertEquals(0, buscador.consultasLanzadas)

    advanceUntilIdle()      // deja pasar el debounce completo
    assertEquals(listOf("kot"), buscador.consultas)
}

La elección entre ellos comunica intención. Usar advanceUntilIdle en todas partes es cómodo y equivale a decir que ocurra todo: sirve para comprobar el resultado final, pero renuncia a afirmar nada sobre los estados intermedios, que es justamente donde viven los errores de orden. Usar runCurrent y advanceTimeBy con valores concretos es lo que convierte un test en una afirmación sobre la secuencia y no solo sobre el destino.

flowchart TD
A[Lanzar corrutina] --> B{Que dispatcher}
B -->|Estandar| C[Encolar en el planificador]
C --> D[El control vuelve al test]
D --> E{Que verbo llama el test}
E -->|runCurrent| F[Solo el instante actual]
E -->|advanceTimeBy| G[Hasta el instante indicado]
E -->|advanceUntilIdle| H[Vaciar la cola entera]
B -->|No confinado| I[Ejecutar ya en este hilo]
I --> J[Hasta la primera suspension real]