Du kennst das vielleicht: Ein Test läuft mehrfach hintereinander durch, und plötzlich scheitert er – ohne dass sich am Code etwas geändert hätte. Der Grund ist oft ein Popup, das nicht immer erscheint: ein Cookie-Banner, ein Newsletter-Hinweis, ein Feedback-Dialog. Taucht es auf, blockiert es die Seite und der nächste Klick geht ins Leere. Taucht es nicht auf, läuft alles glatt.
Playwright bringt dafür eine elegante Lösung mit: den Locator Handler. In dieser Woche möchte ich dir zeigen, wie dieser funktioniert. Dafür habe ich ein eigenes Beispiel (Abschnitt 6) in meinem Testlab vorbereitet.
Vorbereitung
Als Testobjekt dient die folgende kleine Komponente. Man trägt einen Namen ein und klickt auf „Absenden”. Das Besondere: Nach dem Absenden erscheint zufällig – in etwa der Hälfte der Fälle – ein Popup mit einer freundlichen Erinnerung, das die Seite blockiert und den Hinweis anzeigt “Der Name sollte mit einem Großbuchstaben beginnen”, bis man es mit „Okay” schließt:
Probier es gerne selbst im Testlab (Abschnitt 6) ein paar Mal aus: Mal erscheint das Popup, mal nicht – und genau das lässt sich nicht vorhersagen. Für einen automatisierten Test ist das ein Problem, denn er muss mit beiden Situationen zurechtkommen.
Hier erscheint das Popup nicht. Hier erscheint das Popup.
Das Problem: Ein Test, der zufällig scheitert
Ein erster Test für den Ablauf könnte so aussehen. Er trägt zwei Namen nacheinander ein und prüft am Ende die Statusmeldung:
Führt man den Test einmal aus, kann er durchlaufen – oder scheitern. Um dieses Verhalten sichtbar zu machen, hilft ein praktisches Kommandozeilen-Flag: --repeat-each führt jeden Test mehrfach hintereinander aus. Das ist ideal, um unzuverlässige (flaky) Tests zu entlarven:
Das zweite Flag, --workers=1, sorgt dafür, dass die fünf Durchläufe nacheinander laufen. Ohne diese Einstellung würden sie parallel in mehreren Workern ausgeführt.
Das Ergebnis schwankt von Lauf zu Lauf: Mal bestehen drei Durchläufe, mal nur einer. Im HTML-Report sind die fehlgeschlagenen Läufe einzeln aufgeführt.
npx playwright show-report
Der Reporter zeigt folgendes:
Der Grund liegt auf der Hand: Erscheint das Popup nach dem ersten Klick, liegt es wie ein Schleier über der Seite. Der zweite Klick auf „Absenden” trifft dann nicht mehr den Button, sondern das Popup – Playwright wartet vergeblich, bis das Zeitlimit erreicht ist, und der Test schlägt fehl. Im Fehlerprotokoll ist entsprechend zu erkennen, dass ein anderes Element die Klicks abfängt.
Die Lösung: addLocatorHandler
Mit page.addLocatorHandler() bringt man Playwright bei, wie es auf ein solches Popup reagieren soll. Die Methode erwartet zwei Argumente:
Den Auslöser (Locator): Woran erkennt Playwright das Popup? Hier der Text „Freundliche Erinnerung”.
Eine Handler-Funktion: Was soll passieren, sobald das Popup sichtbar ist? Hier ein Klick auf den „Okay”-Button.
Wie funktioniert das? Bevor Playwright eine Aktion ausführt, prüft es, ob der Auslöser gerade sichtbar ist. Ist das der Fall, ruft es zuerst den Handler auf – das Popup wird weggeklickt – und führt danach die eigentliche Aktion aus. Anschließend stellt Playwright sicher, dass das Popup tatsächlich verschwunden ist, bevor es weitergeht. Erscheint das Popup nicht, passiert einfach nichts, und der Test läuft normal weiter.
Wichtig dabei: Der Handler muss vor dem Schritt registriert werden, der das Popup auslösen kann. Im Beispiel steht er deshalb ganz am Anfang des Tests, noch vor page.goto().
Test erneut ausführen
Jetzt zu der Gegenprobe mit denselben Flags wie vorhin:
Und siehe da: Alle fünf Durchläufe bestehen, egal ob das Popup in den einzelnen Läufen erschienen ist oder nicht. Wer mag, kann die Wiederholungen auch erhöhen (z. B. --repeat-each=20), um sicherzugehen, dass der Test wirklich stabil ist. 🙂
Wann sollte man den Locator Handler einsetzen?
Der Locator Handler ist für Situationen gedacht, in denen etwas unvorhersehbar auftaucht und Aktionen blockiert – typische Kandidaten sind:
Cookie- und Consent-Banner, die nicht bei jedem Aufruf erscheinen
Newsletter- oder Werbe-Popups mit zufälligem Timing
Feedback- und Hinweisdialoge, die unregelmäßig eingeblendet werden
Erscheint ein Popup dagegen vorhersehbar, empfiehlt die Playwright-Dokumentation, es ganz normal im Testablauf abzuhandeln – also explizit darauf zu warten und es zu schließen, statt einen Handler zu verwenden. Außerdem verändert der Handler den Zustand der Seite mitten im Test, das sollte man im Hinterkopf behalten.
Die Methode steht seit Playwright 1.42 zur Verfügung. Falls sie bei dir nicht gefunden wird, lohnt sich ein Blick auf die installierte Version.
Fazit
Zufällig auftauchende Popups sind eine häufige Ursache für flaky Tests. Mit --repeat-each lässt sich das Problem zuverlässig sichtbar machen, und mit addLocatorHandler() lösen wir es an der Wurzel: einmal definiert, kümmert sich Playwright automatisch um das Popup – genau dann, wenn es erscheint, und ohne dass der Testablauf selbst davon etwas mitbekommen muss.
