Testear los actores invocados: sustituir la promesa y gobernar el flujo

Todo lo que hemos verificado hasta aquí vivía dentro de la máquina, donde el determinismo es gratis. El invoke rompe esa frontera a propósito: introduce una petición de red, una consulta a disco o un socket, es decir, precisamente aquello que tarda lo que quiere, falla cuando quiere y a veces no ocurre. La reacción instintiva es rendirse y probar solo el camino feliz con una espera generosa. La reacción correcta es recordar que el actor invocado se referencia por nombre y que ese nombre es un punto de sustitución de primera clase: la máquina nunca conoce la implementación, solo la etiqueta. Si en producción la etiqueta resuelve a una promesa real y en el test resuelve a una promesa cuya resolución la decides tú, entonces la latencia, el fallo y el orden dejan de ser accidentes del entorno y se convierten en tres líneas de tu escenario.

Sustituir por nombre, no parchear módulos

La disciplina empieza en la definición de la máquina: la lógica del actor se registra en setup bajo actors y el invoke la referencia con una cadena en src. Esa indirección es lo que hace testable el efecto, y renunciar a ella escribiendo la lógica en línea condena el test a interceptar el módulo global, con todo el acoplamiento y la fragilidad que eso arrastra.

import { setup, fromPromise, fromCallback, createActor, waitFor } from 'xstate'

export const perfil = setup({
  types: { context: {} as { id: string; usuario: Usuario | null; error: unknown } },
  actors: {
    cargarUsuario: fromPromise(async ({ input }: { input: { id: string } }) => {
      const res = await fetch(`/api/users/${input.id}`)
      if (!res.ok) throw new Error(`HTTP ${res.status}`)
      return (await res.json()) as Usuario
    }),
  },
}).createMachine({ /* estados inactivo, cargando, exito, fallo */ })

En el test, provide devuelve una máquina nueva con la misma topología y otra implementación. No muta la original, así que dos tests pueden usar dobles distintos sin interferirse, y la máquina de producción sigue intacta.

const conDoble = perfil.provide({
  actors: { cargarUsuario: fromPromise(async () => ({ id: '7', nombre: 'Ana' })) },
})

Una promesa cuyo reloj lleva el test

Un doble que resuelve inmediatamente prueba menos de lo que parece: la máquina pasa por cargando tan deprisa que ningún test puede afirmar nada sobre ese estado, y el indicador de carga —que es el motivo por el que existe el estado— queda sin verificar para siempre. La solución es la promesa diferida: se crea sin resolver y el test decide cuándo y cómo termina.

function diferida<T>() {
  let resolver!: (valor: T) => void
  let rechazar!: (error: unknown) => void
  const promesa = new Promise<T>((res, rej) => { resolver = res; rechazar = rej })
  return { promesa, resolver, rechazar }
}

test('la carga expone el estado intermedio y luego el resultado', async () => {
  const d = diferida<Usuario>()
  const actor = createActor(
    perfil.provide({ actors: { cargarUsuario: fromPromise(() => d.promesa) } }),
  ).start()

  actor.send({ type: 'CARGAR', id: '7' })
  expect(actor.getSnapshot().matches('cargando')).toBe(true)   // ventana observable

  d.resolver({ id: '7', nombre: 'Ana' })
  const fin = await waitFor(actor, (s) => s.matches('exito'))
  expect(fin.context.usuario?.nombre).toBe('Ana')
  actor.stop()
})

El valor de esta técnica va más allá de comprobar el indicador. Como la resolución es un acto explícito del test, puedes intercalar entre el envío y la resolución todo lo que quieras: enviar un segundo CARGAR para verificar que la petición vieja se descarta, mandar CANCELAR para comprobar que salir del estado detiene el actor, o resolver dos promesas en orden inverso al de creación para exponer una condición de carrera que en el entorno real aparecería una vez cada mil ejecuciones y jamás en una prueba manual.

Afirmar el contrato de ida

onDone y onError verifican la vuelta, pero la mitad de los defectos de integración viven en la ida: la máquina calcula mal el input y entrega un identificador equivocado, o el input es correcto pero se recalcula sobre un context obsoleto. Un doble que registra lo que recibe convierte esa ida en algo afirmable.

const entradas: unknown[] = []
const conEspia = perfil.provide({
  actors: {
    cargarUsuario: fromPromise(async ({ input }) => {
      entradas.push(input)
      return { id: '7', nombre: 'Ana' }
    }),
  },
})
const actor = createActor(conEspia).start()
actor.send({ type: 'CARGAR', id: '7' })
await waitFor(actor, (s) => s.matches('exito'))
expect(entradas).toEqual([{ id: '7' }])

Errores, cancelación y actores de larga vida

El camino de fallo se ejercita rechazando la diferida, y merece aserciones tan detalladas como el camino feliz: no basta con llegar a fallo, hay que comprobar que el motivo se conservó y que la transición de reintento vuelve a crear un actor nuevo en lugar de reutilizar el anterior.

d.rechazar(new Error('HTTP 500'))
const roto = await waitFor(actor, (s) => s.matches('fallo'))
expect((roto.context.error as Error).message).toBe('HTTP 500')

Para los actores que emiten a lo largo del tiempo, el doble natural es fromCallback: te da sendBack para inyectar eventos cuando quieras y una función de limpieza que puedes instrumentar para verificar que la cancelación ocurre de verdad al abandonar el estado. Esa comprobación es la que cierra el círculo abierto en el nivel de invoke: la promesa de que el efecto muere con su estado deja de ser confianza y pasa a ser una aserción.

const limpiezas: string[] = []
const conSondeo = tablero.provide({
  actors: {
    sondeo: fromCallback(({ sendBack }) => {
      sendBack({ type: 'TIC', n: 1 })
      return () => limpiezas.push('sondeo')
    }),
  },
})
const actor = createActor(conSondeo).start()
actor.send({ type: 'OBSERVAR' })
actor.send({ type: 'PARAR' })          // sale del estado que invoca
expect(limpiezas).toEqual(['sondeo'])

sequenceDiagram
participant T as test
participant M as maquina
participant D as doble diferido
T->>M: send CARGAR con id 7
M->>D: invoke con input id 7
T->>M: getSnapshot dice cargando
T->>D: resolver o rechazar a voluntad
D-->>M: onDone u onError
T->>M: waitFor y afirma el context