Detector de Pruebas Inestables (Flaky Test Detector)

Detecta, analiza y elimina pruebas inestables en cualquier ejecutor de pruebas. Una habilidad de agente de IA que identifica fallos no deterministas, categoriza las causas raíz y aplica correcciones específicas.

¿Qué es Detector de Pruebas Inestables (Flaky Test Detector)?

Esta habilidad permite a un agente de IA diagnosticar y corregir sistemáticamente pruebas inestables (flaky tests) en cualquier proyecto de software. Ejecuta el conjunto de pruebas varias veces para identificar aquellas que fallan de forma intermitente, analiza los patrones de fallo para determinar la causa raíz (por ejemplo, problemas de sincronización asíncrona, estado mutable compartido, falta de aislamiento, sensibilidad al entorno o condiciones de carrera) y aplica correcciones probadas y específicas para cada categoría. Soporta los ejecutores de pruebas más populares como Vitest, Jest, Playwright, Cypress, Mocha y AVA, y también configura reintentos como red de seguridad. Finalmente, verifica las correcciones repitiendo el bucle de detección y genera un informe resumido.

Compatible con✓Claude Code~Codex CLI✓Cursor✓OpenCode✓Windsurf
npx skills add sametcelikbicak/flaky-test-detector

Installed? Explore more Investigación y análisis de datos skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿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

  1. Detectar el ejecutor y la configuración
  2. Recolectar candidatos a inestables mediante ejecuciones repetidas
  3. Analizar patrones de fallo para identificar la causa raíz
  4. Corregir cada categoría de inestabilidad con estrategias probadas
  5. 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:

IndicadorEjecutorComando base
"vitest" en devDependenciesVitestnpx vitest
"jest" en devDependenciesJestnpx jest
"react-scripts" en devDependenciesreact-scriptsnpx react-scripts test
"@playwright/test" en devDependenciesPlaywrightnpx playwright test
"cypress" en devDependenciesCypressnpx cypress run
"mocha" en devDependenciesMochanpx mocha
"ava" en devDependenciesAVAnpx ava

Verifica la configuración existente de reintentos/inestabilidad:

  • Vitest: retry en vitest.config.ts
  • Jest: testRetry en jest.config.ts o jest.retryTimes() en la configuración
  • Playwright: retries en playwright.config.ts
  • Cypress: retries en cypress.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 waitFor o expect.poll en 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 --shard o --bail 1 cambia 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, setTimeout con 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:

  1. Ejecutar npx vitest --reporter=json 3 veces con bucle
  2. Detectar que 4 pruebas pasan/fallan de forma inconsistente entre ejecuciones
  3. Para auth.test.ts: grep muestra setTimeout(500) antes de la aserción
  4. Reemplazar con waitFor — auth.test.ts ahora es consistente en 3 ejecuciones
  5. Para api.test.ts: el token de autenticación a nivel de módulo se filtra entre pruebas
  6. Agregar beforeEach(() => localStorage.clear()) — estable
  7. Configurar vitest.config.ts con reintento de CI = 2
  8. Verificar: las 4 pruebas anteriormente inestables pasan de forma consistente
  9. Mostrar informe

Usuario: "las pruebas e2e de playwright son inestables en CI"

Acciones del agente:

  1. Ejecutar npx playwright test --reporter=json 3 veces, identificar login.spec.ts como inestable
  2. Analizar: usa page.waitForTimeout(3000) — problema de tiempo asíncrono
  3. Reemplazar con await expect(page.locator('.dashboard')).toBeVisible({ timeout: 15000 })
  4. Establecer retries: 2 en playwright.config.ts para CI
  5. También detectar user-profile.spec.ts — sensibilidad al entorno (zona horaria)
  6. Simular zona horaria en la configuración de prueba
  7. Verificar: 3/3 ejecuciones pasan para ambas pruebas

Skills relacionados