Voraussetzungen
Für dieses Tutorial brauchst du:
- Playwright ab Version 1.59 – die Trace-Analyse per Kommandozeile gibt es erst seit diesem Release
- Einen Coding-Agenten mit Terminalzugriff – ich verwende Claude Code, die Vorgehensweise ist aber nicht daran gebunden
Die installierte Playwright-Version lässt sich schnell prüfen:
npx playwright --version
Ist sie älter als 1.59, hilft ein Update samt aktualisierten Browsern:
npm install -D @playwright/test@latest
npx playwright install
Was ist neu?
- CLI-Trace-Analyse (
npx playwright trace): Ein aufgezeichneter Trace lässt sich komplett im Terminal untersuchen – Aktionen, Netzwerkaufrufe, Konsolenmeldungen, Fehler und Seiten-Snapshots, alles als Text. Das, was man sonst im Trace Viewer anklickt, kann ein Agent jetzt per Befehl abrufen.
Der Gedanke dahinter: Agenten arbeiten (besser) mit Text. Ein Trace Viewer mit grafischer Oberfläche ist für sie unbrauchbar, eine Textausgabe dagegen genau das Richtige.
Vorbereitung
Als Testobjekt dient die folgende kleine Tierliste. Zu jedem Tier gibt es ein Eingabefeld mit dem Namen und einen Button, um den Namen zu bearbeiten und zu speichern:
Ein Klick auf „Bearbeiten” macht das Feld editierbar, mit „Speichern” wird der neue Name übernommen und eine Statusmeldung angezeigt. Genau diesen Ablauf wollen wir testen. Siehe auch Testlab Abschnitt 8.
Der fehlschlagende Test
Der Test soll “Hund” in „Wellensittich” ändern. Dafür suche ich zuerst die Zeile mit dem Hund und arbeite dann innerhalb dieser Zeile weiter:
Der Test scheitert, und das ist Absicht. Warum, finden wir gleich heraus.
Wichtig für die Analyse: Damit überhaupt ein Trace entsteht, muss die Aufzeichnung eingeschaltet sein. In der Standardkonfiguration wird ein Trace lokal nur beim Wiederholen eines fehlgeschlagenen Tests aufgezeichnet (trace: 'on-first-retry'), und Wiederholungen sind lokal ausgeschaltet. Deshalb schalten wir die Aufzeichnung beim Start per Flag ein:
npx playwright test tests/debug-agent.spec.js --trace on
Die Terminalausgabe nennt neben der Fehlermeldung auch zwei Dateien: den Pfad zur trace.zip und zur error-context.md.
In die zweite Datei lohnt einen kurzen Blick: Playwright legt dort bei jedem Fehlschlag Fehlerdetails, Testquelltext und einen Snapshot der Seite als Text ab. Coding-Agenten lesen diese Datei übrigens oft von selbst.
Den Trace manuell im Terminal analysieren
Bevor wir den Agenten arbeiten lassen, gehen wir den Trace einmal selbst durch. Dann wird klar, welche Informationen der Agent später zur Verfügung hat.
1. Trace öffnen
Den Pfad zur trace.zip übernimmst du aus der Terminalausgabe:
npx playwright trace open test-results/<ordner>/trace.zip
Die Ausgabe beginnt mit einer Zusammenfassung des Tests: Dauer, Anzahl der Aktionen, Netzwerkaufrufe, Fehler und Konsolenmeldungen. Das gibt einen ersten Überblick, bevor man in die Details geht.
2. Alle Aktionen auflisten
npx playwright trace actions
Die Ausgabe listet jeden Schritt des Tests mit laufender Nummer, Zeitpunkt, Aktion und Dauer auf. Der fehlgeschlagene Schritt ist markiert, in unserem Fall der Klick auf den Bearbeiten-Button.
3. Details zum fehlgeschlagenen Schritt
Jede Aktion hat eine Nummer. Mit ihr lassen sich Parameter, Fehlermeldung und Call-Log abrufen. Ich nehme hier die Nummer des fehlgeschlagenen Klicks, also 9, bei dir steht sie in der Aktionsliste:
npx playwright trace action 9
Im Call-Log steht, worauf Playwright gewartet hat: auf eine Zeile, die den Text „Hund” enthält. Gefunden hat es nichts.
4. Den Seitenzustand ansehen
Jetzt wird es spannend: Der Snapshot zeigt, wie die Seite im Moment des Fehlers aussah. Mit --phase wählt man den Zustand vor (before) oder nach (after) der Aktion. Welche Zustände für einen Schritt vorhanden sind, steht am Ende der Ausgabe von trace action unter Snapshots:
npx playwright trace snapshot <nummer> --phase before
Hinweis zur Version: Ich habe dieses Tutorial mit Playwright 1.64.1 nachgestellt. In älteren Beschreibungen zu 1.59 taucht für dasselbe Flag teilweise der Name --name auf. Falls ein Befehl bei dir nicht funktioniert, zeigt die Ausgabe von trace action die passende Syntax an.
Der Snapshot ist die gesamte Seite als Accessibility-Baum in Textform – entsprechend lang, denn er enthält alles, was auf der Seite steht, also auch die anderen Beispiele im Testlab. Weil die Ausgabe reiner Text ist, lässt sie sich einfach filtern, zum Beispiel mit grep:
Das Ergebnis:
Der relevante Ausschnitt sieht so aus (ohne die internen Referenzen):
- row:
- cell:
- textbox "Tiername Hund": Hund
- cell:
- button "Hund bearbeiten": Bearbeiten
- row:
- cell:
- textbox "Tiername Katze": Katze
- cell:
- button "Katze bearbeiten": Bearbeiten
Beachte, wo „Hund” steht: In der Zeile selbst gibt es keinen Text, nur zwei Zellen. Der Name taucht ausschließlich hinter dem Doppelpunkt des Textfelds auf – das ist sein Wert.
Und genau hier liegt die Ursache: Der Name „Hund” steht nicht als Text in der Zeile, sondern als Wert eines Eingabefelds. Der Filter hasText durchsucht aber den Textinhalt des Elements, und der Wert eines Eingabefelds gehört nicht dazu. Deshalb findet der Test keine passende Zeile und läuft in den Timeout.
5. Weitere Befehle
Für andere Fehlerarten gibt es weitere Abfragen:
npx playwright trace requests – Netzwerkaufrufenpx playwright trace console – Konsolenmeldungennpx playwright trace errors – gesammelte Fehler mit Stacktrace
Zum Schluss wird der Trace wieder geschlossen:
npx playwright trace close
Alle Ausgaben sind reiner Text. Man kann sie also auch mit grep oder anderen Shell-Werkzeugen weiterverarbeiten, und genau das kann auch ein Agent.
Den Agenten die Analyse übernehmen lassen
Jetzt machen wir dasselbe noch einmal, aber ohne unser Zutun.
Den Skill installieren
Damit der Agent die Trace-Befehle kennt und weiß, wann er sie einsetzen soll, bringt Playwright einen passenden Agent-Skill mit. Installiert wird er im Projektordner mit:
npx playwright trace install-skill
Die Ausgabe nennt den Installationsort:
Der Skill landet also direkt im Projektordner unter .claude/skills/, dem Ort, an dem Claude Code nach projektbezogenen Skills sucht. Weitere Einrichtung ist nicht nötig.
Alternative: Wer mehr Kontrolle möchte, kann auch einen eigenen Skill schreiben. Darin steht Schritt für Schritt, was der Agent tun soll: den Test mit Trace ausführen, bei Erfolg aufhören, andernfalls den Trace mit den oben gezeigten Befehlen untersuchen, die Ursache benennen und einen Fix vorschlagen oder anwenden.
Den Agenten starten
Im Projektordner starte ich den Coding-Agenten und gebe ihm eine einfache Aufgabe:
Der Test tests/debug-agent.spec.js schlägt fehl. Führe ihn mit Trace aus,
analysiere den Trace mit npx playwright trace und finde die Ursache.
Schlage danach einen Fix vor.
Sieht nun also so aus:
Der Agent geht ähnlich vor wie wir eben von Hand. In meinem Lauf sah das so aus:
- Skill laden: Als Erstes lädt der Agent den installierten Skill
playwright-trace. Damit ist bestätigt, dass die Skill-Installation von eben greift.
- Test mit Trace ausführen: Er startet den Test mit eingeschalteter Trace-Aufzeichnung (
--trace on).
- Trace öffnen und Aktionen auflisten: mit
trace open und trace actions, genau wie wir.
- Fehlgeschlagenen Schritt untersuchen: mit
trace action 9 und trace snapshot 9 --phase before. Die lange Snapshot-Ausgabe filtert er dabei mit grep auf die relevante Stelle.
- Echtes HTML prüfen: Zusätzlich fragt er per eval-Abfrage den tatsächlichen HTML-Code der Tabelle aus dem Snapshot ab.
- Fix ausprobieren: Er legt eine temporäre Kopie des Tests mit dem vorgeschlagenen Fix an, führt sie aus und löscht sie wieder.
Der gesamte Lauf dauerte bei mir knapp eine Minute.
Hinweis zu den Berechtigungen: Je nach Einstellung fragt dein Agent vor jedem Befehl nach. Prüfe, welche Berechtigungen du ihm erteilt hast, bevor du ihn im Projekt arbeiten lässt.
Der Abschlussbericht
Am Ende fasst der Agent seine Erkenntnisse zusammen.
Sinngemäß:
- Ursache: Der Filter
hasText: 'Hund' findet keine Tabellenzeile. Deshalb läuft der erste Klick auf „Bearbeiten” nach 5 Sekunden in den Timeout.
- Beleg im Trace: Fehlgeschlagen ist nur Aktion 9, der Klick. Das Log enthält nur „waiting for …”, ein passendes Element gab es also nie. Im DOM steht „Hund” ausschließlich im
value eines Eingabefelds, und der Textinhalt der Zeile besteht nur aus „Bearbeiten Speichern” und Leerraum. hasText durchsucht genau diesen Text und ignoriert die Werte von Eingabefeldern.
- Ausgeschlossen: Die Seite selbst war in Ordnung, es gab weder fehlgeschlagene Netzwerkaufrufe noch Fehler in der Browser-Konsole.
Das deckt sich mit unserer manuellen Analyse: gleiche Ursache, gleiche Stelle.
Der Fix
Der Agent schlägt vor, die Zeile nicht über Text, sondern über das enthaltene Textfeld zu finden. Dessen Name „Tiername Hund” stammt aus dem aria-label:
const row = page.getByRole('row').filter({
has: page.getByRole('textbox', { name: 'Tiername Hund' }),
});
Diese Variante bleibt auch nach fill('Wellensittich') eindeutig, weil sich das aria-label nicht ändert, der Wert des Feldes aber schon. Der übrige Test bleibt unverändert, und laut Agent läuft er damit durch.
Der Agent hat den Fix nicht einfach in die Datei geschrieben, sondern vorher gefragt, ob er ihn übernehmen soll.
Nach meiner Bestätigung werden die korrigierten Stellen hervorgehoben:
Als Ergebnis entsteht ein neuer, vom Agent korrigierter Test:
Danach läuft der Test erfolgreich durch:
npx playwright test tests/debug-agent.spec.js
Fazit
Playwright 1.59 macht die Fehlersuche für Coding-Agenten greifbar: Der Trace wird zur Textquelle. Im Beispiel liegt die Ursache bei einem Locator, der Text im DOM sucht, obwohl der Name in einem Eingabefeld steht.
Mit trace actions, trace action und trace snapshot ist sie in wenigen Schritten gefunden, manuell wie auch durch einen Agenten.
Ein Agent nimmt einem dabei Detektivarbeit ab, aber nicht die Verantwortung: Den vorgeschlagenen Fix sollte man natürlich immer weiterhin prüfen, bevor man ihn übernimmt.
Weiterführende Links
