Getting Started with Playwright | Browser Automation with Python — A Beginner’s Guide

Playwright is a browser automation library developed by Microsoft. Compared to Selenium, it requires less configuration, ships with auto-waiting built in, and offers a modern API. This guide walks you through installation to running your first test — one command at a time.

📌 Who This Article Is For

📖 What You’ll Be Able to Do After This Guide

I have worked on E2E tests using Playwright across multiple real projects, including migrations from Selenium to Playwright.
This guide targets “a working test by the end of day one” and proactively addresses the points where beginners typically get stuck.

What Is Playwright? How Does It Compare to Selenium?

Why Playwright Has Grown So Quickly

Since around 2020, Playwright has gained rapid adoption as an E2E testing tool. Here’s why.

① Install Playwright

First, make sure you have a Python environment ready (see the Python Setup Guide).
Run the following with your virtual environment activated.

# Install Playwright and the pytest plugin
pip install playwright pytest-playwright

# Download the browser binaries (Chromium, Firefox, WebKit)
playwright install

Verify the installation:

playwright --version
# Should print: Playwright 1.x.x

② Run Something First (Script Style)

Before using pytest, let’s confirm Playwright works with a simple standalone script.

# first_playwright.py
from playwright.sync_api import sync_playwright


def main() -> None:
    with sync_playwright() as p:
        # Launch browser (headless=False shows the browser window)
        browser = p.chromium.launch(headless=False)
        page = browser.new_page()

        # Open a page
        page.goto("https://example.com")  # sample URL

        # Print the page title
        print(page.title())

        # Take a screenshot
        page.screenshot(path="screenshot.png")

        browser.close()


if __name__ == "__main__":
    main()

python first_playwright.py

If a browser window opens and the page loads, it’s working. screenshot.png will also be saved.

③ Write Tests with pytest

In real projects, tests are managed with pytest. With pytest-playwright installed, the page fixture is available automatically.

Your First Test File

# test_first.py
from playwright.sync_api import Page, expect


def test_page_title(page: Page) -> None:
    page.goto("https://example.com")  # sample URL
    assert "Example" in page.title()
    # The Playwright-idiomatic way uses expect:
    # expect(page).to_have_title("Example Domain")


def test_heading_visible(page: Page) -> None:
    page.goto("https://example.com")  # sample URL
    heading = page.get_by_role("heading", name="Example Domain")
    expect(heading).to_be_visible()  # Playwright-idiomatic assertion

pytest test_first.py -v

Expected output:

========================= test session starts ==========================
collected 2 items

test_first.py::test_page_title    PASSED    [ 50%]
test_first.py::test_heading_visible PASSED  [100%]

========================== 2 passed in 2.34s ==========================

Login Form Test (Practical Example)

# test_login.py
from playwright.sync_api import Page, expect


def test_login_success(page: Page) -> None:
    page.goto("https://example.com/login")  # sample URL

    # Fill in email
    page.get_by_label("Email").fill("user@example.com")

    # Fill in password
    page.get_by_label("Password").fill("password123")

    # Click the login button
    page.get_by_role("button", name="Login").click()

    # Verify redirect to dashboard
    expect(page).to_have_url("https://example.com/dashboard")  # sample URL


def test_login_invalid_password(page: Page) -> None:
    page.goto("https://example.com/login")  # sample URL

    page.get_by_label("Email").fill("user@example.com")
    page.get_by_label("Password").fill("wrong-password")
    page.get_by_role("button", name="Login").click()

    # Verify error message is shown
    expect(page.get_by_test_id("error-message")).to_be_visible()
    expect(page.get_by_test_id("error-message")).to_contain_text("Incorrect password")

④ Writing Assertions with expect

Playwright’s expect is an assertion library tailored for web pages that automatically retries until the condition is met.

⑤ Organize Tests with conftest.py

Putting base URL and browser configuration in conftest.py keeps individual test files clean and focused.

# conftest.py
import pytest
from playwright.sync_api import Page


BASE_URL = "https://example.com"  # sample URL


@pytest.fixture
def logged_in_page(page: Page) -> Page:
    """Returns a page fixture already logged in."""
    page.goto(f"{BASE_URL}/login")
    page.get_by_label("Email").fill("user@example.com")
    page.get_by_label("Password").fill("password123")
    page.get_by_role("button", name="Login").click()
    page.wait_for_url(f"{BASE_URL}/dashboard")
    return page

# test_dashboard.py
from playwright.sync_api import Page, expect


def test_dashboard_shows_username(logged_in_page: Page) -> None:
    expect(logged_in_page.get_by_test_id("user-name")).to_contain_text("Test User")

Configure Browser and Headless Mode in pytest.ini

# pytest.ini
[pytest]
addopts =
    --browser chromium
    --headed

# Can also be passed on the command line
pytest --browser chromium              # use Chromium
pytest --browser firefox               # use Firefox
pytest --headed                        # show browser window
pytest --headless                      # headless mode (for CI)
pytest --slowmo 500                    # slow down actions by 500ms for easier debugging

⑥ Auto-Generate Test Code with Codegen

Codegen records your browser interactions and converts them into test code in real time.
It’s a great starting point when you’re unsure how to write a locator.

# Launch Codegen (replace URL with your target page)
playwright codegen https://example.com  # sample URL

A browser opens; as you interact with it, the code appears in a side panel.

⑦ Screenshots and Trace Viewer

Screenshots

# Full-page screenshot
page.screenshot(path="screenshots/result.png", full_page=True)

# Screenshot of a specific element
page.get_by_test_id("error-message").screenshot(path="screenshots/error.png")

Trace Viewer — Inspect Test Failures Visually

Trace Viewer records every step of a test run so you can inspect exactly what the page looked like at each point when a test fails.

# Save a trace automatically when a test fails
pytest --tracing=retain-on-failure

# Open the trace to inspect it
playwright show-trace trace.zip

7 Common Pitfalls When Starting with Playwright

Frequently Asked Questions (FAQ)

Summary

Playwright ships with auto-waiting, Trace Viewer, and Codegen as standard — less setup than Selenium and accessible even to those new to browser automation.
Just running playwright codegen against your app gives you a feel for the whole workflow.

As your test suite grows, organize it with Page Object Model (POM), or take the next step and run tests automatically in GitHub Actions on every push.