Playwright Python (pytest-playwright) Complete Practice Guide & Cheat Sheet
Everything you need to write fast, flake-free Playwright tests in Python using `pytest-playwright`: built-in `page` fixtures, snake_case locators, auto-retrying `expect()`, and popup context managers.
Test this solution live in real cloud browsers
Preload the working test script directly into TargetQA's Playwright Python compiler. Zero local dependencies or browser drivers needed.
Understanding the Breakdown
Python QA engineers moving from Selenium often write verbose `time.sleep()` calls or manual `WebDriverWait` loops when switching to Playwright, missing out on `pytest-playwright`'s auto-waiting assertions and clean fixture lifecycle.
Why Traditional Selectors Fail
Using Python's bare `assert page.locator(...).is_visible()` checks state once with zero retry, causing immediate flakiness on dynamic pages. Always wrap assertions in Playwright's `expect()`.
Production-Grade Solutions
Choose the strategy that matches your test architecture. Pattern #1 is recommended for most production test suites.
1. Use pytest-playwright's `page` Fixture & `expect()` Assertions
RecommendedPlaywright's Python `expect()` automatically retries until the assertion passes or times out.
import re
from playwright.sync_api import Page, expect
def test_search_and_assert(page: Page):
page.goto("https://demo.targetqa.com")
expect(page).to_have_title(re.compile("TargetQA"))
expect(page.get_by_role("heading", level=1)).to_be_visible()2. Handle Popups & Dialogs Idiomatically in Python
Use Python context managers (`with page.expect_popup()`) to capture newly opened tabs safely.
with page.expect_popup() as popup_info:
page.get_by_role("link", name="Open Details").click()
popup = popup_info.value
popup.wait_for_load_state()
expect(popup).to_have_url(re.compile(r"/details"))Complete Working Test Script
You can copy this exact test into your repository or run it immediately in our cloud sandbox against live demo targets.
import re
from playwright.sync_api import Page, expect
def test_playwright_python_basics(page: Page):
page.goto("https://demo.targetqa.com")
expect(page).to_have_title(re.compile("TargetQA"))
expect(page.get_by_role("heading", level=1)).to_be_visible()Best Practices & Golden Rules
- Always use `expect(locator).to_be_visible()` instead of `assert locator.is_visible()`.
- Prefer `get_by_role`, `get_by_label`, and `get_by_text` over brittle CSS/XPath chains.
- Use `pytest --tracing=retain-on-failure` in CI for instant visual debugging.
Common Pitfalls to Avoid
- Mixing synchronous `playwright.sync_api` inside an active asyncio event loop without using `async_api`.
- Using raw `assert` on `.inner_text()` before an async network response finishes rendering.
Frequently Asked Questions
Should I use sync or async Playwright in Python?
For most QA test suites with `pytest-playwright`, the synchronous API (`playwright.sync_api`) is simpler, cleaner, and integrates natively with standard pytest fixtures.
Can I run Playwright Python online without installing pip or Chromium?
Yes. TargetQA's Playwright Python Online Compiler runs `pytest-playwright` inside a cloud Chromium container directly in your browser with logs and video replays.