DEV Community: Karan Sharma

Structuring Playwright Tests with the Page Object Model in Python

Karan Sharma — Wed, 23 Sep 2026 03:54:31 +0000

As a Playwright test suite grows, locators and navigation logic often get duplicated across multiple test files. A small UI change then forces edits in several places, which increases maintenance cost. The Page Object Model (POM) pattern solves this by isolating page structure and interactions into dedicated classes, keeping test functions focused only on flow and assertions.

The problem without POM

def test_search_box_ready():
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        page = browser.new_page()
        page.goto("https://www.google.com", wait_until="domcontentloaded")
        search_box = page.locator("textarea[name='q']")
        expect(search_box).to_be_visible()
        browser.close()

If multiple tests reuse this same search box, the locator string gets duplicated across every test. Any markup change then means updating every occurrence.

Project structure with POM

project/
  pages/
    google_page.py
  tests/
    test_google_pom.py

Page class implementation

# pages/google_page.py
from playwright.sync_api import Page, expect


class GooglePage:
    URL = "https://www.google.com"

    def __init__(self, page: Page):
        self.page = page
        self.search_box = page.locator("textarea[name='q']")

    def open(self):
        self.page.goto(self.URL, wait_until="domcontentloaded")

    def is_search_ready(self):
        expect(self.search_box).to_be_visible()
        expect(self.search_box).to_be_editable()

Line by line explanation

from playwright.sync_api import Page, expect: imports the Page type hint and the expect assertion helper.
class GooglePage:: defines the page object representing the Google homepage.
URL = "https://www.google.com": stores the target URL as a reusable constant.
def __init__(self, page: Page):: constructor receives an active Playwright page.
self.page = page: stores the page reference for reuse in methods.
self.search_box = page.locator("textarea[name='q']"): defines the search box locator exactly once.
def open(self):: encapsulates the navigation step.
self.page.goto(self.URL, wait_until="domcontentloaded"): navigates and waits for DOM readiness.
def is_search_ready(self):: encapsulates the readiness validation.
expect(self.search_box).to_be_visible(): assertion for visibility.
expect(self.search_box).to_be_editable(): assertion for input readiness.

Test implementation using the page object

# tests/test_google_pom.py
from playwright.sync_api import sync_playwright
from pages.google_page import GooglePage


def test_search_box_ready_with_pom():
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        page = browser.new_page()

        google_page = GooglePage(page)
        google_page.open()
        google_page.is_search_ready()

        browser.close()

Line by line explanation

from playwright.sync_api import sync_playwright: imports the Playwright sync entry point.
from pages.google_page import GooglePage: imports the page object.
def test_search_box_ready_with_pom():: defines the pytest test function.
with sync_playwright() as p:: starts Playwright with automatic cleanup.
browser = p.chromium.launch(headless=True): launches Chromium headlessly.
page = browser.new_page(): opens a new page.
google_page = GooglePage(page): wraps the page inside the page object.
google_page.open(): performs navigation via the encapsulated method.
google_page.is_search_ready(): performs assertions via the encapsulated method.
browser.close(): closes the browser session.

Running with an HTML report

py -m pytest -q tests/test_google_pom.py --html=playwright_report.html --self-contained-html

Why this pattern matters

Locators exist in one place only.
Tests read like flow descriptions rather than raw selector syntax.
UI changes require editing the page class, not every test.
New tests can reuse existing page objects directly.

Key takeaway

The Page Object Model turns scattered locators and repeated navigation code into a single reusable abstraction, keeping maintenance cost low as the suite scales.

Without POM vs. with POM

Aspect	Without POM	With POM
Locator definition	Repeated inline in every test	Defined once inside the page class
Impact of a UI change	Requires editing every affected test	Requires editing only the page class
Test readability	Mixed with raw selector syntax	Reads as a sequence of user actions
Reuse across tests	Copy-paste of locators and navigation	Import and reuse the same page object
Maintenance cost at scale	Grows quickly with suite size	Stays low as the suite grows

Playwright with Python: Stable Locators and Better Assertions

Karan Sharma — Tue, 22 Sep 2026 03:30:18 +0000

Reliable automation starts with stable tests.

In Playwright, test stability improves when we use:

strong locators
built-in waiting behavior
meaningful assertions

Code example

from playwright.sync_api import sync_playwright, expect

def test_google_search_box_is_ready():
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        page = browser.new_page()

        page.goto("https://www.google.com", wait_until="domcontentloaded")

        search_box = page.locator("textarea[name='q']")
        expect(search_box).to_be_visible()
        expect(search_box).to_be_editable()

        browser.close()

## What this test checks

- Search input is visible
- Search input is editable

Report command

py -m pytest -q test_google_playwright.py --html=playwright_report.html --self-contained-html

## Why this approach is useful

- Fewer flaky failures
- Better confidence in test outcomes
- Cleaner reporting for review and collaboration

What Is Playwright? Install It in VS Code with Python (Beginner Guide)

Karan Sharma — Thu, 17 Sep 2026 04:05:20 +0000

Playwright is a modern browser automation and end-to-end testing tool. It lets you control Chromium, Firefox, and WebKit using code.

If you are using Python and VS Code, this guide shows exactly how to install and verify Playwright.

What is Playwright?

Playwright is used for:

End-to-end testing of web apps
UI automation for repetitive browser workflows
Cross-browser testing with one API
Fast, reliable automation with auto-wait behavior

Why people like it:

Works across multiple browsers
Handles modern web apps well
Great debugging tools
Supports Python, JavaScript/TypeScript, Java, and .NET

Prerequisites

Before installation, make sure you have:

VS Code installed
Python installed
Internet connection for package and browser downloads

Optional but recommended:

Python extension in VS Code

Install Playwright in Python

Open the VS Code terminal and run:

py -m pip install playwright

If py does not work on your machine:

python -m pip install playwright

Install Browser Binaries

After installing the package, install browsers required by Playwright:

py -m playwright install

Fallback command:

python -m playwright install

Verify Installation

Check package details:

py -m pip show playwright

Check CLI version:

py -m playwright --version

Expected result: a version number (for example, 1.63.0).

Quick Python Test Script

Create a file named test_playwright.py:

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.close()

Run it:

py test_playwright.py

If it prints Example Domain, your setup is working.

VS Code Tips

Select the correct Python interpreter in VS Code
Use one virtual environment per project
Keep Playwright updated:

py -m pip install --upgrade playwright
py -m playwright install

Common Errors and Fixes

Command not found for py
Use python instead of py.
Browser launch error
Run py -m playwright install again.
Wrong interpreter in VS Code
Switch interpreter from the command palette and re-run.

Final Thoughts

Playwright is one of the best choices for modern browser automation. In just a few commands, you can set it up in VS Code with Python and start writing reliable tests.

If you are new, start small: automate one page, one click flow, one assertion. Then scale up to full end-to-end tests.