Vorbereitung
Als Testobjekt dient die neue Komponente „Playwright Timeout Demo“ (Abschnitt 7) in meinem Testlab.
Sie enthält zwei Buttons und einen Statusbereich:
- Daten sofort laden: Der Status wechselt unmittelbar zu „Daten geladen“.
- Daten langsam laden: Der Status wechselt zunächst zu „Lade Daten …“ und erst nach sechs Sekunden zu „Daten geladen“.
Die Verzögerung wird mit JavaScript simuliert. Wir benötigen dafür keine API und können die Tests jederzeit reproduzieren.
Der gesamte Bereich hat die ID st-timeout-demo-2026-container.
In unseren Tests legen wir deshalb einen Locator für genau diesen Bereich an:
const demo = page.locator('#st-timeout-demo-2026-container');
Alle weiteren Locators suchen wir innerhalb dieses Containers. So greifen die Tests nicht versehentlich auf Buttons oder Statusmeldungen anderer Testlab-Beispiele zu.
Die wichtigsten Timeout-Arten
Playwright kennt mehrere Zeitlimits. Für diesen Beitrag sind vor allem drei interessant:
- Action-Timeout: Begrenzt die Wartezeit für eine Aktion, beispielsweise einen Klick.
- Assertion-Timeout: Bestimmt, wie lange eine Web-Assertion auf den erwarteten Zustand wartet.
- Test-Timeout: Begrenzt die gesamte Ausführungszeit eines Tests.
Zusätzlich gibt es den Navigation-Timeout, der beispielsweise beim Öffnen einer Webseite relevant ist.
Die Standardwerte unterscheiden sich:
- Test-Timeout: 30 Sekunden
- Assertion-Timeout: 5 Sekunden
- Action-Timeout: Standardmäßig kein eigenes Zeitlimit gesetzt
- Navigation-Timeout: Standardmäßig kein eigenes Zeitlimit gesetzt
Wichtig ist dabei: Die einzelnen Timeouts arbeiten nicht völlig unabhängig voneinander. Wenn beispielsweise der gesamte Test-Timeout erreicht wird, kann der Test abbrechen, obwohl eine einzelne Aktion oder Assertion noch warten dürfte.
Beispiel 1: Ein falscher Locator verursacht einen Action-Timeout
Wir beginnen mit einem absichtlichen Fehler. In der Demo gibt es einen Button mit dem Text „Daten sofort laden“.
Unser Test sucht allerdings nach einem Button mit dem Namen „Daten schnell laden“.
Was passiert?
Playwright sucht innerhalb unserer Timeout-Demo nach dem angegebenen Button. Dieser existiert aber nicht.
Da wir für die Klick-Aktion einen Timeout von zwei Sekunden gesetzt haben, bricht Playwright nach Ablauf dieses Zeitlimits mit einer Fehlermeldung ab, siehe nachfolgend:
Der Fehler liegt nicht daran, dass die Anwendung zu langsam reagiert. Der Locator ist schlicht falsch.
Die Lösung besteht darin, den richtigen Button anzusprechen:
Alternativ können wir direkt die eindeutige ID verwenden:
Beide Varianten finden den vorhandenen Button.
Merke: Ein längerer Timeout behebt keinen falschen Locator. Er sorgt lediglich dafür, dass Playwright länger nach einem Element sucht, das nicht existiert.
Beispiel 2: Eine Assertion läuft in einen Timeout
Jetzt verwenden wir den Button „Daten langsam laden“.
Nach dem Klick zeigt unsere Demo zunächst „Lade Daten …“. Erst sechs Sekunden später erscheint „Daten geladen“.
Wir prüfen mit einer Locator Assertion, ob der erwartete Text angezeigt wird:
Dieser Test schlägt fehl.
Der Grund ist einfach: Die Assertion wartet standardmäßig fünf Sekunden auf den erwarteten Text. Unsere Demo benötigt aber sechs Sekunden.
Während Playwright prüft, steht im Statusbereich noch „Lade Daten …“. Erst nach Ablauf des Assertion-Timeouts würde der gewünschte Text erscheinen.
Das ist ein anderer Fehler als in Beispiel 1.
Beim ersten Beispiel konnte Playwright den Button nicht finden. Hier funktioniert der Klick problemlos, aber der erwartete Zustand tritt nicht rechtzeitig ein.
Beispiel 3: Den Assertion-Timeout gezielt erhöhen
Wie beheben wir den Fehler aus Beispiel 2? Das Problem ist ausschließlich die Wartezeit unserer Assertion.
Deshalb passen wir genau diesen Timeout an:
Jetzt wartet Playwright bis zu elf Sekunden auf den erwarteten Text.
Unsere Demo benötigt sechs Sekunden. Sobald „Daten geladen“ erscheint, ist die Assertion erfolgreich und der Test läuft weiter – und besteht :).
Das bedeutet übrigens nicht, dass Playwright immer elf Sekunden wartet.
Die Assertion wird automatisch wiederholt und ist erfolgreich, sobald der erwartete Zustand erreicht wurde.
Genau deshalb sind Locator Assertions für dynamische Inhalte so praktisch.
Beispiel 4: Den gesamten Test-Timeout überschreiten
Bisher haben wir Timeouts für einzelne Aktionen und Assertions untersucht. Jetzt geht es um die Gesamtdauer eines Tests.
Standardmäßig darf ein Test in Playwright Test 30 Sekunden laufen. Für unser Beispiel setzen wir das Limit bewusst auf drei Sekunden.
Anschließend bauen wir eine feste Wartezeit von fünf Sekunden ein:
Dieser Test schlägt ebenfalls fehl.
Der Test darf nur drei Sekunden laufen, wartet aber absichtlich fünf Sekunden.
Playwright bricht ihn deshalb mit einer Meldung zum Test-Timeout ab.
Die feste Wartezeit verwenden wir hier ausschließlich, um den Timeout zu demonstrieren. In echten Tests ist waitForTimeout() normalerweise keine gute Lösung.
Wie kann ich den Test-Timeout ändern?
Wenn ein Test tatsächlich länger laufen muss, können wir sein Zeitlimit gezielt anpassen.
Für einen einzelnen Test funktioniert das mit test.setTimeout():
Jetzt hat der Test zehn Sekunden Zeit. Die fünf Sekunden Wartezeit passen also in das verfügbare Zeitbudget, sofern die übrigen Schritte nicht zu lange dauern.
Soll der Timeout für alle Tests im Projekt gelten, kannst du ihn in der playwright.config.js setzen, z.B. so:
import { defineConfig } from '@playwright/test';
export default defineConfig({
timeout: 60000,
});
Damit beträgt der Standard-Test-Timeout 60 Sekunden.
Der wichtige Unterschied: Mit dieser Einstellung veränderst du die maximale Laufzeit des gesamten Tests. Der Standard-Timeout für Web-Assertions bleibt davon unberührt.
Warum feste Wartezeiten keine gute Lösung sind
Eine häufige Reaktion auf Timeout-Probleme besteht darin, eine feste Pause einzubauen:
Das kann zwar dafür sorgen, dass der nächste Testschritt erst später ausgeführt wird. Es hat aber einen entscheidenden Nachteil: Playwright wartet immer die vollständigen zehn Sekunden.
Wenn die Anwendung bereits nach einer Sekunde fertig ist, verliert der Test neun Sekunden.
Benötigt die Anwendung dagegen länger als zehn Sekunden, kann der Test trotzdem fehlschlagen.
Besser ist es, auf den tatsächlichen Zustand zu warten, also wie oben:
Playwright überprüft den Status automatisch und beendet die Wartezeit, sobald „Daten geladen“ erscheint.
Bei dynamischen Inhalten sind solche Assertions deshalb meistens die bessere Wahl.
Wie analysiere ich einen Timeout-Fehler?
Wenn ein Test mit einem Timeout fehlschlägt, solltest du zuerst die Fehlermeldung und den Call Log untersuchen.
Die wichtigste Frage lautet: Worauf hat Playwright eigentlich gewartet?
- Element nicht gefunden: Überprüfe den Locator und den tatsächlichen Namen oder die ID des Elements.
- Aktion nicht möglich: Prüfe, ob das Element sichtbar, aktiviert und anklickbar ist.
- Assertion fehlgeschlagen: Kontrolliere, ob der erwartete Zustand tatsächlich erreicht wird und ob die Wartezeit ausreicht.
- Test-Timeout überschritten: Untersuche, welche Testschritte besonders lange dauern.
Unsere Testlab-Beispiele zeigen diese Unterschiede sehr deutlich.
In Beispiel 1 ist der Locator falsch. In Beispiel 2 ist die Assertion-Wartezeit kürzer als die simulierte Ladezeit. In Beispiel 4 überschreiten wir dagegen das Zeitlimit des gesamten Tests.
Es sind drei unterschiedliche Ursachen – und entsprechend unterschiedlich fallen die Lösungen aus.
Fazit
Timeouts gehören zur Testautomatisierung dazu. Entscheidend ist, dass du verstehst, welcher Timeout ausgelöst wurde und warum.
- Action-Timeout: Eine Aktion kann nicht innerhalb der vorgegebenen Zeit abgeschlossen werden.
- Assertion-Timeout: Ein erwarteter Zustand tritt nicht rechtzeitig ein.
- Test-Timeout: Der gesamte Test dauert länger als erlaubt.
- Navigation-Timeout: Ein Navigationsvorgang benötigt zu viel Zeit.
Ein falscher Locator wird nicht durch einen höheren Timeout richtig. Eine langsam ladende Anwendung benötigt möglicherweise eine passend konfigurierte Assertion. Und wenn ein Test insgesamt zu lange läuft, solltest du seine einzelnen Schritte untersuchen.
Die wichtigste Faustregel lautet deshalb: Nicht einfach alle Timeouts erhöhen, sondern zuerst die Ursache des Fehlers verstehen.
Weiterführende Links
