pytest-playwright

0.7.2 · active · verified Thu Apr 09

pytest-playwright is a Pytest plugin that provides robust fixtures for Playwright, enabling efficient end-to-end web testing in Python. It automatically manages browser instances, contexts, and pages, integrating seamlessly with the pytest testing framework. As of version 0.7.2, it supports Playwright Python 1.39.0 and higher, with new versions typically released in sync with Playwright's own update cadence.

Warnings

gotcha Playwright requires browser binaries to be installed separately. Tests will fail with 'Playwright was not installed. Please run `playwright install`' if browsers are missing.
Fix: After installing `pytest-playwright`, run `playwright install` in your terminal to download browser binaries.
gotcha By default, `page`, `browser`, and `context` fixtures are created and torn down for *each* test function. While ensuring isolation, this can be slow for large test suites.
Fix: To improve performance, use pytest command-line options like `--browser-context-scope=session` or `--browser-scope=session` to share browser resources across tests. For custom fixtures, use `pytest.fixture(scope="session")`.
gotcha Playwright runs browsers in headless mode by default (no visible UI). This can make debugging visual issues difficult.
Fix: Run tests with `--headless=false` (e.g., `pytest --headless=false`) to launch browsers with a visible UI during execution. For more fine-grained control, use the `browser_args` fixture.
gotcha pytest-playwright provides synchronous Playwright API fixtures (e.g., `page`, `browser`) by default. If your tests require `async`/`await` patterns, you must explicitly use the asynchronous fixtures (e.g., `apage`, `abrowser`).
Fix: For asynchronous tests, define your test function as `async def test_my_async(apage):` and use `await apage.goto(...)`.
breaking pytest-playwright has strict version compatibility requirements with the `playwright` library. Installing incompatible versions can lead to runtime errors or unexpected behavior due to API mismatches.
Fix: Always check `pytest-playwright`'s `install_requires` for the compatible `playwright` version range (e.g., `playwright>=1.39.0`) and ensure both packages are upgraded together.

Install

pip install pytest-playwright Install pytest-playwright
playwright install Install browser binaries (required)

Imports

page
```
def test_example(page):
```
pytest-playwright provides fixtures (like 'page') automatically; they are not imported directly from the package.
Page (for type hinting)
```
from playwright.sync_api import Page
```
Used for type hinting the 'page' fixture, not to instantiate it.

Quickstart

This quickstart demonstrates a basic web test using the `page` fixture provided by pytest-playwright. It navigates to Google, asserts the title, and takes a screenshot.

import pytest

def test_example_is_working(page):
    page.goto("https://www.google.com")
    assert "Google" in page.title()
    page.screenshot(path="screenshot.png")

# To run this test file:
# 1. Save as e.g., `test_my_app.py`
# 2. Ensure browsers are installed: `playwright install`
# 3. Run: `pytest test_my_app.py`

view raw JSON →