Getting started with Playwright Python (2026)

TL;DR

Install Playwright and pytest, run `playwright install`, then write tests with the sync or async API. Build around user-facing locators, isolated browser contexts, web-first assertions, and trace-backed CI failures.

Key Takeaways

• Install the Python package and browser binaries as separate, explicit steps.
• Use pytest fixtures to isolate browser context and test data.
• Prefer role, label, and test ID locators over CSS tied to layout.
• Let Playwright auto-wait instead of adding fixed sleeps.
• Capture traces, screenshots, and videos only where they improve diagnosis.
• Keep page objects focused on behavior, not assertions or test orchestration.

Getting started with Playwright Python means more than opening a browser and clicking a button. A reliable first project installs browser binaries correctly, uses resilient locators, isolates tests with contexts, and produces evidence when CI fails.

This guide builds that foundation with the synchronous Python API and pytest. The same concepts apply to the asynchronous API, but mixing the two styles inside one suite creates unnecessary complexity.

TL;DR

Install with pip install playwright pytest pytest-playwright, install Chromium with playwright install chromium, and start with one deterministic test. Avoid sleeps, shared accounts, and selectors copied from the browser inspector without review.

1. Getting Started with Playwright Python: The Mental Model

Playwright controls Chromium, Firefox, and WebKit through one automation API. Its Python binding exposes both synchronous and asynchronous interfaces. The important hierarchy is browser -> context -> page. A browser is the expensive process. A context is a lightweight, isolated session similar to an incognito profile. A page is a tab inside that session.

This model shapes suite design. Launch a browser efficiently, but give each test a fresh context so cookies, local storage, permissions, and cache do not leak. A test may use one or more pages when validating popups or multi-tab flows. Closing the context closes its pages and releases session resources.

Playwright actions include actionability checks. Before clicking, Playwright waits for the target to be attached, visible, stable, enabled, and able to receive events. Assertions such as expect(locator).to_be_visible() retry until the expected state appears or the assertion timeout expires. This is why a Playwright suite should model observable state, not timing guesses.

If you have used Selenium, read the Playwright versus Selenium guide to translate familiar concepts without carrying over fixed-wait habits.

2. Install Playwright Python in a Reproducible Environment

Use a virtual environment so application dependencies do not collide with global packages. The following commands work on macOS and Linux, while Windows users can activate the environment with .venv\Scripts\activate.

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install playwright pytest pytest-playwright
playwright install chromium

The Python package and browser binaries are separate installations. pip install playwright installs the client library and CLI. playwright install chromium downloads the compatible browser build. In a Linux container, playwright install --with-deps chromium can install supported operating-system dependencies as well, provided the environment permits package installation.

Pin dependencies in a lock file or requirements file so local and CI environments agree. A minimal requirements.txt can contain exact versions selected and tested by your team. Do not copy version numbers from an old tutorial. Generate pins from the environment you validate, and review upgrades deliberately.

Confirm the command is available with playwright --version. If the shell cannot find it, invoke python -m playwright install chromium, which ensures the command uses the active interpreter. Commit tests and dependency declarations, but do not commit downloaded browser caches or the virtual environment.

3. Write and Run the First Playwright Pytest Example

The pytest-playwright plugin supplies page, context, and browser fixtures. Create tests/test_example.py:

from playwright.sync_api import Page, expect


def test_docs_navigation(page: Page) -> None:
    page.goto("https://playwright.dev/python/")
    page.get_by_role("link", name="Docs").first.click()
    expect(page).to_have_title(lambda title: "Playwright" in title)
    expect(page.get_by_role("heading", level=1)).to_be_visible()

Run it with pytest -q. Add --headed when you need to watch the browser, and use --browser firefox or --browser webkit to change the project browser. The plugin owns fixture cleanup, so the test does not manually launch or close a browser.

A public website is useful for a smoke check, but production tests should target an environment your team controls. External pages can change content, rate-limit automation, or display regional variants. Configure the application base URL and navigate with relative paths.

[pytest]
addopts = -ra
base_url = http://localhost:3000
testpaths = tests

Then call page.goto("/login"). The base URL can also come from --base-url in CI. Keep a tiny smoke test first. Once it passes reliably, add authentication, data setup, and cross-browser coverage in measured steps.

4. Choose Locators That Express User Intent

A locator is a reusable query that resolves when an action or assertion runs. Prefer locators based on accessibility and visible meaning: get_by_role, get_by_label, get_by_placeholder, get_by_text, and get_by_test_id. They communicate what a user sees and fail clearly when the contract changes.

page.get_by_label("Email").fill("qa@example.com")
page.get_by_label("Password").fill("correct-horse-battery-staple")
page.get_by_role("button", name="Sign in").click()
expect(page.get_by_role("heading", name="Dashboard")).to_be_visible()

Role locators depend on accessible roles and names, which makes them valuable feedback about the product. If a control has no stable user-facing identity, ask developers for a semantic label or a dedicated test ID. Test IDs are appropriate for dynamic icons, canvases, and controls whose copy changes often. CSS is still valid for stable application contracts, but deeply nested CSS and XPath describe implementation rather than behavior.

Use filtering to narrow repeated elements. For a product card, locate the list item containing a product name and then click its button. Avoid .nth() unless order itself is the requirement. A locator that matches multiple elements causes strictness errors for single-target actions. Treat that error as useful ambiguity, not a reason to append .first automatically.

For deeper selector design, see resilient Playwright locator patterns.

5. Understand Auto-Waiting and Web-First Assertions

Fixed delays make tests both slow and unreliable. A two-second sleep wastes time when the UI responds in 100 milliseconds and still fails when a CI worker needs three seconds. Playwright actions and assertions instead wait for precise conditions.

from playwright.sync_api import expect

page.get_by_role("button", name="Save").click()
expect(page.get_by_text("Profile saved", exact=True)).to_be_visible()
expect(page).to_have_url(lambda url: url.endswith("/profile"))

Use locator assertions for UI state and response waiting for a specific network contract. Start the wait before the triggering action so the event cannot be missed.

with page.expect_response(
    lambda response: response.url.endswith("/api/profile")
    and response.request.method == "PUT"
) as response_info:
    page.get_by_role("button", name="Save").click()

assert response_info.value.ok

Do not wait for networkidle as a universal readiness signal. Applications with analytics, polling, or live connections might never become idle. Wait for the heading, table row, toast, URL, or API response that proves the requested operation completed. Configure timeouts near the suite level, then override only known slow operations. A larger global timeout can hide performance regressions and broken synchronization.

6. Use Fixtures for Isolation, Authentication, and Test Data

Fixtures turn setup into explicit dependencies. The plugin's page fixture already creates isolated state. Add custom fixtures for domain-level needs, not generic utility dumping grounds.

import pytest
from playwright.sync_api import Page


@pytest.fixture
def signed_in_page(page: Page) -> Page:
    page.goto("/login")
    page.get_by_label("Email").fill("tester@example.com")
    page.get_by_label("Password").fill("local-test-secret")
    page.get_by_role("button", name="Sign in").click()
    page.get_by_role("heading", name="Dashboard").wait_for()
    return page


def test_account_name(signed_in_page: Page) -> None:
    signed_in_page.goto("/account")
    assert signed_in_page.get_by_label("Display name").input_value() == "Test User"

UI login before every test is easy to understand but costly. Mature suites often authenticate through an API, save storage state, or use worker-scoped authenticated identities. Never let parallel workers mutate the same account. Provision an identity per worker or make tests read-only. Treat stored authentication files as secrets and exclude them from source control.

Create test data through a documented API when the UI operation is not the behavior under test. Use a unique suffix such as a UUID, and delete data during teardown when safe. Cleanup should tolerate a partially completed test. This separation keeps UI tests focused and reduces cascading failures.

7. Structure a Maintainable Python Test Project

A small suite can stay flat. As coverage grows, organize by business capability and keep infrastructure recognizable.

tests/
  conftest.py
  auth/
    test_login.py
  checkout/
    test_payment.py
pages/
  login_page.py
  checkout_page.py
helpers/
  api_client.py
pytest.ini
requirements.txt

Tests should tell a business story. Helper methods should hide mechanical interaction without hiding the meaningful outcome. A page object can expose sign_in(email, password) and locators for important results. It should not contain a giant end-to-end scenario or silently assert unrelated behavior.

from playwright.sync_api import Page, Locator


class LoginPage:
    def __init__(self, page: Page) -> None:
        self.page = page
        self.error: Locator = page.get_by_role("alert")

    def open(self) -> None:
        self.page.goto("/login")

    def sign_in(self, email: str, password: str) -> None:
        self.page.get_by_label("Email").fill(email)
        self.page.get_by_label("Password").fill(password)
        self.page.get_by_role("button", name="Sign in").click()

Use type annotations and linting so errors surface before a browser starts. The page object model for Playwright offers useful boundaries, but composition is usually better than deep inheritance.

8. Test Multiple Browsers, Devices, Tabs, and Frames

Cross-browser testing should reflect customer risk. Chromium coverage on every pull request plus Firefox and WebKit on scheduled or release runs is a sensible starting policy, not a universal rule. Run pytest --browser chromium --browser firefox --browser webkit when the plugin and environment support all installed binaries.

Mobile emulation changes viewport, user agent, touch capability, and device scale settings, but it does not turn desktop Chromium into an actual mobile operating system. Use browser.new_context(**playwright.devices["iPhone 13"]) when creating contexts manually, and reserve real-device testing for platform-specific risks.

For a new tab, wrap the action in expect_page:

with page.context.expect_page() as new_page_info:
    page.get_by_role("link", name="Open report").click()
report_page = new_page_info.value
report_page.wait_for_load_state("domcontentloaded")

For iframes, use frame_locator instead of manually retrieving frame objects when interacting with elements inside a stable embedded document.

payment = page.frame_locator("iframe[title='Secure payment']")
payment.get_by_label("Card number").fill("4242 4242 4242 4242")

Popups, frames, downloads, dialogs, and file choosers are events. Register the expectation before clicking. This ordering is essential because fast events can happen before the next Python statement begins waiting.

9. Debug Failures with Inspector, Traces, Screenshots, and Logs

Start locally with pytest --headed --slowmo 200 when visual pacing helps. Set PWDEBUG=1 before running pytest to open Playwright Inspector, pause execution, and explore locators. Use page.pause() only during development and remove it before commit.

A trace is more useful than a screenshot for many failures because it includes actions, timing, DOM snapshots, console details, and network activity. With pytest-playwright, run with trace options supported by the installed plugin, for example pytest --tracing retain-on-failure. Open a generated trace with playwright show-trace path/to/trace.zip.

Screenshots still help with layout and visual state:

page.screenshot(path="artifacts/failure.png", full_page=True)

Create the destination directory before calling the method. Avoid putting credentials or customer data into artifacts. CI retention policies should match the sensitivity of the environment. Attach the test name, browser, environment, seed, and relevant record IDs to failure reports so another engineer can reproduce the state.

When a test flakes, do not merely add retries. Compare traces from passes and failures. Determine whether the cause is selector ambiguity, shared data, a missed event, backend latency, environment instability, or a real race in the product. Retries measure instability, while diagnosis removes it.

10. Mock and Inspect Network Traffic Without Over-Mocking

Network routing can make a narrow UI test deterministic. Register a route before navigation, examine the request, and fulfill or continue it.

import json
from playwright.sync_api import Route


def mock_profile(route: Route) -> None:
    body = json.dumps({"name": "Ada Tester", "plan": "pro"})
    route.fulfill(status=200, content_type="application/json", body=body)

page.route("**/api/profile", mock_profile)
page.goto("/profile")
expect(page.get_by_text("Ada Tester")).to_be_visible()

Mock the dependency when the test specifically targets frontend behavior under a hard-to-create response, such as an error or empty state. Keep a separate layer of integrated tests against real services. If every response is mocked, a green suite cannot prove that the browser and backend agree on paths, headers, schemas, or authentication.

Use route.continue_() to pass a request through, optionally changing headers or method. Use page.on("requestfailed", handler) for diagnostic logging. Avoid logging authorization headers and bodies containing personal data. For API-focused validation, Playwright also offers APIRequestContext, but a dedicated API suite may be clearer when browser interaction adds no value.

11. Run Playwright Python in CI

CI should reproduce local commands, install compatible browser binaries, and preserve useful artifacts. A minimal GitHub Actions job looks like this:

name: browser-tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip
      - run: pip install -r requirements.txt
      - run: python -m playwright install --with-deps chromium
      - run: pytest -q --tracing retain-on-failure

Choose supported action majors when implementing the workflow and review dependency updates. Start the application and wait on a health endpoint before tests. Do not hide readiness problems inside the first UI test. Supply base URLs and test credentials through environment-specific secrets, never hard-code production credentials.

Parallelization can shorten feedback, but only after tests and data are independent. Split tests by stable duration or use a pytest parallel plugin approved by your team. A test that passes alone but fails in a shard usually exposes shared state, constrained resources, or ordering dependence. Track duration and flake rate by test so the slowest or least reliable cases receive engineering attention.

12. A Practical Learning Path for Playwright Python

Build capability in layers. First automate one read-only happy path using semantic locators and web-first assertions. Next add a form with validation, a test-data API fixture, and a negative scenario. Then add authentication state, trace collection, and a CI run. Finally add cross-browser coverage only where product risk justifies it.

At each stage, review whether the test proves user value. A long script that touches ten screens can fail in ten unrelated places and tell you little. Smaller tests with controlled setup localize defects while a few critical end-to-end journeys protect integration.

Learn Python fundamentals alongside Playwright: functions, classes, context managers, exceptions, typing, and pytest parametrization. Understand HTTP, accessible names, browser storage, and the event loop even if you use the sync API. The Python automation testing roadmap can help sequence those supporting skills.

A useful portfolio project includes a README with setup commands, a clean directory layout, several deterministic tests, CI configuration, and a sample trace or report. Interviewers value clear engineering decisions more than a large count of shallow tests.

13. Getting Started with Playwright Python Interview Preparation

Prepare to explain design choices, not only syntax. Be ready to draw the browser-context-page hierarchy, describe actionability, compare locators, and diagnose a flaky test. Practice turning requirements into observable assertions and identifying what should be created through an API fixture.

A strong interview answer states the principle, gives a concrete example, and acknowledges tradeoffs. For example, say that a context provides lightweight session isolation, so you normally create one per test, while browser reuse reduces process startup cost. Do not claim that Playwright eliminates flakiness. It removes several timing problems, but poor data, unstable environments, ambiguous selectors, and product races still require engineering.

The structured questions below mirror the interviewQnA field for fast review. For a larger practice set, use Playwright interview questions with answers.

Interview Questions and Answers

Q: What is the difference between a browser, context, and page?

A browser is the engine process, a context is an isolated session with its own cookies and storage, and a page is a tab. Reusing a browser while creating fresh contexts balances speed and isolation.

Q: Why are Playwright locators preferable to cached element handles?

Locators resolve again when used and work with auto-waiting and retrying assertions. They are more resilient when a framework rerenders the DOM.

Q: How would you remove a fixed sleep?

Identify the business signal the sleep was guessing, such as a visible confirmation, URL change, or response. Replace it with a locator assertion or an event expectation registered before the action.

Q: When should a response be mocked?

Mock when isolating a frontend state that is rare, destructive, or difficult to create. Retain integrated tests against the real contract so mocks do not conceal drift.

Q: How do you test multiple signed-in users?

Create separate contexts, each with its own storage state or login flow. Never switch identities in one shared context when isolation matters.

Q: What evidence helps diagnose a CI-only failure?

A retained trace, test logs, browser and environment metadata, screenshots, and stable data identifiers usually provide enough context. Compare a passing and failing trace before changing timeouts.

Q: Sync or async Python API?

Use one style consistently. Sync is straightforward for ordinary pytest browser tests, while async fits an existing asynchronous application or concurrency model.

Common Mistakes

• Installing the Python package but forgetting compatible browser binaries.
• Sharing one context, page, or mutable user account across tests.
• Copying long CSS or XPath selectors that encode transient layout.
• Using time.sleep() instead of waiting for an observable condition.
• Registering popup, download, or response waits after the click.
• Adding retries without analyzing traces and classifying the failure.
• Putting secrets or authenticated storage state in the repository.
• Building page objects that contain entire workflows and unrelated assertions.
• Mocking every backend request, then calling the suite end to end.

Conclusion

Getting started with Playwright Python is fastest when the first suite is small, isolated, and observable. Install the library and browsers explicitly, use pytest fixtures and semantic locators, assert business-visible state, and retain traces for failed CI runs.

Treat the first month as framework discovery as well as test delivery. Record failure categories, execution duration, and maintenance friction. If most failures come from shared accounts, invest in data provisioning. If locator ambiguity dominates, improve accessible names and test-ID contracts with developers. If CI differs from local runs, standardize browser installation, application startup, environment variables, and artifacts. These observations should shape the framework more than a copied folder structure.

Keep ownership close to product teams. A passing browser test is useful only when someone trusts its assertion, understands its setup, and acts on its failure. Review tests with production changes, delete redundant scenarios, and move lower-risk logic to faster unit or API layers. Browser coverage should protect user journeys that genuinely need a browser.

Your next step is to automate one important path in an environment you control. Make it deterministic before adding more browsers or scenarios, then grow coverage around risk rather than raw test count. Begin deliberately.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• Playwright Python fixtures with pytest (2026)
• Playwright Python page object model (2026)
• Playwright Python parallel with pytest-xdist (2026)
• Playwright Python vs Selenium Python (2026)
• Accessibility testing with Playwright (2026)
• How to Build a BDD framework with Cucumber and Playwright (2026)