Wer viele UI-Tests für eine Anwendung hat, kennt das Problem: Fast jedes Testszenario beginnt mit denselben Schritten – Benutzername eingeben, Passwort eingeben, Login-Button klicken. Bei zwei oder drei Tests ist das kein Problem, bei 50 oder 100 Tests kostet es spürbar Zeit und erzeugt zusätzliche Last auf dem Authentifizierungssystem.
Playwright bringt dafür eine eingebaute Lösung mit: Storage State. Man loggt sich einmalig ein, speichert den Session-Zustand (Cookies, Local Storage, Tokens) in einer Datei, und alle folgenden Tests starten direkt authentifiziert – ganz ohne wiederholten Login-Flow.
In diesem Beitrag zeige ich das komplette Setup anhand meines eigenen WordPress-Backends auf Softwaretests.org . 🙂
Worum geht es in dieser Woche?
Wir gehen folgende Schritte durch:
Kurzer Überblick: Was ist Storage State und wofür ist es gedacht?
Eine eigene auth.setup.js-Datei für den Login-Vorgang anlegen.
Nach dem Login den Session-Zustand in einer Datei speichern.
Das Setup in playwright.config.js als Abhängigkeit für die eigentlichen Tests einrichten.
Mit einem eigenen Test explizit prüfen, ob die Storage State tatsächlich greift.
Was ist Storage State in Playwright?
Storage State beschreibt den kompletten Anmeldezustand eines Browserkontexts – Cookies, Local Storage und je nach Anwendung auch Tokens. Playwright kann diesen Zustand nach einem erfolgreichen Login in eine JSON-Datei exportieren und beim Start eines neuen Tests wieder einladen. Der Test startet dann so, als hätte der Login bereits stattgefunden – ganz ohne Formular, Klick oder Wartezeit.
Das Prinzip in Kürze:
Ein Setup-Projekt loggt sich einmal ein und speichert den Zustand in eine Datei (z. B. playwright/.auth/user.json).
Die eigentlichen Testprojekte deklarieren eine Abhängigkeit zu diesem Setup und laden die gespeicherte Datei als storageState.
Playwright erkennt automatisch, welche Informationen relevant sind – egal ob es sich um ein einfaches JWT-Cookie handelt oder um komplexere Auth-Flows wie OAuth oder SSO-Provider.
Quelle: https://playwright.dev/docs/auth
Schritt 1: auth.setup.js anlegen
Als Erstes wird unter tests/ eine eigene Datei für den Setup-Schritt angelegt: tests/auth.setup.js. Da mein Projekt mit ES Modules arbeitet (import/export statt require), sieht die fertige Datei so aus:
Der Dateipfad authFile legt fest, wo die spätere Session gespeichert wird – bei mir playwright/.auth/user.json. Der Ordner muss noch nicht existieren, Playwright legt ihn beim ersten Lauf automatisch an.
Schritt 2: Zugangsdaten sicher über .env einbinden
Zugangsdaten gehören nicht in den Code, sondern in eine separate .env-Datei, die nicht versioniert wird.
Praxis-Tipp: Falls dein Passwort Sonderzeichen enthält (!, &, ) etc.), setze den Wert in Anführungszeichen – das hat mir in der Praxis Parsing-Probleme erspart. : )
Damit Node.js diese Datei überhaupt lädt, braucht es das Paket dotenv:
npm install dotenv --save-dev
Und in playwright.config.js, ganz am Anfang:
Schritt 3: Setup in der Konfiguration einrichten
Damit Playwright auth.setup.js automatisch vor den eigentlichen Tests ausführt, wird in playwright.config.js ein eigenes Setup-Projekt definiert, von dem das Test-Projekt abhängt:
ein neuer Eintrag { name: "setup", testMatch: /auth\.setup\.js/ } im projects-Array, sowie bei chromium ergänzt um storageState: "playwright/.auth/user.json" und dependencies: ["setup"].
Das heißt: Damit ist die Reihenfolge klar geregelt: Bevor chromium seine Tests ausführt, läuft zuerst setup und erzeugt user.json. Alle Tests in diesem Projekt starten danach automatisch mit dieser Storage State. 🙂
Schritt 4: Testlauf – Setup läuft automatisch mit
Zunächst habe ich auth.setup.js isoliert laufen lassen (npx playwright test tests/auth.setup.js), um den Login-Flow und das Speichern der user.json separat zu verifizieren, bevor die komplette Suite läuft. Im Terminal sieht man, dass der Test durchläuft und die Session erfolgreich gespeichert wird.
Für bestehende Tests bedeutet das in der Praxis wie gesagt: Sobald ein Test-Projekt von setup abhängt und storageState gesetzt hat, können bisherige Login-Schritte (Formular ausfüllen, Button klicken) am Anfang jedes einzelnen Tests ersatzlos entfernt werden – der Test startet dann dank Storage State bereits eingeloggt.
Schritt 5: Explizit prüfen, ob die Storage State wirklich greift
Bevor man sich darauf verlässt, lohnt sich natürlich ein dedizierter Test storage-check.spec.js, der genau das nachweist:
Führt man npx playwright test tests/storage-check.spec.js aus, meldet Playwright “Running2 tests” statt nur einem. Grund, wie oben beschrieben: Das Projekt hängt von setup ab (dependencies: ['setup']), Playwright führt auth.setup.js also automatisch mit aus, bevor der eigentliche Test startet – der erste Test ist das Setup, der zweite der oben gezeigte.
Schlägt eine der drei Prüfungen fehl, wäre WordPress auf die Login-Seite umgeleitet worden – ein Zeichen, dass die Storage State nicht mehr gültig ist. Sind sie grün, ist der Beweis erbracht: Der Test kam bereits authentifiziert über die gespeicherte Session, ohne selbst einzuloggen.
(Kleine Randnotiz: h1.wp-heading-inline wäre naheliegend gewesen, aber mein WordPress rendert die Überschrift als schlichtes <h1> ohne diese Klasse – daher der einfachere Selektor.)
Sowohl playwright/.auth/user.json (Session-Cookies) als auch auth/.env (Zugangsdaten im Klartext) enthalten hochsensible Informationen. Beide gehören wie du sicherlicher weißt nicht in ein Git-Repository. Entsprechende Einträge in .gitignore sind Pflicht:
playwright/.auth/
auth/
Tipps für bessere Ergebnisse
1. Wartekriterium bewusst wählen: Ein sichtbares Element (wie #wpadminbar) ist meist zuverlässiger als eine feste Wartezeit (waitForTimeout).
2. Zugangsdaten nur über Umgebungsvariablen: Genau wie bei API-Tokens gehören Login-Zugangsdaten nicht in den Testcode.
3. .gitignore nicht vergessen: Sowohl die Storage-State-Datei als auch die .env-Datei enthalten sensible Daten und dürfen nicht versioniert werden – dasselbe gilt für Screenshots davon.
4. Storage State explizit verifizieren: Ein eigener Test wie in Schritt 5 gibt dir Sicherheit, dass das Setup tatsächlich funktioniert, statt es nur anzunehmen.
5. Selektoren am echten Markup prüfen: Nicht blind Beispiel-Selektoren übernehmen – ein kurzer Blick in den Browser-Inspektor erspart unnötige Fehlversuche.
6. Pro Nutzerrolle eine eigene Storage State: Wer z. B. Admin- und Redakteur-Rechte separat testen möchte, legt sich entsprechend mehrere Setup-Projekte und Auth-Dateien an.
Fazit: Weniger Wiederholung, mehr stabile Tests
Storage State ist eine der einfachsten Optimierungen, die sich in einer wachsenden Playwright-Testsuite umsetzen lässt: Der Login-Vorgang läuft nur noch einmal, statt bei jedem einzelnen Test erneut durchlaufen zu werden. Das spart nicht nur Laufzeit, sondern reduziert auch die Last auf dem Authentifizierungssystem.
Auf dem Weg dorthin lauern ein paar leicht zu übersehende Stolperfallen, die ich hier nicht in jedem Detail gezeigt habe – falsche Pfade, gemischte Modulformate, ungenaue Selektoren – aber jede davon lässt sich mit einer klaren Fehlermeldung und etwas Geduld (oder KI-Unterstützung beim Einordnen der Fehlermeldung) zügig lösen.
Am Ende steht ein Setup, das zuverlässig funktioniert und sich beliebig auf weitere Tests übertragen lässt. 🙂
