Playwright (Python) Cheat Sheet

1Install & launch1.61

pip install playwright playwright install # downloads Chromium/Firefox/WebKit★
The second command is required — it fetches the browser binaries. playwright install chromium for just one.
from playwright.sync_api import sync_playwright with sync_playwright() as p: browser = p.chromium.launch(headless=True) page = browser.new_page()★
The standard setup. headless=False to watch; slow_mo=500 to slow it down while debugging.
p.firefox.launch() · p.webkit.launch() · channel="chrome"
Same code, three engines. channel="chrome"/"msedge" uses your installed branded browser.
from playwright.async_api import async_playwright # async twin
The async API mirrors sync with await — use it inside asyncio apps.

2Navigatego places

page.goto("https://example.com")★
Navigates and waits for the load event by default. Returns the response.
page.go_back() · page.reload() · page.title() · page.url
History & page info.
page.goto(url, wait_until="networkidle", timeout=30000)
wait_until: load/domcontentloaded/networkidle/commit. Default timeout is 30s (configurable).

3Locators (get_by_*)user-facing

page.get_by_role("button", name="Sign in")★
Preferred: find by ARIA role + accessible name — resilient to markup changes and mirrors how users/AT perceive the page.
page.get_by_text("Welcome") · get_by_label("Email") · get_by_placeholder(...)★
By visible text, form label, or placeholder. get_by_alt_text, get_by_title too.
page.get_by_test_id("submit") # data-testid★
The stable choice for app code you control — add data-testid attributes.
page.locator("css=.card") · page.locator("xpath=//h1")
Fall back to raw CSS/XPath when the semantic locators don't fit.

4Filter & chainnarrow down

page.get_by_role("listitem").filter(has_text="Product 2")★
Filter a set by contained text or a child locator (has=).
row.get_by_role("button") # chain to scope within an element★
Locators chain — find the button inside a specific row.
loc.first · loc.last · loc.nth(2) · loc.count()★
Index into multiple matches; count() / all() to iterate.
strict mode: one match per actionnote
Acting on a locator that matches multiple elements errors — refine it, or use .first/.nth() deliberately.

5Actionsauto-waiting

page.get_by_role("button", name="Submit").click()★
Auto-waits for the element to be visible, enabled & stable before clicking — no sleep needed. Also dblclick, hover.
page.get_by_label("Email").fill("a@b.com")★
fill clears + sets a value (fast). press_sequentially for real keystrokes; press("Enter") for keys.
.check() / .uncheck() · .select_option("US") · .set_input_files("cv.pdf")★
Checkboxes, dropdowns, file uploads.
loc.text_content() · loc.input_value() · loc.get_attribute("href")
Read values back out for scraping/verification.

6Assertions (expect)web-first, retrying

from playwright.sync_api import expect expect(page.get_by_text("Success")).to_be_visible()★
Web-first assertions retry until the condition holds or times out — no flaky assert element.is_visible().
expect(loc).to_have_text("Done") · to_contain_text(...) · to_have_value(...)★
Content assertions. to_have_count(3), to_be_enabled(), to_be_checked().
expect(page).to_have_url(...) · to_have_title(...)
Page-level assertions. Add .not_ to negate: expect(loc).not_to_be_visible().

7Waiting & navigationthe rare explicit wait

page.wait_for_load_state("networkidle")
Usually unnecessary (actions auto-wait), but handy after a JS-heavy transition.
with page.expect_navigation(): loc.click()★
Wrap an action that triggers navigation. expect_response(url) / expect_download() / expect_popup() similarly.
page.wait_for_timeout(1000) # hard sleep — avoidavoid
Fixed sleeps are the flakiness anti-pattern. Wait for a condition (an assertion, a locator, a response) instead.

8Context, auth, networkpower features

ctx = browser.new_context(viewport={"width":1280,"height":800}, user_agent="...", locale="en-US")★
A context = an isolated browser session (own cookies/storage). Cheap — one per test/user.
ctx.storage_state(path="auth.json") browser.new_context(storage_state="auth.json")★
Log in once, reuse everywhere: save cookies/localStorage, then start future contexts already authenticated.
page.route("**/*.png", lambda r: r.abort()) # block images★
Intercept/modify/mock network. route.fulfill(...) to stub an API response; block assets to speed up scraping.
page.evaluate("() => document.title") · page.on("dialog", ...)
Run JS in the page; handle dialogs/downloads/new tabs (ctx.pages).

9Capture & toolingscreenshots, codegen, trace

page.screenshot(path="s.png", full_page=True) · loc.screenshot(...)★
Full-page or element screenshots. page.pdf(path=...) (Chromium) for PDFs.
playwright codegen https://example.com★
Record your clicks into ready-to-edit Playwright code — the fastest way to start a script.
ctx.tracing.start(screenshots=True, snapshots=True) ctx.tracing.stop(path="trace.zip") # view: playwright show-trace★
Record a trace and inspect every step/DOM snapshot in the Trace Viewer — the best debugging tool.
pip install pytest-playwright # gives a `page` fixture
For testing: def test_x(page): page.goto(...); run headed with --headed, pick browsers with --browser.

!Common gotchasread before shipping

run playwright install
The pip package alone can't launch browsers — playwright install downloads them. In CI/Docker use the official image or --with-deps.
don't sleep — trust auto-wait
Actions & expect already wait for actionability. Fixed wait_for_timeout is the #1 source of flaky/slow scripts.
strict locators error on multiple matches
A locator that resolves to 2+ elements throws on action. Narrow it (role+name, filter) or pick .first/.nth() on purpose.
locators are lazy, not elements
A locator is a query re-run on each use (so it can't go stale). query_selector returns a snapshot handle — prefer locators.
context per user/test
Reusing one context leaks cookies/state between flows. New context = clean session; reuse storage_state only for auth.

Playwright cheat sheet