playwright-docs

Playwright Test (JS/TS) aus der offiziellen Dokumentation

Überblick

Dieser Skill enthält das, was die Playwright-Dokumentation sagt, was leicht falsch verstanden werden kann: Auto-Waiting-Regeln, Striktheit, Timeouts, die sich nicht so verhalten, wie man erwartet, blinde Flecken beim Mocking, Snapshot-Update-Modi, CI-Einstellungen und entfernte APIs. Generische Testtipps werden weggelassen. Jede Behauptung enthält die URL der Dokumentation, aus der sie stammt, sodass sie überprüft werden kann.

Abgedeckte Version

Playwright Test 1.64.1 für Node.js und TypeScript (@playwright/test). Python-, Java- und .NET-Inhalte sind ausgeschlossen. Wenn die installierte Version älter ist, überprüfen Sie die Versionstabelle in references/version-changes.md, bevor Sie eine neuere API anwenden.

Navigation

1. Lesen Sie den Schnellstart unten. Er behandelt die Regeln, die in den meisten Tests wichtig sind.
2. Öffnen Sie die Referenzdatei, deren Themenbereich der Aufgabe entspricht, aus der Tabelle am Ende.
3. Bevor Sie alten Code überprüfen oder ein Upgrade durchführen, lesen Sie „Alte Muster“ unten und references/version-changes.md.

Schnellstart

Locators

• Standard: page.getByRole(role, { name }). Dann getByLabel, getByText (nur nicht-interaktive Elemente), getByTestId als vertragsbasierten Fallback. CSS oder XPath nur, wenn nichts Benutzersichtbares funktioniert. https://playwright.dev/docs/locators#quick-guide
• Locators sind strikt: Eine Aktion auf einem Locator, der 2 Elemente matcht, wirft einen Fehler. Verwenden Sie filter({ hasText }), filter({ has }) oder inner.within(outer), anstatt zu first() / nth() zu greifen. https://playwright.dev/docs/locators#strictness
• Der Locator innerhalb von filter({ has }) wird vom äußeren Treffer aus aufgelöst, niemals vom Seitenstamm. https://playwright.dev/docs/locators#filter-by-childdescendant
• Textabgleich ist standardmäßig Teilstring und nicht case-sensitiv und immer Leerraum-normalisiert, selbst bei exact: true. https://playwright.dev/docs/locators#locate-by-text

Aktionen und Warten

• Aktionen warten automatisch auf Ausführbarkeit. Fügen Sie kein waitForTimeout, kein manuelles Warten auf das Laden vor einem Klick hinzu. https://playwright.dev/docs/actionability#introduction und https://playwright.dev/docs/navigations#when-is-the-page-loaded
• fill() ist die Standardmethode für Text. pressSequentially() nur für die schrittweise Eingabe. https://playwright.dev/docs/input#type-characters
• Events (Popup, Download, Filechooser, Response): Erstellen Sie das Wait-Promise VOR dem Klick, warten Sie es danach ab.

  const downloadPromise = page.waitForEvent('download');
  await page.getByText('Download file').click();
  const download = await downloadPromise;
  

  https://playwright.dev/docs/downloads#introduction
• Ein dialog-Listener, der weder akzeptiert noch ablehnt, lässt die Seite hängen. Ohne Listener werden Dialoge automatisch geschlossen. https://playwright.dev/docs/dialogs#alert-confirm-prompt-dialogs

Assertions

• Verwenden Sie immer await expect(locator).toX(). Niemals expect(await locator.isVisible()).toBe(true), das nur einmal prüft. https://playwright.dev/docs/best-practices#use-web-first-assertions
• Assertion-Timeout beträgt 5 s, getrennt vom 30 s Test-Timeout. https://playwright.dev/docs/test-timeouts
• Kein passender Matcher: Standardmäßig expect.poll verwenden. expect(...).toPass() hat standardmäßig KEIN Timeout, also eines angeben. https://playwright.dev/docs/test-assertions#expecttopass
• Verwenden Sie das expect von Playwright, nicht das von Jest. https://playwright.dev/docs/test-assertions#compatibility-with-expect-library

Struktur und Konfiguration

• Runner-Optionen auf der obersten Ebene von defineConfig, Browser- und Kontextoptionen innerhalb von use. https://playwright.dev/docs/test-configuration#introduction
• Fixtures anstelle von before/after-Hook-Paaren. Tests importieren test aus der Fixture-Datei. https://playwright.dev/docs/test-fixtures#with-fixtures
• beforeAll läuft einmal pro Worker, und ein Worker startet nach jedem Fehlschlag neu, daher kann beforeAll mehrmals ausgeführt werden. https://playwright.dev/docs/test-retries#failures
• Einmaliges Einloggen in einem Setup-Projekt mit dependencies, storageState nach dem Warten auf die endgültige URL speichern, playwright/.auth in gitignore. https://playwright.dev/docs/auth#basic-shared-account-in-all-tests
• Zuerst ein Gerät ausbreiten, dann viewport überschreiben, da ein Gerät auch sein eigenes viewport definiert. https://playwright.dev/docs/emulation#viewport
• Playwright führt keine Typprüfung durch. Führen Sie tsc --noEmit auf CI aus und linten Sie mit @typescript-eslint/no-floating-promises. https://playwright.dev/docs/test-typescript#introduction und https://playwright.dev/docs/best-practices#lint-your-tests

Netzwerk

• page.route VOR page.goto registrieren. Ein Glob muss die vollständige URL matchen, und ? matcht nur ein wörtliches Fragezeichen. https://playwright.dev/docs/mock#mock-api-requests und https://playwright.dev/docs/network#glob-url-patterns
• Routen verpassen Anfragen, die von einem Service Worker bedient werden. Setzen Sie serviceWorkers: 'block'. https://playwright.dev/docs/network#missing-network-events-and-service-workers
• page.request teilt die Browser-Cookies. request.newContext() ist isoliert und muss verworfen werden. https://playwright.dev/docs/api-testing#context-request-vs-global-request

CI

• forbidOnly: !!process.env.CI, retries: process.env.CI ? 2 : 0, workers: process.env.CI ? 1 : undefined, trace: 'on-first-retry', und immer ein globalTimeout, sonst erzeugt ein hängender Lauf keinen Bericht. https://playwright.dev/docs/test-configuration#basic-configuration und https://playwright.dev/docs/ci#global-timeout
• npx playwright install --with-deps nach npm ci und nach jedem Upgrade. Browser nicht cachen. https://playwright.dev/docs/ci#caching-browsers
• Sharding mit fullyParallel: true und Merging von Blob-Reports. https://playwright.dev/docs/test-sharding#balancing-shards
• Tests, die eine Ressource gemeinsam nutzen, mit einem Lock serialisieren, nicht mit serial mode: test('x', { lock: 'db' }, ...). https://playwright.dev/docs/test-parallel#test-locks

Snapshots

• Ohne -u wird ein fehlender Snapshot geschrieben UND der Test schlägt fehl. --update-snapshots=missing schreibt und besteht. -u bedeutet changed. https://playwright.dev/docs/aria-snapshots#updating-snapshots-with-playwrighttest-and-the---update-snapshots-flag
• Screenshot-Baselines sind pro Browser und Betriebssystem. Generieren Sie sie dort, wo sie verglichen werden. https://playwright.dev/docs/test-snapshots#introduction

Alte Muster

Alt	Aktuell	Quelle
locator.type(), page.type()	locator.fill() oder pressSequentially()	https://playwright.dev/docs/release-notes#version-138
page.$(), ElementHandle, page.$eval + generisches expect	Locator + Web-First-Assertion	https://playwright.dev/docs/handles#locator-vs-elementhandle
expect(await locator.isVisible()).toBe(true)	await expect(locator).toBeVisible()	https://playwright.dev/docs/best-practices#dont-use-manual-assertions
:visible-Pseudoklasse	locator.visible()	https://playwright.dev/docs/release-notes#version-163
text=Log in, id=, data-testid=-Selektoren	getByText, getByTestId	https://playwright.dev/docs/other-locators#legacy-text-locator
:right-of(), :near()-Layout-Selektoren	benutzersichtbare Locators	https://playwright.dev/docs/other-locators#css-matching-elements-based-on-layout
_react, _vue-Selektoren	Standard-Locators	https://playwright.dev/docs/release-notes#version-158
page.accessibility	@axe-core/playwright	https://playwright.dev/docs/release-notes#version-157
globalSetup für Login oder Seeding	Setup-Projekt mit dependencies	https://playwright.dev/docs/test-global-setup-teardown#introduction
test.describe.configure({ mode: 'serial' }) für eine gemeinsam genutzte Ressource	Test-Locks	https://playwright.dev/docs/test-parallel#test-locks
webServer.port	webServer.url	https://playwright.dev/docs/test-webserver#configuring-a-web-server
videosPath, videoSize	recordVideo oder use.video im Runner	https://playwright.dev/docs/release-notes#version-160
devtools: true-Startoption	args: ['--auto-open-devtools-for-tabs']	https://playwright.dev/docs/release-notes#version-158
-gv-Flag	--grep-invert oder -G	https://playwright.dev/docs/release-notes#version-154
npx playwright open zum Aufzeichnen	npx playwright codegen	https://playwright.dev/docs/release-notes#version-154
updateSnapshots: 'all' zum Aktualisieren geänderter	'changed' ('all' überschreibt alles)	https://playwright.dev/docs/release-notes#version-150
waitUntil: 'networkidle'	Auto-Waiting und Web-First-Assertions	https://playwright.dev/docs/puppeteer#automation-example
@playwright/experimental-ct-* mit JSX mount(<C />)	Stories + mount('Story/Id', props) von @playwright/test	https://playwright.dev/docs/test-components#migration-from-the-experimental-packages
Browser, die durch npm install heruntergeladen werden	npx playwright install --with-deps	https://playwright.dev/docs/release-notes#version-138

Referenzdateien

Datei	Lesen für
references/locators.md	Locator-Priorität, Textabgleich, Striktheit, filter, within, and / or, visible(), Shadow DOM, Frames, Legacy-Selektoren
references/actions-and-events.md	Actionability-Prüfungen pro Aktion, force, Eingabe, Drag & Drop, Dialoge, Downloads, Uploads, Popups, Navigation, Hydration, evaluate, Init-Skripte, Handles
references/assertions.md	Web-First- versus generische Matcher, Assertion-Timeouts, expect.poll, toPass, Soft-Assertions, benutzerdefinierte Matcher, test.step
references/snapshots-and-accessibility.md	Snapshot-Update-Modi, Aria-Snapshots, toHaveScreenshot-Toleranzen und -Benennung, Nicht-Bild-Snapshots, Axe-Scans
references/configuration.md	Konfigurationsstruktur, use-Scopes und -Standards, Projekte und Abhängigkeiten, Geräte und Emulation, TypeScript-Handhabung, webServer
references/timeouts-retries-annotations.md	Jedes Timeout und sein Standardwert, Wiederholungen und Worker-Neustarts, Serial-Modus, skip / fail / fixme, Tags, parametrisierte Tests und Projekte
references/fixtures-and-auth.md	Isolation, benutzerdefinierte Fixtures, Scopes, Optionen, Ausführungsreihenfolge, globale Hooks, Setup-Projekte, Page Objects, storageState-Authentifizierung, Rollen, Pro-Worker-Konten
references/network-and-mocking.md	route, Glob-Regeln, Header und Redirects, die eine Route nicht berühren kann, HAR-Aufzeichnung und -Wiedergabe, WebSocket-Mocks, Browser-API-Mocks, Service Worker
references/api-testing-and-clock.md	request-Fixture, gemeinsame versus isolierte Cookies, Verwerfen von Kontexten, page.clock-Methoden und -Reihenfolge
references/ci-parallel-sharding.md	CI-Baseline, GitHub Actions und andere Anbieter, Worker, fullyParallel, Test-Locks, Sharding, Zusammenführen von Blob-Reports
references/browsers-and-docker.md	Browser-Installation und -Cache, Chromium-Kanäle, Proxys und Mirrors, Docker-Image, Chrome-Erweiterungen, WebView2, Selenium Grid
references/debugging-and-reporting.md	CLI-Flags, --debug, Inspector, Trace- und Video-Modi, Trace-Viewer, UI-Modus, Reporter
references/component-testing-and-migration.md	Stories- und Gallery-Komponententests, Migration von experimentellen ct-Paketen, Testing Library, Protractor, Puppeteer
references/codegen-and-agent-tooling.md	Codegen, Library versus Test, Release-Kanäle, Test Agents, playwright-cli, Playwright MCP
references/version-changes.md	Breaking Changes im Verhalten, entfernte und veraltete APIs mit Ersatz, Änderungen der Plattformunterstützung

Quellen und Abrufdetails sind in SOURCES.md aufgeführt.