sametcelikbicak/flaky-test-detector

Détecter, analyser et éliminer les tests flaky sur n'importe quel runner de test. Une compétence d'agent IA qui identifie les échecs de test non déterministes, catégorise les causes racines et applique des correctifs ciblés.

Qu'est-ce que flaky-test-detector ?

Cette compétence pour agent IA permet d'identifier, diagnostiquer et éliminer les tests flaky dans un projet logiciel, quel que soit le runner de test utilisé (Vitest, Jest, Playwright, Cypress, Mocha, AVA, react-scripts). Elle fonctionne en exécutant la suite de tests trois fois consécutives en boucle, en collectant les résultats JSON pour identifier les tests qui passent de manière incohérente (parfois vert, parfois rouge). La compétence analyse ensuite chaque test flaky selon cinq catégories de causes racines : temporisation asynchrone, état mutable partagé, isolation des tests, sensibilité à l'environnement, et conditions de course. Pour chaque catégorie, elle propose des correctifs éprouvés (ex : remplacer `setTimeout` par `waitFor`, ajouter des nettoyages `beforeEach`, ou simuler le fuseau horaire). Enfin, elle ajoute une configuration de réexécution (retry) comme filet de sécurité et génère un rapport markdown (FLAKY_REPORT.md) pour le suivi. L'objectif est d'automatiser le cycle complet de détection, diagnostic, correction, vérification et rapport des tests flaky.

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

Installed? Explore more Recherche et analyse de données skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Détecteur de Tests Flaky

Identifiez, diagnostiquez et éliminez les tests flaky. Exécute votre suite de tests plusieurs fois, isole les échecs non déterministes, catégorise les causes racines et applique des correctifs ciblés.

Pipeline

  1. Détecter le runner et la configuration
  2. Récolter les candidats flaky via des exécutions répétées
  3. Analyser les schémas d'échec pour identifier la cause racine
  4. Corriger chaque catégorie de flaky avec des stratégies éprouvées
  5. Vérifier les correctifs en ré-exécutant la boucle de détection

Phase 1 : Détecter le runner et la configuration

Lire la configuration du projet :

cat package.json

Identifier le runner de test :

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

Vérifier la configuration existante de réexécution/flaky :

  • Vitest : retry dans vitest.config.ts
  • Jest : testRetry dans jest.config.ts ou jest.retryTimes() dans la configuration
  • Playwright : retries dans playwright.config.ts
  • Cypress : retries dans cypress.config.ts

Phase 2 : Récolter les candidats flaky

Exécuter la suite complète plusieurs fois et collecter les échecs :

# Exécuter 3+ fois, journaliser chaque résultat
for i in 1 2 3; do
  echo "=== RUN $i ==="
  npx vitest --reporter=json 2>/dev/null | tee ".flaky-run-$i.json"
done

Pour une vérification rapide du flaky sur la dernière exécution échouée :

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

Pour Jest :

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

Pour Playwright :

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

Collecter les résultats des tests sur toutes les exécutions et identifier :

  • Toujours passe — stable, exclure de l'analyse
  • Toujours échoue — test cassé, signaler séparément
  • Parfois passe, parfois échoue — candidat FLAKY

Phase 3 : Analyser la cause racine

Pour chaque candidat flaky, catégoriser par symptôme :

Catégorie A : Temporisation asynchrone

Symptômes :

  • Le test passe localement mais échoue en CI (environnements plus lents)
  • L'échec mentionne timeout, setTimeout, setInterval, requestAnimationFrame
  • Les assertions DOM échouent par intermittence dans les tests navigateur

Diagnostic :

# Chercher les motifs asynchrones dans le fichier de test
grep -n "setTimeout\|setInterval\|waitFor\|delay\|sleep\|requestAnimationFrame\|transition\|animation" <fichier-de-test>

Rechercher :

  • Des temporisations fixes au lieu de polling/réessais
  • waitFor ou expect.poll manquant dans Vitest
  • waitFor / findBy* manquant dans Testing Library
  • Des assertions avant la fin des opérations asynchrones

Catégorie B : État mutable partagé

Symptômes :

  • Les échecs dépendent de l'ordre des tests (--shard ou --bail 1 change les résultats)
  • Les tests passent isolément mais échouent dans la suite complète
  • Variables au niveau module, singletons, globales

Diagnostic :

# Vérifier les motifs d'état partagé
grep -n "let [a-z]* = \|var [a-z]* = \|const [a-z]* = \|global\." <fichier-de-test> | head -20

Rechercher :

  • Variables de test non réinitialisées entre les tests
  • État des mocks qui fuit entre les tests (vi.fn() / jest.fn() non nettoyé)
  • Mutations de variables d'environnement sans restauration
  • État du système de fichiers ou de la base de données non nettoyé

Catégorie C : Isolation des tests

Symptômes :

  • Le test passe avec --testPathPattern=<fichier-unique> mais échoue dans la suite complète
  • Le test échoue lorsque certains autres tests s'exécutent avant lui

Diagnostic : Exécuter les tests dans un ordre aléatoire pour confirmer :

# Vitest (séquentiel + aléatoire)
npx vitest --sequence=sequential --reporter=json 2>/dev/null
npx vitest --sequence=random --reporter=json 2>/dev/null

Rechercher :

  • Nettoyage beforeEach / afterEach manquant
  • Tests modifiant le DOM ou les globales sans restauration
  • Données de base de données / seeds non isolées par test
  • Implémentations de mock qui fuient (vi.restoreAllMocks() / jest.restoreAllMocks() manquant)

Catégorie D : Sensibilité à l'environnement

Symptômes :

  • Échoue uniquement en CI (jamais localement)
  • Échoue sur certaines combinaisons OS/navigateur
  • Échoue à des heures spécifiques (fuseau horaire, date)

Diagnostic : Rechercher :

  • Valeurs de temps/date codées en dur
  • Formatage spécifique à la locale
  • Assertions dépendantes du fuseau horaire
  • Hypothèses sur la résolution d'écran, la taille de la fenêtre
  • Comportements spécifiques à la version de Node.js/Python
  • Tests dépendants du réseau (appels API, limitation de débit)

Catégorie E : Conditions de course

Symptômes :

  • Les échecs impliquent des opérations concurrentes, Web Workers ou requêtes parallèles
  • Promise.all, Promise.race, setTimeout avec délai 0ms
  • Écouteurs d'événements sur des émetteurs partagés

Diagnostic :

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

Phase 4 : Appliquer les correctifs

Appliquer le correctif en fonction de la catégorie détectée :

Correctif A : Temporisation asynchrone

Remplacer les motifs de temporisation fragiles :

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

Pour Vitest, utiliser expect.poll ou waitFor :

import { waitFor } from '@testing-library/react'
// ou intégré à Vitest :
await expect.poll(() => getStatus(), { timeout: 5000, interval: 100 }).toBe('done')

Pour Playwright, utiliser les localisateurs à attente automatique :

// Mauvais :
await page.waitForTimeout(2000)
expect(await page.textContent('.status')).toBe('done')

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

Correctif B : État mutable partagé

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

Réinitialiser l'état au niveau du module :

beforeEach(() => {
  // Réinitialiser compteurs, caches, singletons
  counter = 0
  cache.clear()
})

Isoler les mutations de configuration d'exécution :

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

Correctif C : Isolation des tests

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

Pour les tests avec base de données :

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

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

Correctif D : Sensibilité à l'environnement

Simuler le code dépendant du temps :

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

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

Pour les tests sensibles à la locale :

import { locale } from '../i18n'

beforeEach(() => {
  locale.set('en-US')
})

Pour les tests dépendants du réseau, simuler tous les appels externes :

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

Correctif E : Conditions de course

Assurer un traitement séquentiel dans les tests :

// Au lieu de Promise.all, tester séquentiellement
await operation1()
await operation2()

Pour les tests avec émetteur d'événements :

const events: string[] = []
emitter.on('data', (d) => events.push(d))
emitter.emit('data', 'a')
emitter.emit('data', 'b')
await vi.waitFor(() => {
  expect(events).toEqual(['a', 'b'])
})

Phase 5 : Ajouter la configuration de réexécution

Après avoir corrigé la cause racine, ajouter une réexécution comme filet de sécurité. Privilégier les fichiers de configuration spécifiques au CI ou les commandes de job CI avec des valeurs littérales de réexécution, plutôt que de lire des variables d'environnement d'exécution dans la configuration de test.

Vitest — vitest.ci.config.ts :

import baseConfig from './vitest.config'

export default defineConfig({
  ...baseConfig,
  test: {
    ...baseConfig.test,
    retry: 2,
    // Exécution séquentielle pour les tests flaky :
    sequence: {
      seed: 123,
      shuffle: false,
    },
  },
})

Exécuter en CI avec vitest --config vitest.ci.config.ts.

Ou par test/fichier avec vi.retry() :

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

Jest — jest.ci.config.ts (nécessite jest-retry) :

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

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

Exécuter en CI avec jest --config jest.ci.config.ts.

Playwright — playwright.ci.config.ts :

import baseConfig from './playwright.config'

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

Exécuter en CI avec playwright test --config playwright.ci.config.ts.


Phase 6 : Vérifier

Ré-exécuter la boucle de détection du flaky :

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

Comparer les résultats sur toutes les exécutions :

  • Zéro test flaky — succès, signaler le nombre de tests corrigés
  • Tests flaky restants — revenir à la Phase 3 avec une analyse plus approfondie

Génération du rapport FLAKY_REPORT.md

Après les corrections, générer un rapport récapitulatif :

# Rapport de Tests Flaky

| Test | Runner | Catégorie | Statut | Correctif appliqué |
|------|--------|-----------|--------|--------------------|
| `auth.test.ts` | Vitest | Temporisation asynchrone | Corrigé | Remplacement de `setTimeout` par `waitFor` |
| `api.test.ts` | Jest | État partagé | Corrigé | Ajout du nettoyage `beforeEach` |
| `login.spec.ts` | Playwright | Environnement | Mis en quarantaine | Nécessite configuration de simulation de l'API |

**Taux de stabilité :** 98/100 tests (98%)
**Prochaine étape :** Examiner manuellement les tests flaky restants

Exemple

Utilisateur : "notre CI est plein de tests flaky, nous utilisons vitest"

Actions de l'agent :

  1. Exécuter npx vitest --reporter=json 3 fois avec une boucle
  2. Détecter 4 tests qui passent/échouent de manière incohérente sur les exécutions
  3. Pour auth.test.ts : grep montre setTimeout(500) avant l'assertion
  4. Remplacer par waitFor — auth.test.ts devient cohérent sur 3 exécutions
  5. Pour api.test.ts : le jeton d'authentification au niveau module fuit entre les tests
  6. Ajouter beforeEach(() => localStorage.clear()) — stable
  7. Configurer vitest.config.ts avec CI retry = 2
  8. Vérifier : les 4 tests auparavant flaky passent de manière cohérente
  9. Afficher le rapport

Utilisateur : "les tests e2e Playwright sont flaky en CI"

Actions de l'agent :

  1. Exécuter npx playwright test --reporter=json 3 fois, identifier login.spec.ts comme flaky
  2. Analyser : utilise page.waitForTimeout(3000) — problème de temporisation asynchrone
  3. Remplacer par await expect(page.locator('.dashboard')).toBeVisible({ timeout: 15000 })
  4. Définir retries: 2 dans playwright.config.ts pour le CI
  5. Détecter également user-profile.spec.ts — sensibilité à l'environnement (fuseau horaire)
  6. Simuler le fuseau horaire dans la configuration du test
  7. Vérifier : 3/3 exécutions passent pour les deux tests

Skills associés