pytest-playwright-visual

What it is and what it does

pytest-playwright-visual is a pytest plugin that automates visual regression testing for web applications. It extends pytest-playwright with an `assert_snapshot` fixture that captures screenshots during test runs and compares them pixel-by-pixel using the pixelmatch algorithm. On first run, snapshots are created; on subsequent runs, actual screenshots are compared against stored baselines with a configurable threshold (default 0.1). When mismatches occur, the plugin generates side-by-side diff images in a `snapshot_tests_failures` folder for manual review.

The plugin manages snapshot organization automatically, storing images in a structured folder hierarchy keyed by test name, browser, and OS. It requires explicit user review before accepting snapshot updates via the `--update-snapshots` flag, preventing accidental regressions from being silently committed. Dependencies are minimal: pytest-playwright for browser automation, Pillow for image handling, and pixelmatch for the comparison algorithm.

Use it for:

• Detect unintended visual changes in UI components across browser and OS combinations during CI/CD.
• Establish visual baselines for new features and track pixel-level changes in design systems.
• Catch CSS or layout regressions that unit tests alone would miss, especially in responsive layouts.
• Review and approve visual changes before merging pull requests with generated diff images.
• Maintain visual consistency across browser versions by storing per-browser snapshots.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A pytest plugin that captures and compares visual snapshots of web pages rendered with Playwright, using pixel-level image matching to detect visual regressions.

Yes, if you need visual regression testing for Playwright-based tests and can tolerate aging maintenance. The plugin is lightweight, has no known vulnerabilities, and solves a real problem—catching visual regressions that functional tests miss. However, verify compatibility with your current Playwright version before adopting, and monitor the repository for updates or consider alternatives if active maintenance becomes critical for your workflow.

Install

pytest-playwright-visual on PyPI

pip install pytest-playwright-visual

uv add pytest-playwright-visual

poetry add pytest-playwright-visual

Installing pytest-playwright-visual

Before you install

Low install friction with a pure-Python wheel distribution. Maintenance is aging—last release was in April 2022 with no updates since, though the repository remains active with a recent commit in April 2025.

License in practice

Licensed under Apache 2.0 (permissive), allowing free use, modification, and distribution with minimal restrictions.

Quickstart

pip install pytest-playwright-visual

# In your test file:
from pytest_playwright.sync_api import Page

def test_myapp(page: Page, assert_snapshot):
    page.goto("https://example.com")
    assert_snapshot(page.screenshot())

Requires Playwright and a compatible browser to be installed; pytest-playwright must be set up first.

Verify before relying

• Whether the package works reliably with modern Playwright versions given the last release was in 2022.
• Performance characteristics when comparing large numbers of snapshots or high-resolution screenshots.
• Community activity and whether issues are being actively triaged despite the aging maintenance status.

Package facts

Evidence: pytest_playwright_visual-2.1.2-py3-none-any.whl

Tags

More Testing packages

Further reading