Cómo detectar y solucionar flaky tests

Qué es, con precisión

Las dos herramientas más usadas lo definen desde ángulos distintos y complementarios.

Playwright da la definición operativa, la que se puede automatizar: un test inestable es el que «falló en la primera ejecución, pero pasó al reintentarlo». De ahí salen sus tres categorías de resultado: passed para los que pasaron a la primera, flaky para los que fallaron y pasaron al reintento, y failed para los que fallaron en todos los intentos.

Cypress lo define por su origen: tests que «fallan debido a condiciones impredecibles», y enumera las sospechosas habituales —animaciones, llamadas a APIs, disponibilidad del servidor o de la base de datos, dependencias de recursos y problemas de red—. También marca como Flaky a los tests que reintentaron y después pasaron.

Por qué es más caro de lo que parece

El costo visible es chico: unos minutos de reejecución. El costo real es de otro orden y llega por tres vías.

Primera: se rompe la señal. Una suite existe para responder una pregunta binaria —¿este cambio rompió algo?—. Cuando el rojo puede significar «rompiste algo» o «mala suerte», la respuesta deja de ser información y pasa a ser una probabilidad, que es mucho menos útil.

Segunda: se entrena el reflejo equivocado. Un equipo que convive con tests inestables aprende, con toda lógica, a reejecutar antes de investigar. Ese hábito funciona el 95 % de las veces y falla catastróficamente el 5 % restante: el día que el rojo era real, también se reejecutó y también se ignoró.

Tercera: se detiene el crecimiento de la suite. Cuando agregar tests significa agregar ruido, el equipo deja de agregar tests. La inestabilidad no solo daña la suite que existe: impide la que debería existir.

Paso 1: medir

El error más común es empezar por el arreglo. Sin medición no hay problema definido: hay una sensación compartida de que «la suite anda mal», que no se puede priorizar ni saber si mejoró.

Lo mínimo que hace falta para tener datos:

1. Activá los reintentos en integración continuaEn Playwright, con --retries=3 o desde la configuración. En Cypress, con runMode, cuyo valor por defecto es 0. Con eso, la herramienta empieza a etiquetar qué tests son inestables.
2. Guardá los resultados de cada ejecuciónNo solo el último. Un test que falla una vez cada veinte ejecuciones no aparece en una sola corrida, y suele ser el peor de todos.
3. Armá la lista ordenada por frecuenciaQué test, cuántas veces de cuántas, desde cuándo. Esa tabla es el punto de partida y también la forma de demostrar que el trabajo sirvió.
4. Fijá un objetivo explícitoPor ejemplo: ningún test con más del 1 % de inestabilidad en la rama principal. Sin objetivo, la tarea no termina nunca.

Los reintentos, bien entendidos

Acá está el malentendido que hace que el problema se vuelva crónico en muchos equipos. Los reintentos son una herramienta de medición, no un arreglo.

Vale la pena entender cómo funcionan por dentro, porque explica algo importante. Playwright, cuando un test falla, «descarta el proceso de trabajo completo junto con el navegador e inicia uno nuevo», y el proceso nuevo empieza reintentando el test que falló. La documentación señala por qué: «este esquema funciona perfectamente para tests independientes y garantiza que los tests que fallan no puedan afectar a los sanos».

Leído al revés, eso es una advertencia: el esquema funciona para tests independientes. Si tus tests dependen entre sí, descartar el proceso y reintentar uno solo puede producir resultados incoherentes, porque el estado que ese test necesitaba lo dejaba otro.

Los dos marcos permiten además acotar los reintentos a un grupo: en Playwright, con test.describe.configure({ retries: 2 }) para «un grupo específico de tests o un solo archivo». Eso es preferible a subir los reintentos globales, porque mantiene visible dónde está la deuda.

Paso 2: diagnosticar

El instinto es reproducirlo localmente. Casi nunca funciona: si el test falla una vez cada treinta ejecuciones y depende de la velocidad de la máquina de integración continua, en tu equipo va a pasar siempre.

La estrategia que sí funciona es diagnosticar con la evidencia que dejó la ejecución que falló. Para eso hay que configurarla antes:

• Traza de la ejecución. Es la herramienta más útil de todas: permite ver, paso a paso, el estado exacto de la página en el momento en que la aserción falló, con el DOM, la consola y las peticiones de red. Conviene configurarla para que se guarde en el primer reintento.
• Video y capturas de pantalla en los fallos. Más burdo que la traza, pero responde rápido la pregunta «¿qué estaba en pantalla?».
• Registros del sistema bajo prueba. Del mismo intervalo de tiempo. Es lo que distingue un problema del test de un problema del producto.
• Los artefactos conservados. Si tu integración continua borra los artefactos de las ejecuciones anteriores, estás tirando la única evidencia que tenías.

Y cuatro diferencias del entorno que explican la mayoría de los casos de «solo falla en CI»:

Las seis causas y su arreglo

1. Esperas por tiempo fijo

La causa número uno, con diferencia. Una pausa de dos segundos funciona hasta el día que algo tarda tres. El arreglo es esperar por condición en lugar de por tiempo: que el elemento esté visible, habilitado, con el texto buscado o desaparecido.

// Frágil: apuesta a que dos segundos alcanzan
await page.waitForTimeout(2000);
await expect(page.getByText('Pedido confirmado')).toBeVisible();

// Estable: espera a que la condición se cumpla, con su propio límite
await expect(page.getByText('Pedido confirmado')).toBeVisible();

La buena noticia es que las aserciones modernas de Playwright y Cypress ya esperan por condición. En la mayoría de los casos, el arreglo consiste en borrar las pausas manuales y confiar en la aserción tal como está diseñada.

2. Dependencia entre tests

El test B usa el registro que creó el test A. Funciona mientras el orden se mantenga, y se rompe al paralelizar, al reintentar uno solo o al ejecutar un archivo aislado. El arreglo: cada test crea lo que necesita y no supone nada del anterior.

3. Estado compartido

Un usuario de prueba, un producto, una configuración global que varios tests modifican. En paralelo, se pisan. El arreglo: datos propios por test, con identificadores únicos generados en el momento.

4. Fecha, hora y zona horaria

El clásico que pasa todo el año y falla el último día del mes, o a medianoche, o cuando cambia la hora. El arreglo: controlar el reloj con las utilidades que traen los marcos, o usar fechas relativas al momento de la ejecución en lugar de fechas fijas.

5. Servicios externos

Una API de terceros lenta, caída o con límite de peticiones. Cypress la nombra entre las condiciones impredecibles. El arreglo: simular la respuesta en los tests que no están probando esa integración. Los que sí la prueban, aislados y con la expectativa de que fallen por causas ajenas.

6. Condiciones de carrera en la interfaz

Animaciones a mitad de camino, contenido que se carga en dos etapas, elementos que se vuelven a montar y dejan inválida la referencia. El arreglo: esperar el estado final observable —el resultado, no el paso intermedio— y, si el marco lo permite, desactivar animaciones en el entorno de prueba.

Cuando el problema no es el test

De ahí que la primera pregunta ante un test que falla y luego pasa no sea «¿cómo lo estabilizo?» sino «¿esto es del test o del producto?». Dos señales que apuntan al producto:

• El fallo no es siempre el mismo. Un test inestable típico falla en el mismo punto; un defecto real suele producir fallos variados.
• Los registros del sistema muestran algo raro en ese momento. Un error, un tiempo de espera agotado, una excepción. Un test inestable por esperas no deja rastro en el servidor.

Aislamiento: la prevención que funciona

Casi todas las causas anteriores son variantes de un mismo problema de fondo: falta de aislamiento. Y eso se puede prevenir con cuatro reglas que valen la pena como acuerdo de equipo:

• Cada test crea los datos que necesita y los identifica de forma única.
• Ningún test depende del orden de ejecución ni del resultado de otro.
• Todo lo externo al sistema bajo prueba está simulado, salvo en los tests que prueban justamente esa integración.
• Nada que dependa del reloj real, de la zona horaria de la máquina o de una pausa fija.

Una prueba de que el aislamiento está bien: la suite tiene que dar el mismo resultado ejecutada en orden aleatorio. Si al aleatorizar el orden aparecen fallos, hay dependencias ocultas, y esa es una forma barata de encontrarlas antes de que se manifiesten solas.

Paso 4: cuarentena, con condiciones

A veces un test inestable bloquea al equipo y no hay tiempo de arreglarlo. La cuarentena es la salida legítima, y consiste en sacarlo del conjunto que puede detener el pipeline pero seguir ejecutándolo y registrando su resultado. Esa segunda mitad es la que hace la diferencia con apagarlo.

Dos condiciones que no son negociables si no querés que la cuarentena se convierta en un cementerio:

• Fecha límite. Anotada donde se vea. Un test en cuarentena sin fecha es un test eliminado con más pasos.
• Responsable. Una persona con nombre, no «el equipo».

Y un límite de cantidad que funciona como alarma: si hay más de un puñado de tests en cuarentena al mismo tiempo, el problema ya no son los tests sino la suite o el entorno, y conviene parar a resolver eso en lugar de seguir mandando casos a la lista.

Errores frecuentes

• Subir los reintentos hasta que la suite quede verde. Es la forma más eficiente de perder toda la información que la suite podía dar.
• Agregar una pausa fija para «estabilizar». Funciona hoy, falla en un mes y hace la suite más lenta para siempre.
• Intentar reproducirlo localmente antes de mirar la traza. Se pierde una tarde en algo que la evidencia respondía en cinco minutos.
• Apagar el test en lugar de ponerlo en cuarentena. Se pierde la visibilidad y a nadie le consta qué dejó de cubrirse.
• No aleatorizar el orden nunca. Las dependencias entre tests quedan latentes hasta que se manifiestan de la peor manera.
• Suponer que la culpa es siempre del test. A veces es del producto, y ahí estabilizarlo es tapar un defecto.
• Tratarlo como tarea individual. Sin un acuerdo de equipo sobre aislamiento, cada test nuevo reintroduce el problema.

Preguntas frecuentes

Fuentes

Documentación oficial y material de la comunidad consultados para esta guía. Fecha de consulta: 27 de julio de 2026.

Aportes de la comunidad Underc0de

1. Underc0de, foro. Overrides y mocking en DevTools, o cómo crear tu propio set de datos, por 0d1n, sección QA y Testing, 20 de febrero de 2025. Técnicas para controlar los datos de prueba, que es la base del aislamiento.
2. Underc0de, foro. Ayuda con Cypress, sección QA y Testing, 11 de julio de 2024.
3. Underc0de, foro. Sección QA y Testing. Hilos de la comunidad sobre automatización y herramientas de prueba.

Documentación oficial

4. Playwright. Retries. Definición de test inestable, las tres categorías de resultado, el descarte del proceso de trabajo al fallar, la nota sobre tests independientes y la configuración por grupo.
5. Cypress. Test Retries. Descripción de los tests inestables por sus causas impredecibles, configuración de runMode y openMode con valor por defecto 0, y etiquetado de los tests que reintentaron y pasaron.
6. Playwright. Trace viewer. La herramienta de traza usada para diagnosticar con la evidencia de la ejecución fallida.