¿Qué hace Detector de Pruebas Inestables (Flaky Test Detector)?
Identifica, diagnostica y elimina pruebas inestables. Ejecuta tu conjunto de pruebas varias veces, aísla los fallos no deterministas, categoriza las causas raíz y aplica correcciones específicas.
Proceso
- Detectar el ejecutor y la configuración
- Recolectar candidatos a inestables mediante ejecuciones repetidas
- Analizar patrones de fallo para identificar la causa raíz
- Corregir cada categoría de inestabilidad con estrategias probadas
- Verificar las correcciones repitiendo el bucle de detección
Fase 1: Detectar ejecutor y configuración
Lee la configuración del proyecto:
cat package.json
Identifica el ejecutor de pruebas:
| Indicador | Ejecutor | Comando base |
|---|---|---|
"vitest" en devDependencies | Vitest | npx vitest |
"jest" en devDependencies | Jest | npx jest |
"react-scripts" en devDependencies | react-scripts | npx react-scripts test |
"@playwright/test" en devDependencies | Playwright | npx playwright test |
"cypress" en devDependencies | Cypress | npx cypress run |
"mocha" en devDependencies | Mocha | npx mocha |
"ava" en devDependencies | AVA | npx ava |
Verifica la configuración existente de reintentos/inestabilidad:
- Vitest:
retryenvitest.config.ts - Jest:
testRetryenjest.config.tsojest.retryTimes()en la configuración - Playwright:
retriesenplaywright.config.ts - Cypress:
retriesencypress.config.ts
Fase 2: Recolectar candidatos a inestables
Ejecuta el conjunto completo de pruebas varias veces y recopila los fallos:
# Ejecutar 3+ veces, registrar cada resultado
for i in 1 2 3; do
echo "=== EJECUCIÓN $i ==="
npx vitest --reporter=json 2>/dev/null | tee ".flaky-run-$i.json"
done
Para una verificación rápida de inestabilidad en la última ejecución fallida:
npx vitest --reporter=json 2>/dev/null | tee ".flaky-last-run.json"
Para Jest:
for i in 1 2 3; do
echo "=== EJECUCIÓN $i ==="
npx jest --json 2>/dev/null | tee ".flaky-run-$i.json"
done
Para Playwright:
for i in 1 2 3; do
echo "=== EJECUCIÓN $i ==="
npx playwright test --reporter=json 2>/dev/null | tee ".flaky-run-$i.json"
done
Recopila los resultados de las pruebas en todas las ejecuciones e identifica:
- Siempre pasa — estable, excluir del análisis
- Siempre falla — prueba rota, reportar por separado
- A veces pasa, a veces falla — candidato a INESTABLE
Fase 3: Analizar la causa raíz
Para cada candidato inestable, categoriza según el síntoma:
Categoría A: Tiempo asíncrono
Síntomas:
- La prueba pasa localmente pero falla en CI (entornos más lentos)
- El fallo menciona tiempo de espera agotado,
setTimeout,setInterval,requestAnimationFrame - Las aserciones del DOM fallan de forma intermitente en pruebas de navegador
Diagnóstico:
# Buscar en el archivo de prueba patrones asíncronos
grep -n "setTimeout\|setInterval\|waitFor\|delay\|sleep\|requestAnimationFrame\|transition\|animation" <archivo-de-prueba>
Busca:
- Tiempos de espera fijos en lugar de sondeo/reintento
- Falta de
waitForoexpect.pollen Vitest - Falta de
waitFor/findBy*en Testing Library - Aserciones antes de que se completen las operaciones asíncronas
Categoría B: Estado mutable compartido
Síntomas:
- Los fallos dependen del orden de las pruebas (ejecutar
--shardo--bail 1cambia los resultados) - Las pruebas pasan de forma aislada pero fallan en el conjunto completo
- Variables a nivel de módulo, singletons, variables globales
Diagnóstico:
# Buscar patrones de estado compartido
grep -n "let [a-z]* = \|var [a-z]* = \|const [a-z]* = \|global\." <archivo-de-prueba> | head -20
Busca:
- Variables a nivel de prueba que no se restablecen entre pruebas
- Estado de mocks que se filtra entre pruebas (
vi.fn()/jest.fn()no limpiado) - Mutaciones de variables de entorno sin restauración
- Estado del sistema de archivos o base de datos no limpiado
Categoría C: Aislamiento de pruebas
Síntomas:
- La prueba pasa con
--testPathPattern=<archivo-único>pero falla en el conjunto completo - La prueba falla cuando otras pruebas específicas se ejecutan antes que ella
Diagnóstico: Ejecuta las pruebas en orden aleatorio para confirmar:
# Vitest (secuencial + aleatorio)
npx vitest --sequence=sequential --reporter=json 2>/dev/null
npx vitest --sequence=random --reporter=json 2>/dev/null
Busca:
- Falta de limpieza en
beforeEach/afterEach - Pruebas que modifican el DOM o variables globales sin restaurarlos
- Datos de base de datos/semilla no aislados por prueba
- Implementaciones de mocks que se filtran (falta
vi.restoreAllMocks()/jest.restoreAllMocks())
Categoría D: Sensibilidad al entorno
Síntomas:
- Falla solo en CI (nunca localmente)
- Falla en ciertas combinaciones de SO/navegador
- Falla en momentos específicos (zona horaria, fecha dependiente)
Diagnóstico: Busca:
- Valores de hora/fecha codificados
- Formato específico de configuración regional (locale)
- Aserciones dependientes de la zona horaria
- Suposiciones sobre resolución de pantalla, tamaño de ventana gráfica
- Comportamiento específico de la versión de Node.js/Python
- Pruebas dependientes de la red (llamadas a API, límite de tasa)
Categoría E: Condiciones de carrera
Síntomas:
- Los fallos involucran operaciones concurrentes, Web Workers o solicitudes paralelas
Promise.all,Promise.race,setTimeoutcon retardo de 0ms- Listeners de eventos en emisores compartidos
Diagnóstico:
grep -n "Promise\.all\|Promise\.race\|Promise\.any\|Promise\.allSettled\|setTimeout\|setImmediate\|process\.nextTick" <archivo-de-prueba>
Fase 4: Aplicar correcciones
Aplica la corrección según la categoría detectada:
Corrección A: Tiempo asíncrono
Reemplaza patrones de temporización frágiles:
- await new Promise(r => setTimeout(r, 1000))
- expect(screen.getByText('Cargado')).toBeInTheDocument()
+ await waitFor(() => {
+ expect(screen.getByText('Cargado')).toBeInTheDocument()
+ }, { timeout: 5000, interval: 100 })
Para Vitest, usa expect.poll o waitFor:
import { waitFor } from '@testing-library/react'
// o integrado en Vitest:
await expect.poll(() => getStatus(), { timeout: 5000, interval: 100 }).toBe('listo')
Para Playwright, usa localizadores con espera automática:
// Malo:
await page.waitForTimeout(2000)
expect(await page.textContent('.status')).toBe('listo')
// Bueno:
await expect(page.locator('.status')).toHaveText('listo', { timeout: 10000 })
Corrección B: Estado mutable compartido
+ import { vi } from 'vitest'
+
+ beforeEach(() => {
+ vi.clearAllMocks()
+ })
+
+ afterEach(() => {
+ vi.restoreAllMocks()
+ })
Restablece el estado a nivel de módulo:
beforeEach(() => {
// Restablecer contadores, cachés, singletons
contador = 0
cache.clear()
})
Aísla las mutaciones de configuración en tiempo de ejecución:
const MODO_EJECUCION_ORIGINAL = getModoEjecucion()
afterEach(() => {
setModoEjecucion(MODO_EJECUCION_ORIGINAL)
})
Corrección C: Aislamiento de pruebas
+ beforeEach(() => {
+ document.body.innerHTML = ''
+ localStorage.clear()
+ })
+
+ afterEach(() => {
+ vi.restoreAllMocks()
+ vi.useRealTimers()
+ })
Para pruebas respaldadas por base de datos:
beforeEach(async () => {
await db.migrate.latest()
await db.seed.run()
})
afterEach(async () => {
await db.migrate.rollback()
})
Corrección D: Sensibilidad al entorno
Simula código dependiente del tiempo:
beforeEach(() => {
vi.useFakeTimers()
vi.setSystemTime(new Date('2024-01-15T12:00:00Z'))
})
afterEach(() => {
vi.useRealTimers()
})
Para pruebas sensibles a la configuración regional:
import { locale } from '../i18n'
beforeEach(() => {
locale.set('en-US')
})
Para pruebas dependientes de la red, simula todas las llamadas externas:
vi.mock('../api/client')
// o
global.fetch = vi.fn()
Corrección E: Condiciones de carrera
Asegura el procesamiento secuencial en las pruebas:
// En lugar de Promise.all, probar secuencialmente
await operacion1()
await operacion2()
Para pruebas de emisores de eventos:
const eventos: string[] = []
emisor.on('datos', (d) => eventos.push(d))
emisor.emit('datos', 'a')
emisor.emit('datos', 'b')
await vi.waitFor(() => {
expect(eventos).toEqual(['a', 'b'])
})
Fase 5: Agregar configuración de reintentos
Después de corregir la causa raíz, agrega reintentos como red de seguridad. Prefiere archivos de configuración específicos de CI o comandos de trabajo de CI con valores de reintento literales en lugar de leer variables de entorno en tiempo de ejecución dentro de la configuración de prueba.
Vitest — vitest.ci.config.ts:
import baseConfig from './vitest.config'
export default defineConfig({
...baseConfig,
test: {
...baseConfig.test,
retry: 2,
// Ejecución secuencial para pruebas inestables:
sequence: {
seed: 123,
shuffle: false,
},
},
})
Ejecutar en CI con vitest --config vitest.ci.config.ts.
O por prueba/archivo con vi.retry():
vi.retry(2)
describe('archivo inestable', () => { ... })
Jest — jest.ci.config.ts (requiere jest-retry):
const baseConfig = require('./jest.config')
export default {
...baseConfig,
setupFilesAfterSetup: ['jest-retry'],
retryTimes: 2,
}
Ejecutar en CI con jest --config jest.ci.config.ts.
Playwright — playwright.ci.config.ts:
import baseConfig from './playwright.config'
export default defineConfig({
...baseConfig,
retries: 2,
})
Ejecutar en CI con playwright test --config playwright.ci.config.ts.
Fase 6: Verificar
Vuelve a ejecutar el bucle de detección de inestabilidad:
for i in 1 2 3; do
echo "=== EJECUCIÓN $i ==="
npx vitest --reporter=json 2>/dev/null | tee ".flaky-verify-$i.json"
done
Compara los resultados entre las ejecuciones:
- Cero pruebas inestables — éxito, informar la cantidad corregida
- Pruebas inestables restantes — iterar de vuelta a la Fase 3 con análisis más profundo
Generación del archivo FLAKY_REPORT.md
Después de corregir, genera un informe resumido:
# Informe de Pruebas Inestables
| Prueba | Ejecutor | Categoría | Estado | Corrección aplicada |
|--------|----------|-----------|--------|---------------------|
| `auth.test.ts` | Vitest | Tiempo asíncrono | Corregida | Se reemplazó `setTimeout` con `waitFor` |
| `api.test.ts` | Jest | Estado compartido | Corregida | Se agregó limpieza en `beforeEach` |
| `login.spec.ts` | Playwright | Entorno | En cuarentena | Requiere configuración de simulación de API |
**Tasa estable:** 98/100 pruebas (98%)
**Próximo paso:** Revisar las pruebas inestables restantes manualmente
Ejemplo
Usuario: "nuestro CI está lleno de pruebas inestables, usamos vitest"
Acciones del agente:
- Ejecutar
npx vitest --reporter=json3 veces con bucle - Detectar que 4 pruebas pasan/fallan de forma inconsistente entre ejecuciones
- Para
auth.test.ts: grep muestrasetTimeout(500)antes de la aserción - Reemplazar con
waitFor—auth.test.tsahora es consistente en 3 ejecuciones - Para
api.test.ts: el token de autenticación a nivel de módulo se filtra entre pruebas - Agregar
beforeEach(() => localStorage.clear())— estable - Configurar
vitest.config.tscon reintento de CI = 2 - Verificar: las 4 pruebas anteriormente inestables pasan de forma consistente
- Mostrar informe
Usuario: "las pruebas e2e de playwright son inestables en CI"
Acciones del agente:
- Ejecutar
npx playwright test --reporter=json3 veces, identificarlogin.spec.tscomo inestable - Analizar: usa
page.waitForTimeout(3000)— problema de tiempo asíncrono - Reemplazar con
await expect(page.locator('.dashboard')).toBeVisible({ timeout: 15000 }) - Establecer
retries: 2enplaywright.config.tspara CI - También detectar
user-profile.spec.ts— sensibilidad al entorno (zona horaria) - Simular zona horaria en la configuración de prueba
- Verificar: 3/3 ejecuciones pasan para ambas pruebas