Playwright + pytest Test Structure Best Practices | Folder Design, Fixtures & Marks Explained

Going beyond simply connecting Playwright and pytest — designing your folder structure, fixture hierarchy, and mark strategy from the start is what lets you build a test automation foundation that stays maintainable long-term.

Combining Playwright and Python makes it easy to write E2E tests. But as your test suite grows, you’ll often run into problems like these:

• Fixtures multiply and you lose track of where to put them
• Selectors end up scattered throughout your test files
• It becomes unclear which tests to run and when in CI/CD

This article walks you through the Playwright × pytest best practices structure that prevents these problems — from folder design to fixtures, conftest.py, and pytest.ini, all in one place.

① Recommended Folder Structure

Let’s start with the overall folder structure. Two patterns are introduced: a simple version for small projects and an expanded version for medium-to-large teams.

Simple Version (Small Projects / Learning)

my_project/
├── pages/                    # Page Object Model (page interaction classes)
│   ├── __init__.py
│   ├── login_page.py
│   └── inventory_page.py
├── tests/                    # Test files
│   ├── conftest.py           # Shared fixtures
│   ├── test_login.py
│   └── test_inventory.py
├── pytest.ini                # pytest configuration
└── requirements.txt

Expanded Version (Medium–Large Projects / Team Use)

my_project/
├── pages/                    # Page Object Model
│   ├── __init__.py
│   ├── base_page.py          # Base class shared by all pages
│   ├── login_page.py
│   └── inventory_page.py
├── tests/                    # Test files
│   ├── conftest.py           # Session/browser-level fixtures
│   ├── e2e/                  # E2E tests (full user flows)
│   │   ├── conftest.py       # E2E-specific fixtures
│   │   └── test_purchase_flow.py
│   ├── smoke/                # Smoke tests (minimal sanity checks)
│   │   └── test_login_smoke.py
│   └── regression/           # Regression tests
│       └── test_cart.py
├── utils/                    # Helper functions and constants
│   ├── __init__.py
│   └── constants.py          # URL and test data constants
├── reports/                  # Test report output
├── pytest.ini
└── requirements.txt

② pytest.ini — Complete Configuration

Place pytest.ini at the project root. With this in place, every team member runs tests with identical settings.

# pytest.ini
[pytest]
# Test discovery path
testpaths = tests

# Default options
addopts =
    -v
    --tb=short
    --html=reports/report.html
    --self-contained-html

# Custom mark registration (unregistered marks produce warnings)
markers =
    smoke: Smoke tests (minimal sanity checks, run on every push)
    regression: Regression tests (run before release)
    e2e: E2E tests (full flows, time-consuming)
    slow: Tests that take a long time to run

# Log settings
log_cli = true
log_cli_level = INFO
log_format = %(asctime)s %(levelname)s %(message)s
log_date_format = %Y-%m-%d %H:%M:%S

③ conftest.py — Layered Design

The best practice for conftest.py is to separate fixtures by scope — placing them in the directory that matches their intended reach.

tests/conftest.py (Shared Across the Entire Project)

# tests/conftest.py
import pytest
from playwright.sync_api import sync_playwright

# ============================================================
# Browser / page fixtures (session scope)
# ============================================================

@pytest.fixture(scope="session")
def browser_instance():
    """Share a single browser instance across the entire test session"""
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        yield browser
        browser.close()

@pytest.fixture(scope="function")
def page(browser_instance):
    """Create a fresh page (tab) for each test"""
    context = browser_instance.new_context(
        viewport={"width": 1280, "height": 720}
    )
    page = context.new_page()
    yield page
    context.close()  # close the context after each test

# ============================================================
# Authentication fixtures
# ============================================================

@pytest.fixture(scope="session")
def base_url():
    """Return the base URL for the test target"""
    # In actual code, add https:// prefix (e.g. "https://www.saucedemo.com")
    return "www.saucedemo.com"

@pytest.fixture
def valid_credentials():
    """Login credentials for happy-path tests"""
    return {
        "username": "standard_user",
        "password": "secret_sauce"
    }

@pytest.fixture
def locked_out_credentials():
    """Login credentials for locked-out user (error case tests)"""
    return {
        "username": "locked_out_user",
        "password": "secret_sauce"
    }

# ============================================================
# Pre-logged-in page fixture (commonly needed — centralize it)
# ============================================================

@pytest.fixture
def logged_in_page(page, base_url, valid_credentials):
    """Return a page fixture already in the logged-in state"""
    page.goto(f"https://{base_url}/")
    page.fill("#user-name", valid_credentials["username"])
    page.fill("#password", valid_credentials["password"])
    page.click("#login-button")
    page.wait_for_url("**/inventory.html")
    return page

tests/e2e/conftest.py (E2E Tests Only)

# tests/e2e/conftest.py
import pytest

@pytest.fixture
def cart_items():
    """Test data for cart items used in E2E tests"""
    return ["Sauce Labs Backpack", "Sauce Labs Bike Light"]

@pytest.fixture
def shipping_info():
    """Shipping information for E2E checkout tests"""
    return {
        "first_name": "Test",
        "last_name": "User",
        "postal_code": "10001"
    }

④ Page Object Model Implementation

Here’s how to implement Page Object Model alongside pytest. The key is putting shared behavior in a base class.

pages/base_page.py (Base Class)

# pages/base_page.py
from playwright.sync_api import Page

class BasePage:
    """Base class containing operations common to all pages"""

    def __init__(self, page: Page):
        self.page = page

    def navigate(self, url: str):
        """Navigate to the specified URL"""
        self.page.goto(url)

    def get_title(self) -> str:
        """Return the current page title"""
        return self.page.title()

    def take_screenshot(self, name: str):
        """Save a screenshot to the reports folder"""
        self.page.screenshot(path=f"reports/{name}.png")

pages/login_page.py

# pages/login_page.py
from pages.base_page import BasePage

class LoginPage(BasePage):
    """Page Object for the login page"""

    # Locator constants (manage all selectors in one place)
    USERNAME_INPUT = "#user-name"
    PASSWORD_INPUT = "#password"
    LOGIN_BUTTON   = "#login-button"
    ERROR_MESSAGE  = ".error-message-container h3"

    def login(self, username: str, password: str):
        """Perform a login action"""
        self.page.fill(self.USERNAME_INPUT, username)
        self.page.fill(self.PASSWORD_INPUT, password)
        self.page.click(self.LOGIN_BUTTON)

    def get_error_message(self) -> str:
        """Return the error message text"""
        return self.page.locator(self.ERROR_MESSAGE).text_content()

⑤ Test File Implementation

Here’s the complete test file combining fixtures and Page Objects.

tests/smoke/test_login_smoke.py

# tests/smoke/test_login_smoke.py
import pytest
from pages.login_page import LoginPage

@pytest.mark.smoke
def test_login_success(page, base_url, valid_credentials):
    """Smoke: verify that a valid login succeeds"""
    login_page = LoginPage(page)
    login_page.navigate(f"https://{base_url}/")
    login_page.login(
        valid_credentials["username"],
        valid_credentials["password"]
    )
    assert page.url.endswith("/inventory.html"), \
        f"URL after login does not match expected: {page.url}"

@pytest.mark.smoke
def test_login_wrong_password(page, base_url):
    """Smoke: verify that a wrong password shows an error message"""
    login_page = LoginPage(page)
    login_page.navigate(f"https://{base_url}/")
    login_page.login("standard_user", "wrong_password")
    error = login_page.get_error_message()
    assert "Epic sadface" in error

@pytest.mark.smoke
def test_login_locked_out_user(page, base_url, locked_out_credentials):
    """Smoke: verify that a locked-out user sees an error message"""
    login_page = LoginPage(page)
    login_page.navigate(f"https://{base_url}/")
    login_page.login(
        locked_out_credentials["username"],
        locked_out_credentials["password"]
    )
    error = login_page.get_error_message()
    assert "locked out" in error

tests/e2e/test_purchase_flow.py

# tests/e2e/test_purchase_flow.py
import pytest

@pytest.mark.e2e
@pytest.mark.slow
def test_purchase_flow_success(logged_in_page, cart_items, shipping_info):
    """E2E: test the full flow from login to order completion"""
    page = logged_in_page

    # Add items to cart
    page.click("[data-test='add-to-cart-sauce-labs-backpack']")
    page.click("[data-test='add-to-cart-sauce-labs-bike-light']")

    # Navigate to cart
    page.click(".shopping_cart_link")
    assert page.url.endswith("/cart.html")

    # Begin checkout
    page.click("[data-test='checkout']")
    page.fill("[data-test='firstName']", shipping_info["first_name"])
    page.fill("[data-test='lastName']", shipping_info["last_name"])
    page.fill("[data-test='postalCode']", shipping_info["postal_code"])
    page.click("[data-test='continue']")

    # Confirm and complete order
    page.click("[data-test='finish']")
    success_msg = page.locator(".complete-header").text_content()
    assert "Thank you" in success_msg

⑥ Controlling Test Execution with Marks

With marks in place, you can flexibly switch which tests to run depending on the phase of your CI/CD pipeline.

# Run only smoke tests (every PR/push)
pytest -m smoke

# Run smoke + regression (before merging to main)
pytest -m "smoke or regression"

# Run everything except E2E (for fast feedback)
pytest -m "not e2e"

# Run everything except slow tests
pytest -m "not slow"

# Run all tests (nightly schedule)
pytest

⑦ GitHub Actions Integration

Combining marks with GitHub Actions lets you automatically run different test sets depending on the pipeline phase.

# .github/workflows/playwright.yml (excerpt)

jobs:
  smoke:
    name: Smoke Tests (PR / push)
    runs-on: ubuntu-latest
    steps:
      # ... setup omitted ...
      - name: Run smoke tests
        run: pytest -m smoke

  regression:
    name: Regression Tests (after merge to main)
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      # ... setup omitted ...
      - name: Run regression tests
        run: pytest -m "smoke or regression"

  nightly:
    name: Nightly Full Test Suite
    runs-on: ubuntu-latest
    if: github.event_name == 'schedule'
    steps:
      # ... setup omitted ...
      - name: Run all tests
        run: pytest

⑧ Sample Execution Output

$ pytest -m smoke -v

========================= test session starts ==========================
platform linux -- Python 3.11.0, pytest-7.4.0
collected 8 items / 5 deselected / 3 selected

tests/smoke/test_login_smoke.py::test_login_success          PASSED  [ 33%]
tests/smoke/test_login_smoke.py::test_login_wrong_password   PASSED  [ 66%]
tests/smoke/test_login_smoke.py::test_login_locked_out_user  PASSED  [100%]

========================== 3 passed in 5.21s ===========================

FAQ

⚠️ 7 Common Pitfalls in Playwright + pytest Project Structure

Even with a solid structure in place, there are traps that are easy to fall into. Knowing them in advance saves you a lot of unnecessary debugging.

# ❌ Wrong
cd tests
pytest

# ✅ Correct
cd my_project    # the directory with pytest.ini
pytest

📋 Summary

You don’t need to aim for the perfect structure from day one. Start with the simple folder layout, then gradually expand toward the full version as your test suite grows — that’s the practical approach that works in the real world.