CommunityPesquisa e Análise de Dadosgithub.com

Detector de Testes Flaky

Detecte, analise e elimine testes flaky em qualquer executor de testes. Uma skill para agentes de IA que identifica falhas não determinísticas, categoriza causas raízes e aplica correções direcionadas.

O que é Detector de Testes Flaky?

Esta skill capacita agentes de IA a identificar, diagnosticar e eliminar testes flaky (instáveis) de forma automatizada. Ela executa a suíte de testes múltiplas vezes, coleta resultados em JSON e isola falhas que ocorrem de forma não determinística — ou seja, testes que às vezes passam e às vezes falham. A análise é dividida em cinco categorias principais de causa raiz: problemas de temporização assíncrona, estado mutável compartilhado, falta de isolamento entre testes, sensibilidade ao ambiente (como fuso horário ou sistema operacional) e condições de corrida. Para cada categoria, a skill fornece diagnósticos precisos usando comandos grep e opções específicas do executor, além de correções comprovadas com exemplos de código diff. A skill suporta os principais frameworks: Vitest, Jest, Playwright, Cypress, Mocha e AVA. Após as correções, ela gera automaticamente um relatório em FLAKY_REPORT.md documentando cada teste afetado, sua categoria, status e a correção aplicada. Por fim, a skill pode adicionar configuração de retry como rede de segurança em CI, permitindo que as equipes aumentem a confiabilidade de suas suítes de testes de forma sistemática e reproduzível.

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

Installed? Explore more Pesquisa e Análise de Dados skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Detector de Testes Flaky faz?

Identifique, diagnostique e elimine testes flaky. Executa sua suíte de testes várias vezes, isola falhas não determinísticas, categoriza causas raízes e aplica correções direcionadas.

Pipeline

  1. Detectar executor e configuração
  2. Coletar candidatos flaky via execuções repetidas
  3. Analisar padrões de falha para identificar a causa raiz
  4. Corrigir cada categoria de flakiness com estratégias comprovadas
  5. Verificar correções reexecutando o loop de detecção

Fase 1: Detectar executor e configuração

Leia a configuração do projeto:

cat package.json

Identifique o executor de testes:

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

Verifique configurações existentes de retry/flaky:

  • Vitest: retry em vitest.config.ts
  • Jest: testRetry em jest.config.ts ou jest.retryTimes() na configuração
  • Playwright: retries em playwright.config.ts
  • Cypress: retries em cypress.config.ts

Fase 2: Coletar candidatos flaky

Execute a suíte completa várias vezes e colete as falhas:

# Execute 3+ vezes, registre cada resultado
for i in 1 2 3; do
  echo "=== EXECUÇÃO $i ==="
  npx vitest --reporter=json 2>/dev/null | tee ".flaky-run-$i.json"
done

Para uma verificação rápida de flaky na última execução com falha:

npx vitest --reporter=json 2>/dev/null | tee ".flaky-last-run.json"

Para Jest:

for i in 1 2 3; do
  echo "=== EXECUÇÃO $i ==="
  npx jest --json 2>/dev/null | tee ".flaky-run-$i.json"
done

Para Playwright:

for i in 1 2 3; do
  echo "=== EXECUÇÃO $i ==="
  npx playwright test --reporter=json 2>/dev/null | tee ".flaky-run-$i.json"
done

Colete os resultados dos testes entre as execuções e identifique:

  • Sempre passa — estável, excluir da análise
  • Sempre falha — teste quebrado, reportar separadamente
  • Às vezes passa, às vezes falha — candidato FLAKY

Fase 3: Analisar causa raiz

Para cada candidato flaky, categorize pelo sintoma:

Categoria A: Temporização assíncrona

Sintomas:

  • Teste passa localmente, mas falha no CI (ambientes mais lentos)
  • Falha menciona timeout, setTimeout, setInterval, requestAnimationFrame
  • Asserções DOM falham intermitentemente em testes de navegador

Diagnóstico:

# Grep no arquivo de teste por padrões assíncronos
grep -n "setTimeout\|setInterval\|waitFor\|delay\|sleep\|requestAnimationFrame\|transition\|animation" <arquivo-de-teste>

Procure por:

  • Timeouts fixos em vez de polling/retry
  • Faltando waitFor ou expect.poll no Vitest
  • Faltando waitFor / findBy* no Testing Library
  • Asserções antes da conclusão de operações assíncronas

Categoria B: Estado mutável compartilhado

Sintomas:

  • Falhas dependem da ordem dos testes (executar --shard ou --bail 1 altera resultados)
  • Testes passam isoladamente, mas falham na suíte completa
  • Variáveis de módulo, singletons, globais

Diagnóstico:

# Verifique padrões de estado compartilhado
grep -n "let [a-z]* = \|var [a-z]* = \|const [a-z]* = \|global\." <arquivo-de-teste> | head -20

Procure por:

  • Variáveis de teste não reinicializadas entre testes
  • Estado de mock vazando entre testes (vi.fn() / jest.fn() não limpos)
  • Mutações de variáveis de ambiente sem restauração
  • Estado de sistema de arquivos ou banco de dados não limpo

Categoria C: Isolamento de teste

Sintomas:

  • Teste passa com --testPathPattern=<arquivo-único> mas falha na suíte completa
  • Teste falha quando testes específicos são executados antes dele

Diagnóstico: Execute testes em ordem aleatória para confirmar:

# Vitest (sequencial + aleatório)
npx vitest --sequence=sequential --reporter=json 2>/dev/null
npx vitest --sequence=random --reporter=json 2>/dev/null

Procure por:

  • Limpeza faltando em beforeEach / afterEach
  • Testes modificando DOM ou globais sem restaurar
  • Dados de banco/semente não isolados por teste
  • Implementações de mock vazando (vi.restoreAllMocks() / jest.restoreAllMocks() faltando)

Categoria D: Sensibilidade ao ambiente

Sintomas:

  • Falha apenas no CI (nunca localmente)
  • Falha em certas combinações de SO/navegador
  • Falha em horários específicos (fuso horário, data-dependente)

Diagnóstico: Procure por:

  • Valores de hora/data hardcoded
  • Formatação específica de localidade
  • Asserções dependentes de fuso horário
  • Suposições de resolução de tela, tamanho de viewport
  • Comportamento específico de versão Node.js/Python
  • Testes dependentes de rede (chamadas de API, rate limiting)

Categoria E: Condições de corrida

Sintomas:

  • Falhas envolvem operações concorrentes, Web Workers ou requisições paralelas
  • Promise.all, Promise.race, setTimeout com delay 0ms
  • Listeners de eventos em emissores compartilhados

Diagnóstico:

grep -n "Promise\.all\|Promise\.race\|Promise\.any\|Promise\.allSettled\|setTimeout\|setImmediate\|process\.nextTick" <arquivo-de-teste>

Fase 4: Aplicar correções

Aplique a correção com base na categoria detectada:

Correção A: Temporização assíncrona

Substitua padrões de temporização frágeis:

- await new Promise(r => setTimeout(r, 1000))
- expect(screen.getByText('Carregado')).toBeInTheDocument()
+ await waitFor(() => {
+   expect(screen.getByText('Carregado')).toBeInTheDocument()
+ }, { timeout: 5000, interval: 100 })

Para Vitest, use expect.poll ou waitFor:

import { waitFor } from '@testing-library/react'
// ou embutido no Vitest:
await expect.poll(() => getStatus(), { timeout: 5000, interval: 100 }).toBe('pronto')

Para Playwright, use localizadores com espera automática:

// Ruim:
await page.waitForTimeout(2000)
expect(await page.textContent('.status')).toBe('pronto')

// Bom:
await expect(page.locator('.status')).toHaveText('pronto', { timeout: 10000 })

Correção B: Estado mutável compartilhado

+ import { vi } from 'vitest'
+
+ beforeEach(() => {
+   vi.clearAllMocks()
+ })
+
+ afterEach(() => {
+   vi.restoreAllMocks()
+ })

Reinicialize estado de nível de módulo:

beforeEach(() => {
  // Reinicializar contadores, caches, singletons
  contador = 0
  cache.clear()
})

Isole mutações de configuração de runtime:

const MODO_RUNTIME_ORIGINAL = getRuntimeMode()
afterEach(() => {
  setRuntimeMode(MODO_RUNTIME_ORIGINAL)
})

Correção C: Isolamento de teste

+ beforeEach(() => {
+   document.body.innerHTML = ''
+   localStorage.clear()
+ })
+
+ afterEach(() => {
+   vi.restoreAllMocks()
+   vi.useRealTimers()
+ })

Para testes com banco de dados:

beforeEach(async () => {
  await db.migrate.latest()
  await db.seed.run()
})

afterEach(async () => {
  await db.migrate.rollback()
})

Correção D: Sensibilidade ao ambiente

Mock de código dependente de tempo:

beforeEach(() => {
  vi.useFakeTimers()
  vi.setSystemTime(new Date('2024-01-15T12:00:00Z'))
})

afterEach(() => {
  vi.useRealTimers()
})

Para testes sensíveis a localidade:

import { locale } from '../i18n'

beforeEach(() => {
  locale.set('pt-BR')
})

Para testes dependentes de rede, mock todas as chamadas externas:

vi.mock('../api/client')
// ou
global.fetch = vi.fn()

Correção E: Condições de corrida

Garanta processamento sequencial nos testes:

// Em vez de Promise.all, teste sequencialmente
await operacao1()
await operacao2()

Para testes com event emitter:

const eventos: string[] = []
emitter.on('data', (d) => eventos.push(d))

emitter.emit('data', 'a')
emitter.emit('data', 'b')
await vi.waitFor(() => {
  expect(eventos).toEqual(['a', 'b'])
})

Fase 5: Adicionar configuração de retry

Após corrigir a causa raiz, adicione retry como rede de segurança. Prefira arquivos de configuração específicos para CI ou comandos de CI com valores literais de retry em vez de ler variáveis de ambiente do runtime dentro da configuração de teste.

Vitest — vitest.ci.config.ts:

import baseConfig from './vitest.config'

export default defineConfig({
  ...baseConfig,
  test: {
    ...baseConfig.test,
    retry: 2,
    // Execução sequencial para testes flaky:
    sequence: {
      seed: 123,
      shuffle: false,
    },
  },
})

Execute no CI com vitest --config vitest.ci.config.ts.

Ou por teste/arquivo com vi.retry():

vi.retry(2)
describe('arquivo flaky', () => { ... })

Jest — jest.ci.config.ts (requer jest-retry):

const baseConfig = require('./jest.config')

export default {
  ...baseConfig,
  setupFilesAfterSetup: ['jest-retry'],
  retryTimes: 2,
}

Execute no CI com jest --config jest.ci.config.ts.

Playwright — playwright.ci.config.ts:

import baseConfig from './playwright.config'

export default defineConfig({
  ...baseConfig,
  retries: 2,
})

Execute no CI com playwright test --config playwright.ci.config.ts.


Fase 6: Verificar

Reexecute o loop de detecção de flaky:

for i in 1 2 3; do
  echo "=== EXECUÇÃO $i ==="
  npx vitest --reporter=json 2>/dev/null | tee ".flaky-verify-$i.json"
done

Compare os resultados entre as execuções:

  • Zero testes flaky — sucesso, reportar quantidade corrigida
  • Testes flaky restantes — iterar de volta para a Fase 3 com análise mais aprofundada

Geração de FLAKY_REPORT.md

Após corrigir, gere um relatório resumido:

# Relatório de Testes Flaky

| Teste | Executor | Categoria | Status | Correção aplicada |
|-------|----------|-----------|--------|-------------------|
| `auth.test.ts` | Vitest | Temporização assíncrona | Corrigido | Substituído `setTimeout` por `waitFor` |
| `api.test.ts` | Jest | Estado compartilhado | Corrigido | Adicionado `beforeEach` com limpeza |
| `login.spec.ts` | Playwright | Ambiente | Colocado em quarentena | Precisa de configuração de mock de API |

**Taxa de estabilidade:** 98/100 testes (98%)
**Próximo passo:** Revisar testes flaky restantes manualmente

Exemplo

Usuário: "nosso CI está cheio de testes flaky, usamos vitest"

Ações do agente:

  1. Executar npx vitest --reporter=json 3 vezes com loop
  2. Detectar 4 testes que passam/falham inconsistentemente entre execuções
  3. Para auth.test.ts: grep mostra setTimeout(500) antes da asserção
  4. Substituir por waitFor — auth.test.ts agora consistente em 3 execuções
  5. Para api.test.ts: token de autenticação em nível de módulo vaza entre testes
  6. Adicionar beforeEach(() => localStorage.clear()) — estável
  7. Configurar vitest.config.ts com retry no CI = 2
  8. Verificar: todos os 4 testes que eram flaky passam consistentemente
  9. Mostrar relatório

Usuário: "testes e2e do playwright flaky no CI"

Ações do agente:

  1. Executar npx playwright test --reporter=json 3 vezes, identificar login.spec.ts como flaky
  2. Analisar: usa page.waitForTimeout(3000) — problema de temporização assíncrona
  3. Substituir por await expect(page.locator('.dashboard')).toBeVisible({ timeout: 15000 })
  4. Definir retries: 2 em playwright.config.ts para CI
  5. Detectar também user-profile.spec.ts — sensibilidade ao ambiente (fuso horário)
  6. Mock de fuso horário na configuração do teste
  7. Verificar: 3/3 execuções passam para ambos os testes

Habilidades Relacionadas