Playwright-Testhandwerk — Cheat Sheet

Der Spickzettel zum Handwerk aus dem Seminar Playwright mit KI-Agenten: was ein Test braucht, damit er etwas aussagt und in der Pipeline hält. Den agentischen Teil — Planner, Generator, Healer, MCP und CLI — behandelt ein eigenes Blatt: Playwright mit KI-Agenten.

Maßgeblich ist die Originaldokumentation auf playwright.dev; dieses Blatt trifft eine Auswahl und bringt sie die Methode nicht bei — dafür ist das Seminar da.

Testmodell: die vier Ebenen

Isolation entsteht durch den Kontext, nicht durch Aufräumcode am Testende. Weil ein Kontext fast nichts kostet, bekommt ihn jeder Test neu — Geschwindigkeit und Isolation stehen hier nicht gegeneinander.

Modul: Ein belastbares Playwright-Fundament

Locators — welcher wann

Die Reihenfolge ist eine Rangfolge: Je näher ein Locator an der Wahrnehmung eines Menschen liegt, desto länger hält er. Rollenbasierte Locators finden das Element nur, wenn es auch für Assistenztechnik erreichbar ist.

Modul: Ein belastbares Playwright-Fundament

Web-first Assertions

// Warten von selbst bis zum Zeitlimit — kein waitForTimeout nötig
await expect(alarm).toHaveText('Nicht lieferbar');
await expect(kasse).toBeEnabled();
await expect(page.getByTestId('zeile')).toHaveCount(2);
await expect(alarm).not.toBeVisible();   // Fehlerfall absichern

Sichtbarkeit ist fast keine Aussage, der Wert ist die Aussage. Die negative Assertion fehlt in erzeugtem Code am häufigsten.

Modul: Ein belastbares Playwright-Fundament

Artefakte und ihre Aussage

Der Trace legt Aktion, DOM-Zustand, Netzwerk und Konsole auf eine gemeinsame Zeitachse und beantwortet damit das Was und das Warum zugleich. Videos ergänzen ihn, ersetzen ihn nicht.

Modul: Ein belastbares Playwright-Fundament

Kommandozeile

npx playwright test --ui              # interaktiv, mit Zeitachse
npx playwright test warenkorb --debug # schrittweise, Browser hält an
npx playwright codegen <url>          # aufzeichnen, Locators vorschlagen
npx playwright show-trace trace.zip   # Nachschau
npx playwright test --repeat-each=3 --workers=4   # Instabilität provozieren
npx playwright test --shard=1/4       # verteilen
npx playwright merge-reports --reporter html blobs/

Module: Playwright-Fundament · Parallelität, Testdaten und große Suites

Fixtures und Page Objects

export const test = base.extend<Fixtures>({
  warenkorb: async ({ page }, use) => {
    const seite = new WarenkorbSeite(page);
    await seite.oeffnen();
    await use(seite);          // danach: aufräumen — greift auch bei Fehlschlag
  },
});

Assertions bleiben im Test. Wandern sie ins Page Object, liest man hinterher eine Klickfolge, die irgendwo im Hintergrund etwas behauptet. Geteilter Zustand in einer Worker-Fixture ist erlaubt — nur darf kein Test ihn verändern.

Modul: Wartbarkeit mit Fixtures und Domänenabstraktionen

Parallelität und Kollisionen

Ein Test, der allein grün und in der Suite rot ist, ist fast immer ein Kollisionsfall — und die Ursache sitzt im Test, der gleichzeitig lief. Die Diagnose in dreißig Sekunden: --workers=1. Verschwindet der Fehler, ist es eine Kollision.

Gegenmittel ist nicht weniger Parallelität, sondern eine eindeutige Kennung je Test — etwa aus testInfo.workerIndex und testInfo.testId — plus Aufräumen in der Fixture statt am Testende.

Modul: Parallelität, Testdaten und große Suites

API-gestütztes Testen

Die Regel: über die Oberfläche nur prüfen, was auch ein Mensch dort prüfen würde. Der Anmeldezustand ist zwischen APIRequestContext und BrowserContext austauschbar — einmal per API anmelden, im Browser weiterarbeiten.

Modul: Testabdeckung strategisch ausbauen

CI-Läufe

Für stabile Läufe empfiehlt die Dokumentation zunächst einen Worker; Breite entsteht über Sharding, nicht über Worker. Browser-Caching lohnt selten — das Wiederherstellen dauert etwa so lange wie das Herunterladen.

Modul: Playwright-Tests in der CI-Pipeline

Typische Fallen

• Selektoren aus generierten Klassennamen übernehmen, die der nächste Build ändert.
• Feste Wartezeiten statt Web-first Assertions — sie verdecken Ladeprobleme und brechen auf langsamer CI.
• Nur Sichtbarkeit prüfen, statt was in einem Element steht.
• Negative Assertions weglassen und damit Fehlerfälle nie absichern.
• Traces nur lokal aktivieren und in der Pipeline genau dann keine haben.
• Fehlschläge durch Wiederholung wegdrücken, statt sie zu lesen.
• Ein einziges Testkonto für die ganze Suite — die häufigste Kollisionsursache.
• Aufräumen ans Testende legen, wo es bei einem Fehlschlag nie erreicht wird.
• Shards ohne Zusammenführung fahren und vier Teilberichte hinterlassen.
• Assertions in Hilfsfunktionen verstecken und dem Test seine Aussage nehmen.