---
id: pytest-playwright-visual
version: "2.1.2"
license: unclear
license_treatment: permissive
maintenance: aging
---

# pytest-playwright-visual — A pytest fixture for visual testing with Playwright

License: permissive · Maintenance: aging · Downloads: 109.3K/mo

## 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 above — 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

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

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 109.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

visual regression testing pytest, screenshot comparison playwright, pixel-level image diffing, visual snapshot testing, web ui visual testing, playwright screenshot assertions, visual-testing, regression-detection, playwright

[View on SkillFed](https://skillfed.io/packages/pytest-playwright-visual) · [View on PyPI](https://pypi.org/project/pytest-playwright-visual/)