Playwright Cheat Sheet

Updated 2026-04-29

Next Topic: pnpm Package Manager Cheat Sheet

🧠Study flashcards on this topic143 cards · spaced repetition→

Playwright is a modern end-to-end testing framework developed by Microsoft for testing web applications across Chromium, Firefox, and WebKit browsers. Built on a multi-browser, multi-platform architecture, Playwright enables reliable automation through features like auto-waiting, web-first assertions, and browser context isolation. Unlike older tools that rely on polling and explicit waits, Playwright's actionability checks and parallel execution capabilities make it a top choice for creating fast, stable, and maintainable test suites that scale with modern CI/CD pipelines. As of v1.59, Playwright extends into AI-assisted workflows with Test Agents, MCP server integration, and agentic video receipts for automated test authoring and repair.

What This Cheat Sheet Covers

This topic spans 24 focused tables and 254 indexed concepts, 143 flashcards. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.

Table 1: Core Locator StrategiesTable 2: Actions and InteractionsTable 3: Web-First AssertionsTable 4: Navigation and WaitingTable 5: Browser Contexts and IsolationTable 6: Authentication PatternsTable 7: Fixtures and Dependency InjectionTable 8: Network Interception and MockingTable 9: API TestingTable 10: Test Configuration and OrganizationTable 11: Test Hooks and LifecycleTable 12: Test Annotations and ControlTable 13: Page Object ModelTable 14: Debugging and ToolingTable 15: Parallelization and ShardingTable 16: Visual TestingTable 17: File HandlingTable 18: Dialogs and PopupsTable 19: Advanced SelectorsTable 20: Accessibility TestingTable 21: CI/CD IntegrationTable 22: Mobile and EmulationTable 23: Parameterization and Environment VariablesTable 24: AI Agents and MCP

Quick IndexSubscribe to unlock

A jump-to index of every table row in this cheat sheet.

Mind MapSubscribe to unlock

An interactive map of every table and concept in this topic.

Table 1: Core Locator Strategies

Locators are how Playwright finds elements, and the order they appear here is a recommendation — reach for getByRole, getByText, and getByLabel first because they mirror how real users and assistive tech perceive the page, and drop down to CSS or XPath only when nothing user-facing fits. The filtering and chaining methods at the bottom let you narrow a broad match down to exactly one element without writing brittle selectors.

Method	Example	Description
getByRole	`page.getByRole('button', { name: 'Submit' })`	• Finds elements by ARIA role — most accessibility-friendly and recommended strategy • supports `name`, `checked`, `pressed`, `expanded` options.
getByText	`page.getByText('Welcome back')`	• Matches elements by visible text content • supports exact match, substring, or regex.
getByLabel	`page.getByLabel('Email address')`	• Finds form inputs by their associated label text • works with `<label>`, `aria-label`, and `aria-labelledby`.
getByPlaceholder	`page.getByPlaceholder('Search...')`	Locates inputs by their placeholder attribute — convenient for search fields without labels.
getByTestId	`page.getByTestId('user-profile')`	• Finds elements by data-testid attribute (configurable) • provides stable, framework-agnostic selectors.
getByAltText	`page.getByAltText('Company logo')`	Finds `<img>` or `<area>` elements by their alt attribute — essential for image and accessibility testing.
getByTitle	`page.getByTitle('Close dialog')`	Matches elements by their title attribute — typically used for tooltips or icon buttons.
filter by text	`page.getByRole('button').filter({ hasText: 'Save' })`	Narrows locator results by filtering on text content for precise targeting.
filter by child/descendant	`page.getByRole('article').filter({ has: page.locator('.new-badge') })`	Filters elements that contain a specific child or descendant — powerful for nested structures.
filter by not having text	`page.getByRole('listitem').filter({ hasNotText: 'Out of stock' })`	Filters elements that do not contain specified text — useful for inventory checks.
filter by visibility	`page.locator('button').filter({ visible: true })`	Returns only visible elements from a locator match — avoids strict mode violations with hidden duplicates.
locator.and	`page.getByRole('button').and(page.getByTitle('Subscribe'))`	Narrows a locator by requiring it to also match a second locator simultaneously.
locator.or	`newEmail.or(dialog).first()`	Matches either of two locators — useful when two different elements may appear.
chaining locators	`page.locator('.sidebar').getByRole('link')`	Combines locators to narrow scope — finds links within the sidebar only.
nth matching element	`page.getByRole('listitem').nth(2)`	Selects the nth element (zero-indexed) from multiple matches.
first / last	`page.getByRole('button').first()`	Selects the first or last element from multiple matches — more readable than `nth(0)`.
locator.normalize	`const better = await page.locator('#id').normalize()`	• Converts a locator to best-practice form (prefers test IDs and ARIA roles) • added in v1.59.
CSS selector	`page.locator('.submit-btn')`	• Uses CSS selector syntax — powerful but less readable • prefer stable classes or IDs.
XPath selector	`page.locator('xpath=//button[@id="submit"]')`	Uses XPath expressions — useful for complex DOM traversal but generally harder to maintain.

Table 2: Actions and Interactions

Once you have a locator, these are the things you actually do to it — click, fill, check, hover, upload, drag. The key thing that sets Playwright apart is that every action auto-waits for the element to be visible, enabled, and stable before acting, so you rarely need explicit waits. Most of the time click and fill carry you through a test; the rest of this list covers the edge cases like file inputs, human-paced typing, and right-clicks.

Action	Example	Description
click	`await page.getByRole('button').click()`	• Clicks an element • auto-waits for visibility, enabled, and stable state • supports modifiers like `Shift`, `ControlOrMeta`.

The rest of this section is part of the full cheat sheet

Table 3: Web-First Assertions

Web-first assertions are the reason Playwright tests are stable: each expect(...).toBe... automatically retries until the condition is met or the timeout expires, so you never have to sprinkle in manual sleeps to wait for the UI to catch up. Beyond the standard visibility, text, and value checks, the expect.soft, expect.poll, and expect.toPass helpers near the bottom give you control over how failures accumulate and how flaky async state is handled.

Assertion	Example	Description
toBeVisible	`await expect(page.locator('.banner')).toBeVisible()`	Asserts element is visible — auto-retries until visible or timeout.

The rest of this section is part of the full cheat sheet

Moving between pages and waiting for asynchronous events is where flakiness usually creeps in, so these methods are worth knowing well. Prefer waiting on a concrete signal — a URL pattern, a network response, or a locator reaching a state — over the fixed-duration waitForTimeout, which appears here mainly as the anti-pattern to avoid. Note that the event waiters like waitForEvent must be set up before the action that triggers them.

Method	Example	Description
goto	`await page.goto('https://example.com')`	• Navigates to URL • waits for load event by default • supports `waitUntil` options (load, domcontentloaded, networkidle).

The rest of this section is part of the full cheat sheet

Table 1: Core Locator Strategies

Method	Example	Description
getByRole	`page.getByRole('button', { name: 'Submit' })`	• Finds elements by ARIA role — most accessibility-friendly and recommended strategy • supports `name`, `checked`, `pressed`, `expanded` options.
getByText	`page.getByText('Welcome back')`	• Matches elements by visible text content • supports exact match, substring, or regex.
getByLabel	`page.getByLabel('Email address')`	• Finds form inputs by their associated label text • works with `<label>`, `aria-label`, and `aria-labelledby`.
getByPlaceholder	`page.getByPlaceholder('Search...')`	Locates inputs by their placeholder attribute — convenient for search fields without labels.
getByTestId	`page.getByTestId('user-profile')`	• Finds elements by data-testid attribute (configurable) • provides stable, framework-agnostic selectors.
getByAltText	`page.getByAltText('Company logo')`	Finds `<img>` or `<area>` elements by their alt attribute — essential for image and accessibility testing.
getByTitle	`page.getByTitle('Close dialog')`	Matches elements by their title attribute — typically used for tooltips or icon buttons.
filter by text	`page.getByRole('button').filter({ hasText: 'Save' })`	Narrows locator results by filtering on text content for precise targeting.
filter by child/descendant	`page.getByRole('article').filter({ has: page.locator('.new-badge') })`	Filters elements that contain a specific child or descendant — powerful for nested structures.
filter by not having text	`page.getByRole('listitem').filter({ hasNotText: 'Out of stock' })`	Filters elements that do not contain specified text — useful for inventory checks.
filter by visibility	`page.locator('button').filter({ visible: true })`	Returns only visible elements from a locator match — avoids strict mode violations with hidden duplicates.
locator.and	`page.getByRole('button').and(page.getByTitle('Subscribe'))`	Narrows a locator by requiring it to also match a second locator simultaneously.
locator.or	`newEmail.or(dialog).first()`	Matches either of two locators — useful when two different elements may appear.
chaining locators	`page.locator('.sidebar').getByRole('link')`	Combines locators to narrow scope — finds links within the sidebar only.
nth matching element	`page.getByRole('listitem').nth(2)`	Selects the nth element (zero-indexed) from multiple matches.
first / last	`page.getByRole('button').first()`	Selects the first or last element from multiple matches — more readable than `nth(0)`.
locator.normalize	`const better = await page.locator('#id').normalize()`	• Converts a locator to best-practice form (prefers test IDs and ARIA roles) • added in v1.59.
CSS selector	`page.locator('.submit-btn')`	• Uses CSS selector syntax — powerful but less readable • prefer stable classes or IDs.
XPath selector	`page.locator('xpath=//button[@id="submit"]')`	Uses XPath expressions — useful for complex DOM traversal but generally harder to maintain.

Table 2: Actions and Interactions

Action	Example	Description
click	`await page.getByRole('button').click()`	• Clicks an element • auto-waits for visibility, enabled, and stable state • supports modifiers like `Shift`, `ControlOrMeta`.

Table 3: Web-First Assertions

Assertion	Example	Description
toBeVisible	`await expect(page.locator('.banner')).toBeVisible()`	Asserts element is visible — auto-retries until visible or timeout.

Table 4: Navigation and Waiting

Method	Example	Description
goto	`await page.goto('https://example.com')`	• Navigates to URL • waits for load event by default • supports `waitUntil` options (load, domcontentloaded, networkidle).