Eine Playwright-storageState-Datei kann vollständig aussehen und den Zustand, den eine App tatsächlich braucht, trotzdem nicht wiederherstellen. Cookies können da sein, localStorage kann da sein, und die JSON kann völlig gültig wirken, aber sessionStorage fehlt standardmäßig. Hält die App einen Teil ihrer Sitzung dort, bringt das Laden der Datei in einen neuen Kontext diesen Zustand nicht zurück.
Diese Unterscheidung zählt, weil storageState ein Snapshot ist, kein vollständiges Browserprofil. Playwright macht diesen Snapshot leicht zu exportieren, zu laden, nach Konto zu isolieren und zu prüfen. Hängt die Aufgabe aber von Browserzustand ab, der nicht sauber in die Datei passt, etwa sessionStorage, Erweiterungen, ein bereits angemeldetes Profil oder ein Mensch, der MFA abschließt, nimmt ego (lite) den anderen Weg: die echte Chromium-Umgebung belassen, statt sie aus JSON nachzubauen.
Dieser Leitfaden bleibt beim Snapshot selbst: was storageState enthält, wie Sie ihn erzeugen und laden, wie Sie Konten und Umgebungen trennen und wie Sie belegen, dass der wiederhergestellte Zustand tatsächlich greift. Login-Schleifen und automatische Neuauthentifizierung sind ein eigenes Problem. Hier ist die Frage einfacher: Was hat die Datei wirklich gespeichert, und was hat sie weggelassen?
Was ist Playwright storageState?
Playwright storageState ist der gespeicherte Cookie- und localStorage-Snapshot eines Browser-Kontexts. Sie exportieren ihn, nachdem der Kontext den gewünschten Zustand bereits hat, und säen dann einen späteren Kontext, damit er mit diesem Snapshot statt mit einem leeren Jar startet.
Die offizielle Playwright-Authentifizierungsdokumentation baut Test-Setup auf dieser Datei auf. Das ist ein Verbraucher des Snapshots, nicht die Definition des Snapshots. Diese Seite bleibt bei der Datei.
Login-Walls auf X und LinkedIn werden behandelt in KI-Scraping hinter Login-Walls.
Die Routenwahl beim JavaScript-Scraping wird behandelt in Web Scraping mit JavaScript.
Was enthält die storageState-Datei tatsächlich?
Die Datei ist JSON mit cookies und origins. cookies ist ein Array von Cookie-Objekten. origins ist ein Array von Origin-Einträgen, jeweils mit localStorage-Name/Wert-Paaren. Playwrights storageState API schreibt diese Form, wenn Sie einen Pfad übergeben, und liefert dasselbe Objekt, wenn Sie das nicht tun.
| Speicher | Standardmäßig in storageState? | Was das bedeutet |
|---|---|---|
| cookies | Ja | Jeder Eintrag kann name, value, domain, path, expires, httpOnly, secure und sameSite tragen. |
| localStorage | Ja, unter origins | Nach Origin geschlüsselt. Ein auf https://quotes.toscrape.com gespeicherter Schlüssel erscheint nicht auf einem anderen Origin. |
| sessionStorage | Nein | Die JSON hat standardmäßig keinen sessionStorage-Schlüssel. Eine wiederhergestellte Seite liest sessionStorage als null. |
Wir haben diese Dateiform am 2026-09-18 aus OpenCode getestet. Headed Chromium auf quotes.toscrape.com exportierte storageState mit den Top-Level-Schlüsseln cookies und origins. d05-demo lag in origins localStorage. Der JSON-String enthielt weder sessionStorage noch d05-session.
Der Playwright-Authentifizierungsleitfaden erwähnt für manche Setups auch IndexedDB und Passkeys im wiederverwendeten Zustand. Nehmen Sie nicht an, dass diese Schlüssel existieren, nur weil ein Blogpost sie auflistet. Öffnen Sie die erzeugte Datei und lesen Sie die Top-Level-Schlüssel.
Session-Cookies ohne Expires oder Max-Age sind eine eigene Falle in Profilverzeichnissen. Dieses Plattenverhalten gehört in dauerhafte Browser-Sitzungen. In einer storageState-JSON ist der Cookie-Ablauf ein explizites Feld an jedem Cookie. Null oder ein vergangener Zeitstempel ist, wie Sie ein Cookie sehen, das den nächsten Kalendertag nicht überlebt.
Wie erzeugen und laden Sie storageState?
Erzeugen Sie aus einem Kontext, der den gewünschten Zustand bereits hat. Laden Sie in einen neuen Kontext, bevor Sie die Seite öffnen, die ihn braucht. Exportieren Sie nicht von einem Origin und erwarten Sie das localStorage eines anderen Origins.
import { chromium } from "playwright";
const browser = await chromium.launch();
const setup = await browser.newContext();
const page = await setup.newPage();
await page.goto("https://quotes.toscrape.com/");
await page.evaluate(() => {
localStorage.setItem("d05-demo", "local-only");
sessionStorage.setItem("d05-session", "session-only");
});
await setup.storageState({ path: "playwright/.auth/user.json" });
await setup.close();
const reused = await browser.newContext({
storageState: "playwright/.auth/user.json",
});
const next = await reused.newPage();
await next.goto("https://quotes.toscrape.com/");
const restored = await next.evaluate(() => ({
local: localStorage.getItem("d05-demo"),
session: sessionStorage.getItem("d05-session"),
}));
console.log(restored);
await browser.close();Dieses Snippet ist der gesamte Mechanismus. Die offizielle Playwright-Authentifizierungsdokumentation packt ihn in ein Setup-Projekt, damit Tests die Login-UI überspringen. Der Wrapper ist optional. Die zwei Aufrufe sind es nicht.
Hält die App das Session-Token nur in sessionStorage, trägt diese Datei es nicht. Kopieren Sie sessionStorage mit page.evaluate, halten Sie einen Prozess am Leben oder nutzen Sie ein echtes Profil.
Wir haben die Wiederherstellung in derselben OpenCode-Sitzung getestet. Ein neuer Kontext, geladen aus dieser Datei, druckte local = local-only und session = null.
Wie beweisen Sie, dass der wiederhergestellte Zustand greift?
Belegen Sie die Wiederherstellung mit einem Schlüssel, den Sie geschrieben haben, oder mit einer authentifizierten URL, die nur die gespeicherten Cookies öffnen können. Behandeln Sie „das Login-Formular fehlt“ nicht als Beweis. Ein Redirect-Bug kann das Formular ebenfalls verbergen.
await page.goto("https://quotes.toscrape.com/");
const local = await page.evaluate(() => localStorage.getItem("d05-demo"));
if (local !== "local-only") {
throw new Error("storageState did not restore localStorage");
}Bei einem echten Konto rufen Sie eine URL auf, die nur bei gültigem Cookie 200 liefert, und prüfen Sie dann ein sichtbares Angemeldet-Label. Landen Sie auf /login, ist der Snapshot veraltet. Neuauthentifizierung gehört woanders hin. Hier brauchen Sie nur den Fail: Diese JSON hat die Sitzung nicht wiederhergestellt.
| Prüfung | Bestanden | Fehlgeschlagen |
|---|---|---|
| localStorage-Schlüssel | Liest den gespeicherten Wert | null nach dem Laden |
| sessionStorage-Schlüssel | null, sofern Sie ihn nicht selbst kopiert haben | Annehmen, er habe überlebt, weil localStorage überlebt hat |
| Cookie-Ablauf | expires liegt in der Zukunft bei den benötigten Cookies | expires ist 0 oder bereits vorbei |
Wie isolieren Sie Konten und Umgebungen?
Eine Datei pro Konto, pro Umgebung, pro Browser-Kontext, den Sie wiederverwenden wollen. Staging- und Produktions-Cookies in user.json zu mischen, ist der Weg, den falschen Mandanten zu testen.
Origins in der JSON sind origin-begrenzt. Ein auf https://quotes.toscrape.com gespeicherter localStorage-Schlüssel erscheint nicht auf http://quotes.toscrape.com. Schema, Host und Port zählen alle.
playwright/.auth/staging-admin.json
playwright/.auth/staging-viewer.json
playwright/.auth/prod-readonly.jsonParallele Worker brauchen jeweils eine eigene Datei oder einen eigenen Kontext. Eine JSON über zwei Kontexte zu teilen, die dann zurückschreiben, ist ein Race. Exportieren Sie nach dem Setup, laden Sie im Lauf nur lesend und schreiben Sie eine neue Datei nur aus einem eigenen Refresh-Job.
Woran erkennen Sie, dass der gespeicherte Zustand abgelaufen ist?
Die Datei kann gültig aussehen, während die Site die Sitzung bereits widerrufen hat. Prüfen Sie cookie expires in der JSON und dann eine Live-URL, die dieses Cookie verlangt.
Ein Cookie mit expires: -1 oder 0 ist ein Session-Cookie im Snapshot. Es kann im selben Lauf funktionieren und später verschwinden, je nachdem, wie der Browser es behandelt. Ein Zeitstempel in der Vergangenheit ist bereits tot. Ein zukünftiger Zeitstempel kann serverseitig trotzdem widerrufen werden.
Die Live-Prüfung ist die, die zählt. Öffnen Sie nach dem Laden eine authentifizierte Route. Bekommen Sie die Login-Seite, 401 oder eine anonyme Hülle, ist der Snapshot verbraucht. Aktualisieren Sie die Datei. Kodieren Sie auf dieser Seite keine Einmal-Login-Maschine.
Wie speichern Sie storageState sicher?
Behandeln Sie die JSON wie ein Passwort. Playwrights eigener Auth-Leitfaden sagt, sie könne Cookies und Header enthalten, mit denen man sich als Sie ausgeben kann. Halten Sie sie aus git, Logs, CI-Artefakten und Modellkontext.
# .gitignore
playwright/.auth/CI kann die Datei zu Jobbeginn aus einem Secrets Store injizieren und am Jobende löschen. Drucken Sie sie nicht. Hängen Sie sie nicht an ein Failed-Test-Zip. Fügen Sie sie nicht in einen Agenten-Prompt ein, um „die Sitzung zu debuggen“.
Wann sollten Sie stattdessen ein echtes Browserprofil wiederverwenden?
Verwenden Sie ein echtes Chromium-Profil wieder, wenn die App mehr braucht als Cookies und localStorage: Erweiterungen, sessionStorage, Geräte-Signale oder einen Menschen, der MFA durchsitzt. Eine JSON-Datei kann das nicht tragen.
Dort passt ego (lite) 0.5.0.32. Der Agent läuft in einem isolierten Space gegen das tägliche Browserprofil, das bereits auf der Maschine liegt. Der Tab kann beobachtet, ein Prompt übernommen und die Aufgabe gestoppt werden. Das Changelog zu dieser Version ist vom 2026-09-12 auf dem ego (lite)-Changelog. Es ist kein storageState-Exporter. Es ist der Weg, der die Datei überspringt, wenn die Datei die falsche Form hat.
Wir haben diese Isolation in ego (lite) aus OpenCode getestet. Die Spaces-Übersicht hielt die Zitataufgabe in einem eigenen laufenden Space, andere Arbeit in einem getrennten Space, statt die Sitzung aus JSON neu aufzubauen.
Wir haben dieselbe öffentliche URL in einem dieser Spaces getestet. Space 6 blieb unter Agentensteuerung auf quotes.toscrape.com, mit sichtbarem Take over und Stop. Die Browserumgebung blieb an Ort, statt aus einem JSON-Snapshot rekonstruiert zu werden.
Kommt localStorage zurück und ist sessionStorage null, hat die Datei ihre Arbeit getan. Behandeln Sie ein fehlendes Login-Formular nicht als Beweis. Am 2026-09-18 druckte der wiederhergestellte Kontext local = local-only und session = null aus Dummy-Schlüsseln, ohne Passwortformular.
Was sind die Herausforderungen und Grenzen?
Die Datei sieht vollständig aus und verfehlt trotzdem den Speicher, den Ihre App tatsächlich nutzt. Das ist der Standardfehler.
Origin-Mismatch ist der zweite. Speichern Sie auf localhost:3000, laden Sie gegen 127.0.0.1:3000, und localStorage ist leer, während Cookies je nach Domain noch anhaften können.
Der dritte ist, diese Seite mit Login-Choreografie zu überladen. 401 zu erkennen, nach /login zu springen und den Snapshot zu aktualisieren, sind echte Aufgaben. Sie sind nicht die Aufgabe dieser Datei.
FAQ
Enthält Playwright storageState Cookies?
Ja. cookies ist ein Top-Level-Array in der JSON. Jedes Cookie kann name, value, domain, path, expires, httpOnly, secure und sameSite enthalten.
Enthält storageState localStorage?
Ja, unter origins. Jeder Origin-Eintrag hält localStorage-Name/Wert-Paare nur für diesen Origin.
Enthält storageState sessionStorage?
Standardmäßig nicht. Eine Seite kann sessionStorage schreiben, storageState exportieren und trotzdem eine JSON ohne sessionStorage-Schlüssel erzeugen. Der wiederhergestellte Kontext liest diesen Speicher als leer. Am 2026-09-18 stellte der headed Lauf local = local-only und session = null wieder her.
Wie erzeuge ich eine storageState-Datei?
Rufen Sie await context.storageState({ path: 'playwright/.auth/user.json' }) auf, nachdem der Kontext die gewünschten Cookies und localStorage bereits hält.
Wie lade ich storageState in einem neuen Kontext?
Übergeben Sie storageState: 'playwright/.auth/user.json' an browser.newContext. Laden Sie, bevor Sie zur Seite navigieren, die den Snapshot braucht.
Wie beweise ich, dass storageState localStorage wirklich wiederhergestellt hat?
Lesen Sie einen gesetzten localStorage-Schlüssel oder öffnen Sie eine URL, die nur die gespeicherten Cookies erreichen. Ein fehlendes Login-Formular ist kein Beweis.
Sollte ich storageState in git committen?
Nein. Fügen Sie playwright/.auth/ zu .gitignore hinzu. Mit der Datei kann man sich als das erfasste Konto ausgeben.
Können zwei Tests eine storageState-Datei teilen?
Sie können denselben Snapshot nur lesend laden. Lassen Sie parallele Worker nicht dieselbe Datei schreiben. Nutzen Sie eine Datei pro Rolle, wenn die Konten sich unterscheiden.
Wann sollte ich stattdessen ein echtes Browserprofil nutzen?
Wenn die App sessionStorage, Erweiterungen oder einen Menschen für MFA braucht. ego (lite) führt diese Arbeit in einem Space gegen Ihr tägliches Chromium-Profil aus.
Ist storageState dasselbe wie ein User-Data-Directory?
Nein. storageState ist ein JSON-Snapshot. Ein User-Data-Directory ist das Profil auf der Platte.
Wenn die nächste Aufgabe den echten angemeldeten Browser braucht statt eines JSON-Snapshots, ist ego (lite) kostenlos zum Herunterladen.
