Playwright 1.50: Modern E2E Browser Testing Guide

Playwright 1.50 has become the go‑to framework for modern end‑to‑end (E2E) testing, offering a single API that drives Chromium, WebKit, and Firefox across desktop and mobile. Whether you’re a solo developer or part of a large QA team, Playwright’s reliability and speed can dramatically cut flaky test time. In this guide we’ll walk through the essential concepts, set up a robust test suite, and explore real‑world patterns that keep your browser tests maintainable.

Why Playwright Stands Out in 2024

Playwright ships with built‑in auto‑waiting, network interception, and a powerful test runner that rivals Cypress and Selenium. The 1.50 release adds Web‑First assertions, tighter integration with VS Code, and a leaner installation footprint. These improvements translate into faster feedback loops and less boilerplate code.

Another key advantage is the “single source of truth” approach: the same test file runs against all three browsers without any extra configuration. This cross‑browser confidence is crucial when you need to support legacy Safari users while also targeting the latest Chrome features.

Getting Started: Installation and Project Scaffold

First, create a fresh virtual environment and install Playwright with its browsers. The --with-deps flag ensures all required system libraries are pulled in, which is handy on CI runners.

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install playwright==1.50.0
playwright install --with-deps

Next, generate the test skeleton using the Playwright test generator. It creates a tests/ folder, a playwright.config.ts (or .py for Python users), and a sample spec file.

playwright codegen https://example.com --target python

The generated script demonstrates how Playwright records user actions and translates them into reliable selectors. Save the output as tests/example_test.py and you’ll have a runnable test in seconds.

Core Concepts: Browser, Context, and Page

Understanding the three-tier model is essential for writing scalable tests.

Browser

A Browser instance represents the actual engine (Chromium, Firefox, or WebKit). Launching a browser is expensive, so you typically do it once per worker process.

BrowserContext

A BrowserContext isolates cookies, local storage, and permissions. Think of it as an incognito window that can host multiple pages simultaneously. Using separate contexts for each test guarantees no state leakage.

Page

A Page is the tab or window where you interact with the DOM. All actions—clicks, navigation, network requests—are performed on a page object.

Here’s a concise example that spins up a browser, creates a context, and opens a page:

from playwright.sync_api import sync_playwright

def run():
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=False)
        context = browser.new_context()
        page = context.new_page()
        page.goto("https://playwright.dev")
        page.screenshot(path="homepage.png")
        browser.close()

if __name__ == "__main__":
    run()

Writing Your First Test with Playwright Test Runner

The Playwright test runner (installed automatically with playwright) provides fixtures, parallelism, and rich reporting out of the box. Create a file tests/login.spec.py and add the following:

import pytest
from playwright.sync_api import Page

@pytest.fixture(scope="function")
def login(page: Page):
    page.goto("https://demo.example.com/login")
    page.fill('input[name="email"]', "test@example.com")
    page.fill('input[name="password"]', "Secret123")
    page.click('button[type="submit"]')
    page.wait_for_selector("text=Dashboard")
    return page

def test_dashboard_shows_welcome(login: Page):
    assert login.is_visible('text=Welcome, Test User')

The page fixture is provided by Playwright automatically; it creates a fresh context for each test, ensuring isolation. The test itself is only three lines of assertions, thanks to Playwright’s auto‑waiting.

Advanced Selectors and Auto‑Waiting

Playwright’s selector engine goes beyond CSS. You can target elements by text, role, or even accessibility attributes, making tests resilient to UI changes.

• Text selector: page.click("text=Submit")
• Role selector: page.get_by_role("button", name="Delete")
• Locator chaining: page.locator("form").locator("input").first

All locator actions automatically wait for the element to be actionable (visible, enabled, stable). This eliminates the need for manual wait_for_selector calls in most cases.

Pro tip: Use expect(page).to_have_url(/dashboard/) for URL assertions; it retries until the pattern matches, reducing flaky timing issues.

Network Interception: Mocking APIs and Testing Edge Cases

Real‑world E2E tests often need to simulate server responses—slow networks, error codes, or specific payloads. Playwright’s route API lets you intercept any request and provide a custom response.

def test_error_handling(page: Page):
    # Mock a 500 error for the orders endpoint
    page.route("**/api/orders", lambda route: route.fulfill(
        status=500,
        body='{"error":"Internal Server Error"}',
        content_type="application/json"
    ))
    page.goto("https://demo.example.com/orders")
    page.click("text=Refresh")
    # Verify the UI shows the proper error banner
    expect(page.locator(".error-banner")).to_have_text("Failed to load orders")

Because the mock is scoped to the test’s context, other tests continue to hit the real backend. This pattern is invaluable for testing retry logic, fallback UI, and performance degradations without slowing down the entire suite.

Parallel Execution and Test Projects

Playwright’s test runner spawns workers based on the number of CPU cores, running tests in parallel by default. You can fine‑tune this behavior in playwright.config.py.

# playwright.config.py
from pathlib import Path
import pytest

def pytest_configure(config):
    config.addinivalue_line(
        "markers", "skip_browser: skip test for a specific browser"
    )

# Example configuration for multiple browsers
projects = [
    {
        "name": "Chromium",
        "use": {"browserName": "chromium"},
    },
    {
        "name": "Firefox",
        "use": {"browserName": "firefox"},
    },
    {
        "name": "WebKit",
        "use": {"browserName": "webkit"},
    },
]

# Export the configuration
config = {
    "testDir": "tests",
    "timeout": 30_000,
    "retries": 1,
    "workers": 4,
    "projects": projects,
}

Each project runs the same test suite against a different browser, and the runner aggregates results into a single HTML report. This approach guarantees cross‑browser parity without duplicating test code.

CI/CD Integration: From Local to Pipeline

Running Playwright in CI requires a few extra steps: installing browsers, setting headless mode, and handling artifacts. Most CI providers already have a Docker image that includes Playwright.

# .github/workflows/playwright.yml
name: Playwright Tests
on: [push, pull_request]

jobs:
  e2e:
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: pip install -r requirements.txt
      - name: Run tests
        run: playwright test --reporter=html
      - name: Upload report
        uses: actions/upload-artifact@v3
        with:
          name: playwright-report
          path: playwright-report/

The Docker image already contains the three browsers, so you don’t need to run playwright install again. The --reporter=html flag generates a visual report that can be downloaded as an artifact for quick debugging.

Debugging, Tracing, and Video Recording

When a test fails, Playwright can automatically capture a trace that includes screenshots, network logs, and DOM snapshots. Enable tracing in the config or per‑test using the trace fixture.

def test_search(page: Page, trace):
    trace.start()
    page.goto("https://example.com")
    page.fill('input[placeholder="Search"]', "Playwright")
    page.press('input[placeholder="Search"]', "Enter")
    expect(page).to_have_url(/search\?q=Playwright/)
    trace.stop(path="trace.zip")

Open the generated trace.zip in the Playwright Trace Viewer (npx playwright show-trace trace.zip) to step through each action and see exactly where the failure occurred. Video recording works similarly; set recordVideo in the context options to capture flaky UI interactions.

Real‑World Use Cases

1. Feature Flag Validation – When rolling out a new feature behind a flag, write a test that toggles the flag via an API call, then asserts the UI changes accordingly. Use page.request.post to flip the flag before navigation.

def test_new_dashboard_enabled(page: Page):
    # Enable the flag for the test user
    page.request.post(
        "https://api.example.com/flags",
        data={"userId": 123, "flag": "new-dashboard", "enabled": True}
    )
    page.goto("https://app.example.com")
    expect(page.locator("#new-dashboard")).to_be_visible()

2. Progressive Web App (PWA) Offline Testing – Simulate offline mode to verify your service worker caches assets correctly.

def test_offline_fallback(page: Page):
    page.goto("https://pwa.example.com")
    page.context.set_offline(True)
    page.reload()
    expect(page.locator("text=You are offline")).to_be_visible()
    page.context.set_offline(False)

3. Multi‑Step Checkout Flow – Combine network interception with screenshots to create a visual regression suite for each checkout stage.

def test_checkout_flow(page: Page):
    page.goto("https://shop.example.com")
    page.click("text=Add to cart")
    page.click("text=Checkout")
    # Mock payment gateway response
    page.route("**/payment", lambda route: route.fulfill(
        status=200,
        body='{"status":"success","transactionId":"abc123"}',
        content_type="application/json"
    ))
    page.click("text=Pay now")
    page.wait_for_selector("text=Thank you for your purchase")
    page.screenshot(path="checkout_success.png")

Pro Tips & Best Practices

1. Keep selectors stable. Prefer data-test-id attributes over fragile CSS paths. Playwright’s get_by_role is also a great alternative for accessible components.

2. Use fixtures wisely. Define a custom login fixture in conftest.py to share authentication logic across many tests, reducing duplication.

3. Limit test duration. A fast suite stays under 5 seconds per test on average. If a test exceeds 30 seconds, consider splitting it or mocking external services.

4. Leverage test tags. Mark long‑running or flaky tests with @pytest.mark.slow and exclude them in quick CI runs using --grep -slow.

Performance Optimizations

Playwright’s headless mode is the default for CI, but you can gain additional speed by disabling video recording and reducing the viewport size for non‑visual tests. Also, reuse the same Browser instance across workers when possible, as launching a browser is the most expensive operation.

For large test suites, consider sharding tests by feature area and running them on separate agents. Playwright’s JSON reporter can be consumed by test management tools to visualize flaky trends over time.

Migration from Selenium or Cypress

If you’re coming from Selenium, you’ll notice Playwright’s API is more concise—no need for explicit waits or driver binaries. Replace driver.find_element_by_xpath with page.locator("xpath=//...") and let Playwright handle the waiting.

Cypress users will appreciate the ability to run tests in real browsers rather than a headless Chromium wrapper. The biggest shift is moving from the “global” Cypress object to explicit page objects, which improves test isolation and parallelism.

Extending Playwright with Custom Helpers

Complex applications often require reusable helper functions. Create a utils.py module with high‑level actions like add_to_cart or fill_address_form. Import these helpers in your specs to keep test files declarative.

# utils.py
def add_to_cart(page: Page, product_id: str):
    page.goto(f"https://shop.example.com/product/{product_id}")
    page.click('button[data-test-id="add-to-cart"]')
    page.wait_for_selector('text=Added to cart')

Now a test becomes a simple narrative:

from utils import add_to_cart

def test_multiple_items_checkout(page: Page):
    add_to_cart(page, "sku-123")
    add_to_cart(page, "sku-456")
    page.click('a[href="/cart"]')
    expect(page.locator("text=2 items")).to_be_visible()

Conclusion

Playwright 1.50 delivers a mature, developer‑friendly platform for modern E2E testing. By embracing its auto‑waiting, powerful selectors, and built‑in test runner, you can write concise, reliable tests that run across all major browsers. Combine network mocking, tracing, and parallel execution to achieve fast feedback loops, and integrate seamlessly into CI pipelines for continuous quality assurance. With the patterns and pro tips outlined above, you’re now equipped to scale your test suite from a single login flow to a full‑blown e‑commerce platform—all while keeping the codebase clean and maintainable.