Was macht Flaky-Test-Erkenner?
Identifiziere, diagnostiziere und beseitige flaky Tests. Führt deine Testsuite mehrmals aus, isoliert nicht-deterministische Fehler, kategorisiert Grundursachen und wendet gezielte Korrekturen an.
Pipeline
- Erkenne Runner und Konfiguration
- Sammle flaky Kandidaten durch wiederholte Ausführung
- Analysiere Fehlermuster, um die Grundursache zu identifizieren
- Korrigiere jede Flakiness-Kategorie mit bewährten Strategien
- Überprüfe Korrekturen durch erneutes Durchlaufen des Erkennungszyklus
Phase 1: Runner und Konfiguration erkennen
Projekteinrichtung lesen:
cat package.json
Den Test-Runner identifizieren:
| Indikator | Runner | Basiskommando |
|---|---|---|
"vitest" in devDependencies | Vitest | npx vitest |
"jest" in devDependencies | Jest | npx jest |
"react-scripts" in devDependencies | react-scripts | npx react-scripts test |
"@playwright/test" in devDependencies | Playwright | npx playwright test |
"cypress" in devDependencies | Cypress | npx cypress run |
"mocha" in devDependencies | Mocha | npx mocha |
"ava" in devDependencies | AVA | npx ava |
Vorhandene Wiederholungs-/Flaky-Konfiguration prüfen:
- Vitest:
retryinvitest.config.ts - Jest:
testRetryinjest.config.tsoderjest.retryTimes()im Setup - Playwright:
retriesinplaywright.config.ts - Cypress:
retriesincypress.config.ts
Phase 2: Flaky Kandidaten sammeln
Die gesamte Suite mehrmals ausführen und Fehler sammeln:
# 3+ Mal ausführen, jedes Ergebnis protokollieren
for i in 1 2 3; do
echo "=== RUN $i ==="
npx vitest --reporter=json 2>/dev/null | tee ".flaky-run-$i.json"
done
Für eine schnelle Flaky-Überprüfung des letzten fehlgeschlagenen Durchlaufs:
npx vitest --reporter=json 2>/dev/null | tee ".flaky-last-run.json"
Für Jest:
for i in 1 2 3; do
echo "=== RUN $i ==="
npx jest --json 2>/dev/null | tee ".flaky-run-$i.json"
done
Für 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
Testergebnisse über mehrere Durchläufe sammeln und identifizieren:
- Besteht immer — stabil, von der Analyse ausschließen
- Schlägt immer fehl — defekter Test, separat melden
- Besteht manchmal, schlägt manchmal fehl — FLAKY-Kandidat
Phase 3: Grundursache analysieren
Für jeden flaky Kandidaten nach Symptom kategorisieren:
Kategorie A: Async-Timing
Symptome:
- Test besteht lokal, schlägt aber auf CI fehl (langsamere Umgebungen)
- Fehler erwähnt Timeout,
setTimeout,setInterval,requestAnimationFrame - DOM-Assertions schlagen in Browser-Tests inkonsistent fehl
Diagnose:
# Die Testdatei nach Async-Mustern durchsuchen
grep -n "setTimeout\|setInterval\|waitFor\|delay\|sleep\|requestAnimationFrame\|transition\|animation" <test-datei>
Achten auf:
- Feste Timeouts anstelle von Polling/Wiederholungen
- Fehlendes
waitForoderexpect.pollin Vitest - Fehlendes
waitFor/findBy*in Testing Library - Assertions vor Abschluss asynchroner Operationen
Kategorie B: Gemeinsam genutzter veränderlicher Zustand
Symptome:
- Fehler hängen von der Testreihenfolge ab (Ausführen mit
--shardoder--bail 1ändert Ergebnisse) - Tests bestehen isoliert, schlagen aber in der gesamten Suite fehl
- Modulebene-Variablen, Singletons, Globals
Diagnose:
# Nach Mustern für gemeinsam genutzten Zustand suchen
grep -n "let [a-z]* = \|var [a-z]* = \|const [a-z]* = \|global\." <test-datei> | head -20
Achten auf:
- Testebene-Variablen, die nicht zwischen Tests zurückgesetzt werden
- Mock-Zustand, der zwischen Tests durchsickert (
vi.fn()/jest.fn()nicht bereinigt) - Mutationen von Umgebungsvariablen ohne Wiederherstellung
- Dateisystem- oder Datenbankzustand, der nicht bereinigt wurde
Kategorie C: Testisolation
Symptome:
- Test besteht mit
--testPathPattern=<einzeldatei>aber schlägt in der gesamten Suite fehl - Test schlägt fehl, wenn bestimmte andere Tests davor ausgeführt werden
Diagnose: Tests in zufälliger Reihenfolge ausführen, um zu bestätigen:
# Vitest (sequentiell + zufällig)
npx vitest --sequence=sequential --reporter=json 2>/dev/null
npx vitest --sequence=random --reporter=json 2>/dev/null
Achten auf:
- Fehlende
beforeEach/afterEachBereinigung - Tests, die DOM oder Globals ändern, ohne sie wiederherzustellen
- Datenbank-/Seed-Daten, die nicht pro Test isoliert sind
- Durchsickernde Mock-Implementierungen (
vi.restoreAllMocks()/jest.restoreAllMocks()fehlt)
Kategorie D: Umgebungsabhängigkeit
Symptome:
- Schlägt nur auf CI fehl (nie lokal)
- Schlägt bei bestimmten OS/Browser-Kombinationen fehl
- Schlägt zu bestimmten Zeiten fehl (Zeitzone, datumsabhängig)
Diagnose: Achten auf:
- Hartcodierte Zeit-/Datumswerte
- Gebietsschema-spezifische Formatierung
- Zeitzonenabhängige Assertions
- Bildschirmauflösung, Viewport-Größenannahmen
- Node.js/Python-Versions-spezifisches Verhalten
- Netzwerkabhängige Tests (API-Aufrufe, Ratenbegrenzung)
Kategorie E: Wettlaufsituationen
Symptome:
- Fehler betreffen gleichzeitige Operationen, Web Worker oder parallele Anfragen
Promise.all,Promise.race,setTimeoutmit 0ms Verzögerung- Ereignis-Listener auf gemeinsam genutzten Emittern
Diagnose:
grep -n "Promise\.all\|Promise\.race\|Promise\.any\|Promise\.allSettled\|setTimeout\|setImmediate\|process\.nextTick" <test-datei>
Phase 4: Korrekturen anwenden
Korrektur basierend auf der erkannten Kategorie anwenden:
Korrektur A: Async-Timing
Anfällige Timing-Muster ersetzen:
- await new Promise(r => setTimeout(r, 1000))
- expect(screen.getByText('Loaded')).toBeInTheDocument()
+ await waitFor(() => {
+ expect(screen.getByText('Loaded')).toBeInTheDocument()
+ }, { timeout: 5000, interval: 100 })
Für Vitest expect.poll oder waitFor verwenden:
import { waitFor } from '@testing-library/react'
// oder Vitest-eingebaut:
await expect.poll(() => getStatus(), { timeout: 5000, interval: 100 }).toBe('done')
Für Playwright Auto-Waiting-Lokatoren verwenden:
// Schlecht:
await page.waitForTimeout(2000)
expect(await page.textContent('.status')).toBe('done')
// Gut:
await expect(page.locator('.status')).toHaveText('done', { timeout: 10000 })
Korrektur B: Gemeinsam genutzter veränderlicher Zustand
+ import { vi } from 'vitest'
+
+ beforeEach(() => {
+ vi.clearAllMocks()
+ })
+
+ afterEach(() => {
+ vi.restoreAllMocks()
+ })
Modulebene-Zustand zurücksetzen:
beforeEach(() => {
// Zähler, Caches, Singletons zurücksetzen
counter = 0
cache.clear()
})
Laufzeitkonfigurationsmutationen isolieren:
const ORIGINAL_RUNTIME_MODE = getRuntimeMode()
afterEach(() => {
setRuntimeMode(ORIGINAL_RUNTIME_MODE)
})
Korrektur C: Testisolation
+ beforeEach(() => {
+ document.body.innerHTML = ''
+ localStorage.clear()
+ })
+
+ afterEach(() => {
+ vi.restoreAllMocks()
+ vi.useRealTimers()
+ })
Für datenbankgestützte Tests:
beforeEach(async () => {
await db.migrate.latest()
await db.seed.run()
})
afterEach(async () => {
await db.migrate.rollback()
})
Korrektur D: Umgebungsabhängigkeit
Zeitabhängigen Code mocken:
beforeEach(() => {
vi.useFakeTimers()
vi.setSystemTime(new Date('2024-01-15T12:00:00Z'))
})
afterEach(() => {
vi.useRealTimers()
})
Für gebietsschema-sensitive Tests:
import { locale } from '../i18n'
beforeEach(() => {
locale.set('en-US')
})
Für netzwerkabhängige Tests alle externen Aufrufe mocken:
vi.mock('../api/client')
// oder
global.fetch = vi.fn()
Korrektur E: Wettlaufsituationen
Sequenzielle Verarbeitung in Tests sicherstellen:
// Statt Promise.all sequentiell testen
await operation1()
await operation2()
Für Ereignis-Emitter-Tests:
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: Wiederholungskonfiguration hinzufügen
Nach der Behebung der Grundursache eine Wiederholung als Sicherheitsnetz hinzufügen. Bevorzuge CI-spezifische Konfigurationsdateien oder CI-Job-Befehle mit literalem Wiederholungswert anstatt Laufzeit-Umgebungsvariablen in der Testkonfiguration zu lesen.
Vitest — vitest.ci.config.ts:
import baseConfig from './vitest.config'
export default defineConfig({
...baseConfig,
test: {
...baseConfig.test,
retry: 2,
// Sequenzielle Ausführung für flaky Tests:
sequence: {
seed: 123,
shuffle: false,
},
},
})
In CI ausführen mit vitest --config vitest.ci.config.ts.
Oder pro Test/Datei mit vi.retry():
vi.retry(2)
describe('flaky datei', () => { ... })
Jest — jest.ci.config.ts (erfordert jest-retry):
const baseConfig = require('./jest.config')
export default {
...baseConfig,
setupFilesAfterSetup: ['jest-retry'],
retryTimes: 2,
}
In CI ausführen mit jest --config jest.ci.config.ts.
Playwright — playwright.ci.config.ts:
import baseConfig from './playwright.config'
export default defineConfig({
...baseConfig,
retries: 2,
})
In CI ausführen mit playwright test --config playwright.ci.config.ts.
Phase 6: Überprüfung
Den Flaky-Erkennungszyklus erneut durchlaufen:
for i in 1 2 3; do
echo "=== RUN $i ==="
npx vitest --reporter=json 2>/dev/null | tee ".flaky-verify-$i.json"
done
Ergebnisse über Durchläufe vergleichen:
- Null flaky Tests — Erfolg, Anzahl der behobenen Tests melden
- Verbleibende flaky Tests — Zurück zu Phase 3 mit tiefergehender Analyse
FLAKY_REPORT.md Generierung
Nach der Korrektur einen zusammenfassenden Bericht generieren:
# Flaky-Test-Bericht
| Test | Runner | Kategorie | Status | Angewandte Korrektur |
|------|--------|-----------|--------|----------------------|
| `auth.test.ts` | Vitest | Async-Timing | Behoben | `setTimeout` durch `waitFor` ersetzt |
| `api.test.ts` | Jest | Gemeinsam genutzter Zustand | Behoben | `beforeEach` Bereinigung hinzugefügt |
| `login.spec.ts` | Playwright | Umgebung | Unter Quarantäne | API-Mock-Setup erforderlich |
**Stabilitätsrate:** 98/100 Tests (98%)
**Nächster Schritt:** Verbleibende flaky Tests manuell überprüfen
Beispiel
Benutzer: "Unser CI ist voller flaky Tests, wir verwenden Vitest"
Agent-Aktionen:
npx vitest --reporter=json3 Mal mit Schleife ausführen- 4 Tests erkennen, die inkonsistent bestehen/fehlschlagen
- Für
auth.test.ts: grep zeigtsetTimeout(500)vor Assertion - Mit
waitForersetzen —auth.test.tsjetzt konsistent über 3 Durchläufe - Für
api.test.ts: Auth-Token auf Modulebene sickert zwischen Tests durch beforeEach(() => localStorage.clear())hinzufügen — stabilvitest.config.tsmit CI-Wiederholung = 2 konfigurieren- Überprüfen: alle 4 ehemals flaky Tests bestehen konsistent
- Bericht anzeigen
Benutzer: "Playwright E2E-Tests flaky auf CI"
Agent-Aktionen:
npx playwright test --reporter=json3 Mal ausführen,login.spec.tsals flaky identifizieren- Analyse: verwendet
page.waitForTimeout(3000)— Async-Timing-Problem - Ersetzen mit
await expect(page.locator('.dashboard')).toBeVisible({ timeout: 15000 }) retries: 2inplaywright.config.tsfür CI setzen- Auch
user-profile.spec.tserkennen — Umgebungsabhängigkeit (Zeitzone) - Zeitzone im Test-Setup mocken
- Überprüfen: 3/3 Durchläufe bestehen für beide Tests