Skip to content
Target QATargetQA
Playwright Python · PythonLocators & SelectorsBeginner5 min read

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.

By TargetQA Engineering Team•Updated 2026-11-20
Interactive Cloud Sandbox

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.

Test Live in Compiler
The Problem & Error Symptoms

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.

Under the Hood

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()`.

Field-Tested Patterns

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

Recommended

Playwright's Python `expect()` automatically retries until the assertion passes or times out.

1. Use pytest-playwright's `page` Fixture & `expect()` Assertions (python)
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()
How it works: Because `expect()` polls automatically, your Python tests stay short, readable, and deterministic across fast laptops and slower CI workers.

2. Handle Popups & Dialogs Idiomatically in Python

Use Python context managers (`with page.expect_popup()`) to capture newly opened tabs safely.

2. Handle Popups & Dialogs Idiomatically in Python (python)
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"))
How it works: The context manager subscribes to the popup event before the click fires, eliminating race conditions.
Full Executable Cloud Test
Open in compiler

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.

test-recipe.spec.ts
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()
Target framework: Playwright Python · Language: Python
Preload & Run in Compiler
Production Checklist

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.
Avoid Test Flakiness

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.

Hands-On Practice

Practice This Skill in TargetQA Challenges

Explore More Automation Guides