Playwright Trace Viewer: Fehlgeschlagene Tests debuggen

1. Warum der Trace Viewer Flaky Tests besser aufklärt als console.log

Ein fehlgeschlagener E2E-Test in der CI ist eine der frustrierendsten Situationen im Entwickleralltag: Der Test läuft lokal grün, scheitert aber auf dem CI-Runner, und ein einzelner console.log oder ein Screenshot am Ende des Laufs verrät kaum, was in den Sekunden davor tatsächlich passiert ist. Der Playwright Trace Viewer löst genau dieses Problem, indem er nicht nur den Endzustand, sondern jeden einzelnen Schritt eines Testlaufs aufzeichnet: jede Aktion, jede Netzwerkanfrage, jede DOM-Änderung und jede Konsolenausgabe, zeitlich synchronisiert und durchsuchbar.

Der entscheidende Unterschied zu klassischem Debugging mit Logging-Statements ist, dass eine Trace nachträglich analysiert werden kann, ohne den Test erneut ausführen zu müssen. Gerade bei flaky Tests, die nur unter bestimmten Timing-Bedingungen fehlschlagen, ist das entscheidend, denn ein erneuter lokaler Lauf reproduziert das Problem oft gar nicht. Die Trace-Datei aus dem fehlgeschlagenen CI-Lauf enthält den exakten Zustand, der zum Fehler geführt hat, und lässt sich beliebig oft im Trace Viewer durchgehen, vor- und zurückspulen und mit dem DOM zu jedem Zeitpunkt inspizieren.

2. Trace-Aufzeichnung aktivieren: trace: 'on-first-retry' konfigurieren

Traces werden über die use-Option in playwright.config.ts aktiviert. Die Einstellung trace: 'on-first-retry' ist für die meisten Projekte der sinnvollste Kompromiss: Ein Test, der beim ersten Versuch erfolgreich ist, erzeugt keine Trace und spart damit Speicherplatz und Laufzeit. Erst wenn ein Test fehlschlägt und automatisch wiederholt wird, zeichnet Playwright beim ersten Retry eine vollständige Trace auf. Damit liegt für praktisch jeden echten Fehlschlag eine Aufzeichnung vor, ohne dass grüne Läufe unnötig Artefakte produzieren.

Alternative Werte sind 'on' für lückenlose Aufzeichnung aller Läufe, was beim Debuggen einer einzelnen Testdatei sinnvoll ist, aber in der CI schnell zu großen Artefaktmengen führt, sowie 'retain-on-failure', das Traces für jeden Lauf erzeugt, aber nur bei einem endgültigen Fehlschlag behält. Die Option retries muss dabei so gesetzt sein, dass überhaupt ein zweiter Versuch stattfindet, sonst greift on-first-retry nie. In CI-Umgebungen sind zwei bis drei Retries üblich, lokal reicht meist null.

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  // Retry failed tests in CI so a trace actually gets recorded
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 4 : undefined,
  use: {
    baseURL: 'https://staging.mironsoft-shop.test',
    // Record a trace only on the first retry of a failing test
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
  reporter: [['html', { open: 'never' }], ['github']],
});

3. Anatomie der Trace-Viewer-Oberfläche: Timeline, Snapshots, Netzwerk, Konsole

Die Trace-Viewer-Oberfläche gliedert sich in mehrere Bereiche, die zusammen ein vollständiges Bild des Testlaufs ergeben. Oben liegt die Timeline: eine horizontale Leiste mit einem Kästchen pro Aktion, farblich markiert nach Dauer und Status. Ein Klick auf ein Kästchen springt zu genau diesem Zeitpunkt und lädt den passenden DOM-Snapshot im mittleren Bereich, der die Seite exakt so darstellt, wie sie zu diesem Moment im Browser aussah, inklusive Hover-Zustände und angewendeter Styles.

Rechts daneben zeigt der Action-Baum jeden Schritt als Liste mit Selektor, Dauer und Vor-/Nach-Snapshot. Darunter befinden sich Tabs für Netzwerk, in dem jede HTTP-Anfrage mit Status-Code, Headern, Payload und Timing aufgelistet ist, Konsole mit allen Browser-Logs und JavaScript-Fehlern, sowie ein Source-Tab, der die Testdatei mit der exakt ausgeführten Zeile anzeigt. Für Assertions gibt es zusätzlich einen Call-Tab, der den erwarteten und tatsächlichen Wert eines fehlgeschlagenen expect() gegenüberstellt, was die Fehlersuche bei Wert-Mismatches erheblich beschleunigt.

4. Traces lokal öffnen mit npx playwright show-trace

Nach einem lokalen Testlauf mit aktivierter Trace-Aufzeichnung öffnet npx playwright show-trace die Aufzeichnung direkt im Browser, ohne dass eine separate Installation nötig ist. Der Befehl startet einen lokalen Webserver, lädt die Trace-Datei und öffnet automatisch ein neues Browserfenster mit der vollständigen Oberfläche. Das funktioniert sowohl mit einer einzelnen .zip-Datei als auch mit mehreren Traces gleichzeitig, die dann als getrennte Tabs im Viewer erscheinen und sich per Drag-and-drop vergleichen lassen.

Besonders praktisch für den täglichen Gebrauch: Der HTML-Report, den Playwright nach jedem Lauf erzeugt, verlinkt fehlgeschlagene Tests direkt mit einem Trace-Button. Ein Klick darauf öffnet den Trace Viewer direkt im Report, ohne den Dateipfad manuell suchen zu müssen. Für schnelles Debugging während der Entwicklung reicht daher oft npx playwright test --trace on gefolgt von npx playwright show-report, um jeden fehlgeschlagenen Test mit einem Klick vollständig zu inspizieren.

# Run tests locally with tracing forced on for every test
npx playwright test --trace on

# Open the trace for a single failed test directly from the test-results folder
npx playwright show-trace test-results/checkout-flow-should-complete/trace.zip

# Compare two trace files side by side (e.g. before/after a fix)
npx playwright show-trace trace-before.zip trace-after.zip

# Open the interactive HTML report, then click "trace" on any failed test
npx playwright show-report

5. CI-Trace-Artefakte herunterladen und untersuchen

In der CI reicht es nicht, Traces nur lokal zu erzeugen: Sie müssen als Artefakte gesichert werden, bevor der Runner-Workspace nach dem Job gelöscht wird. In GitHub Actions übernimmt das actions/upload-artifact, konfiguriert mit if: failure(), damit Artefakte nur bei tatsächlichen Fehlschlägen hochgeladen werden und nicht bei jedem grünen Lauf unnötig Speicherplatz belegen. Der Ordner test-results/ enthält dabei automatisch alle Trace-, Screenshot- und Video-Dateien der fehlgeschlagenen Tests.

Nach dem Download des Artefakt-Archivs aus der GitHub-Actions-Oberfläche oder per gh run download lässt sich die enthaltene trace.zip lokal exakt wie ein selbst erzeugter Trace mit npx playwright show-trace öffnen. Wichtig ist, das Archiv vollständig zu entpacken, da einzelne Netzwerk-Ressourcen und Screenshots als separate Dateien neben der eigentlichen Trace-Datei liegen können. Wer regelmäßig CI-Traces analysiert, richtet sich am besten ein festes lokales Verzeichnis für heruntergeladene Artefakte ein, um Testläufe über die Zeit vergleichen zu können.

# .github/workflows/e2e.yml
name: E2E Tests
on: [pull_request]

jobs:
  playwright:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test

      # Only upload traces when the job actually failed
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-traces
          path: test-results/
          retention-days: 7

6. --debug und der Playwright Inspector

Während der Trace Viewer für die nachträgliche Analyse gedacht ist, richtet sich der Modus --debug an das Debuggen während der Testentwicklung. Der Befehl npx playwright test --debug startet den Browser sichtbar und pausiert vor jeder Aktion, während der Playwright Inspector als separates Fenster geöffnet wird. Dort lässt sich Schritt für Schritt durch den Test gehen, jede Aktion einzeln ausführen und der Selektor der aktuellen Zeile live im Browser hervorheben.

Der Inspector bringt zusätzlich einen Selektor-Picker mit, der beim Klick auf ein Element im Browser automatisch einen robusten Playwright-Selektor generiert, was besonders beim Schreiben neuer Tests Zeit spart. Für gezieltes Debugging einer einzelnen Testdatei eignet sich --debug in Kombination mit einem Testnamen-Filter, damit nicht der gesamte Testlauf pausiert, sondern nur der relevante Test. Ein gesetzter await page.pause()-Aufruf im Testcode hält die Ausführung zusätzlich an einer beliebigen Stelle an, auch ohne den Flag global zu setzen.

# Debug a single test file interactively, browser visible, paused before each step
npx playwright test checkout.spec.ts --debug

# Debug only one test by name (avoids pausing the whole file)
npx playwright test --debug -g "should apply discount code at checkout"

# Inside a test file, pause execution at an arbitrary point without --debug:
# await page.pause();

7. --ui-Modus für interaktives lokales Debugging

Der UI-Modus, gestartet mit npx playwright test --ui, kombiniert eine Testübersicht, den Trace Viewer und einen Watch-Modus in einem einzigen Fenster. Auf der linken Seite erscheint eine durchsuchbare Liste aller Tests, die per Klick einzeln oder gefiltert nach Datei, Projekt oder Tag ausgeführt werden können. Nach jedem Lauf, egal ob erfolgreich oder fehlgeschlagen, steht die vollständige Trace-Ansicht mit Timeline, Snapshots und Netzwerk-Tab direkt im selben Fenster zur Verfügung, ohne dass eine separate Trace-Datei geöffnet werden muss.

Der eingebaute Watch-Modus führt Tests automatisch erneut aus, sobald der zugehörige Quellcode oder die Testdatei gespeichert wird, was die Iterationsgeschwindigkeit beim Beheben eines Fehlers deutlich erhöht. Zusätzlich zeigt der UI-Modus einen Time-Travel-Schieberegler direkt über dem Browser-Vorschaufenster, mit dem sich durch jeden Schritt eines Tests scrubben lässt, während der DOM-Zustand live mitwandert. Für die tägliche Testentwicklung ersetzt der UI-Modus in der Praxis meist sowohl --debug als auch das manuelle Öffnen von Trace-Dateien.

# Launch the interactive UI mode for the whole test suite
npx playwright test --ui

# Launch UI mode scoped to a single project (e.g. only Chromium)
npx playwright test --ui --project=chromium

# UI mode respects the same filters as a normal run
npx playwright test --ui checkout.spec.ts

8. Flaky vs. deterministische Fehler richtig einordnen

Nicht jeder fehlgeschlagene Test ist gleich zu behandeln, und der Trace Viewer hilft dabei, die beiden Kategorien sauber zu unterscheiden. Ein deterministischer Fehler tritt bei jedem Lauf unter denselben Bedingungen auf, etwa weil ein Selektor durch eine UI-Änderung nicht mehr existiert oder eine Assertion einen tatsächlich falschen Wert erwartet. Solche Fehler zeigen sich in der Trace als klarer roter Schritt mit eindeutiger Fehlermeldung im Call-Tab, und die Behebung besteht meist im Anpassen von Selektor oder Erwartungswert.

Ein flaky Test hingegen schlägt nur unter bestimmten Timing- oder Reihenfolgebedingungen fehl, häufig weil eine asynchrone Operation wie ein API-Aufruf oder eine Animation noch nicht abgeschlossen war, als die nächste Aktion ausgeführt wurde. In der Trace erkennt man das typischerweise an einer Netzwerkanfrage, die im Netzwerk-Tab erst nach dem fehlgeschlagenen Schritt abschließt, oder an einem DOM-Snapshot, der ein Element im Übergangszustand zeigt. Die Lösung liegt fast immer in einer expliziten Playwright-Auto-Waiting-Bedingung wie await expect(locator).toBeVisible() statt einer festen waitForTimeout-Pause, die das Problem nur verschleiert statt es zu beheben.

9. Trace Viewer im direkten Vergleich zu klassischen Debugging-Methoden

Die folgende Übersicht stellt klassische, oft zeitraubende Debugging-Ansätze den entsprechenden Trace-Viewer-Workflows gegenüber. Der Unterschied liegt selten in der grundsätzlichen Machbarkeit, sondern in der Zeit bis zur tatsächlichen Ursache eines Fehlschlags.

Der gemeinsame Nenner aller Zeilen in der Tabelle: Der Trace Viewer verschiebt Debugging von einem iterativen Rate-und-Ausführe-Zyklus zu einer einmaligen, vollständigen Aufzeichnung, die beliebig oft und ohne erneuten Testlauf durchsucht werden kann. Gerade bei CI-spezifischen Fehlern, die lokal gar nicht auftreten, ist das der entscheidende Zeitvorteil gegenüber klassischem Debugging.

10. Zusammenfassung

Der Playwright Trace Viewer löst das Kernproblem des E2E-Debuggings: Fehler, die nur einmal auftreten, insbesondere in der CI, lassen sich vollständig rekonstruieren, ohne den Test erneut ausführen zu müssen. trace: 'on-first-retry' in der Konfiguration sorgt dafür, dass für jeden echten Fehlschlag eine Aufzeichnung existiert, ohne grüne Läufe unnötig zu belasten. Die Kombination aus Timeline, DOM-Snapshots, Netzwerk-Tab und Konsole deckt praktisch jede Fehlerursache ab, von falschen Selektoren über Timing-Probleme bis zu fehlgeschlagenen API-Aufrufen.

Für die tägliche Testentwicklung ergänzen sich --debug mit dem Playwright Inspector und der --ui-Modus mit integriertem Watch-Modus ideal: Während der Entwicklung eines neuen Tests hilft die interaktive Schritt-für-Schritt-Ausführung, nach einem CI-Fehlschlag liefert die heruntergeladene Trace-Datei die exakte Ursache. Wer diese Werkzeuge konsequent nutzt, ersetzt das Rätselraten bei flaky Tests durch einen reproduzierbaren, dokumentierten Debugging-Workflow.

11. FAQ: Playwright Trace Viewer und Testdebugging