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
- Détecter le runner et la configuration
- Récolter les candidats flaky via des exécutions répétées
- Analyser les schémas d'échec pour identifier la cause racine
- Corriger chaque catégorie de flaky avec des stratégies éprouvées
- 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 :
| Indicateur | Runner | Commande de base |
|---|---|---|
"vitest" dans devDependencies | Vitest | npx vitest |
"jest" dans devDependencies | Jest | npx jest |
"react-scripts" dans devDependencies | react-scripts | npx react-scripts test |
"@playwright/test" dans devDependencies | Playwright | npx playwright test |
"cypress" dans devDependencies | Cypress | npx cypress run |
"mocha" dans devDependencies | Mocha | npx mocha |
"ava" dans devDependencies | AVA | npx ava |
Vérifier la configuration existante de réexécution/flaky :
- Vitest :
retrydansvitest.config.ts - Jest :
testRetrydansjest.config.tsoujest.retryTimes()dans la configuration - Playwright :
retriesdansplaywright.config.ts - Cypress :
retriesdanscypress.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
waitForouexpect.pollmanquant dans VitestwaitFor/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 (
--shardou--bail 1change 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/afterEachmanquant - 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,setTimeoutavec 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 :
- Exécuter
npx vitest --reporter=json3 fois avec une boucle - Détecter 4 tests qui passent/échouent de manière incohérente sur les exécutions
- Pour
auth.test.ts: grep montresetTimeout(500)avant l'assertion - Remplacer par
waitFor—auth.test.tsdevient cohérent sur 3 exécutions - Pour
api.test.ts: le jeton d'authentification au niveau module fuit entre les tests - Ajouter
beforeEach(() => localStorage.clear())— stable - Configurer
vitest.config.tsavec CI retry = 2 - Vérifier : les 4 tests auparavant flaky passent de manière cohérente
- Afficher le rapport
Utilisateur : "les tests e2e Playwright sont flaky en CI"
Actions de l'agent :
- Exécuter
npx playwright test --reporter=json3 fois, identifierlogin.spec.tscomme flaky - Analyser : utilise
page.waitForTimeout(3000)— problème de temporisation asynchrone - Remplacer par
await expect(page.locator('.dashboard')).toBeVisible({ timeout: 15000 }) - Définir
retries: 2dansplaywright.config.tspour le CI - Détecter également
user-profile.spec.ts— sensibilité à l'environnement (fuseau horaire) - Simuler le fuseau horaire dans la configuration du test
- Vérifier : 3/3 exécutions passent pour les deux tests