CommunityRecherche & Datenanalysegithub.com

Flaky-Test-Erkenner

Erkenne, analysiere und beseitige flaky Tests in jedem Test-Runner. Eine KI-Agenten-Fähigkeit, die nicht-deterministische Testfehler identifiziert, Grundursachen kategorisiert und gezielte Korrekturen anwendet.

Was ist Flaky-Test-Erkenner?

Der Flaky-Test-Erkenner ist eine KI-Agenten-Fähigkeit, die entwickelt wurde, um flaky Tests in Softwareprojekten zu identifizieren, zu diagnostizieren und zu beheben. Er unterstützt eine breite Palette von Test-Runnern wie Vitest, Jest, Playwright, Cypress, Mocha und AVA. Der Agent führt die Testsuite mehrmals hintereinander aus, sammelt Ergebnisse und identifiziert Tests, die inkonsistent bestehen oder fehlschlagen. Anschließend kategorisiert er die Fehler in fünf Hauptkategorien: Async-Timing, gemeinsam genutzter veränderlicher Zustand, Testisolationsprobleme, Umgebungsabhängigkeiten und Wettlaufsituationen. Für jede Kategorie bietet der Agent spezifische Diagnosebefehle und bewährte Korrekturstrategien, einschließlich Code-Beispielen in diff-Format. Nach der Anwendung von Korrekturen führt er einen erneuten Testdurchlauf zur Überprüfung durch und generiert optional einen zusammenfassenden Bericht (FLAKY_REPORT.md). Die Fähigkeit ist plattformunabhängig und kann in CI/CD-Pipelines integriert werden, um die Stabilität der Testsuite nachhaltig zu verbessern.

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

Installed? Explore more Recherche & Datenanalyse skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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

  1. Erkenne Runner und Konfiguration
  2. Sammle flaky Kandidaten durch wiederholte Ausführung
  3. Analysiere Fehlermuster, um die Grundursache zu identifizieren
  4. Korrigiere jede Flakiness-Kategorie mit bewährten Strategien
  5. Überprüfe Korrekturen durch erneutes Durchlaufen des Erkennungszyklus

Phase 1: Runner und Konfiguration erkennen

Projekteinrichtung lesen:

cat package.json

Den Test-Runner identifizieren:

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

Vorhandene Wiederholungs-/Flaky-Konfiguration prüfen:

  • Vitest: retry in vitest.config.ts
  • Jest: testRetry in jest.config.ts oder jest.retryTimes() im Setup
  • Playwright: retries in playwright.config.ts
  • Cypress: retries in cypress.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 waitFor oder expect.poll in 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 --shard oder --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 / afterEach Bereinigung
  • 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, setTimeout mit 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:

  1. npx vitest --reporter=json 3 Mal mit Schleife ausführen
  2. 4 Tests erkennen, die inkonsistent bestehen/fehlschlagen
  3. Für auth.test.ts: grep zeigt setTimeout(500) vor Assertion
  4. Mit waitFor ersetzen — auth.test.ts jetzt konsistent über 3 Durchläufe
  5. Für api.test.ts: Auth-Token auf Modulebene sickert zwischen Tests durch
  6. beforeEach(() => localStorage.clear()) hinzufügen — stabil
  7. vitest.config.ts mit CI-Wiederholung = 2 konfigurieren
  8. Überprüfen: alle 4 ehemals flaky Tests bestehen konsistent
  9. Bericht anzeigen

Benutzer: "Playwright E2E-Tests flaky auf CI"

Agent-Aktionen:

  1. npx playwright test --reporter=json 3 Mal ausführen, login.spec.ts als flaky identifizieren
  2. Analyse: verwendet page.waitForTimeout(3000) — Async-Timing-Problem
  3. Ersetzen mit await expect(page.locator('.dashboard')).toBeVisible({ timeout: 15000 })
  4. retries: 2 in playwright.config.ts für CI setzen
  5. Auch user-profile.spec.ts erkennen — Umgebungsabhängigkeit (Zeitzone)
  6. Zeitzone im Test-Setup mocken
  7. Überprüfen: 3/3 Durchläufe bestehen für beide Tests

Verwandte Skills