pytest-playwright-visual

2.1.2 verified Fri May 01 auth: no python

A pytest fixture for visual testing with Playwright. Version 2.1.2 (released 2025). Active development with monthly releases.

pip install pytest-playwright-visual

Common errors

error ModuleNotFoundError: No module named 'pytest_playwright_visual' ↓

cause Older import pattern from v1.x was 'from pytest_playwright_visual import ...'. v2.0 changed the package structure.

fix

Use the pytest plugin registration; no direct import needed. Ensure you have installed the package.

error Failed: Visual diff mismatch (threshold exceeded) ↓

cause The visual comparison threshold is set too low or the screenshot differs significantly.

fix

Adjust threshold parameter in the fixture or increase it: threshold=0.1 (default is 0.0). See docs for details.

Warnings

breaking v2.0 restructured snapshot folder from flat to hierarchical: snapshots/<file_name>/<test_name>/<test_name>[browser][os].png. All existing snapshots must be moved/recreated. ↓

fix Re-run tests with --update-snapshots after removing old snapshots, or manually restructure folders.

breaking v2.0 fails on --update-snapshots to force users to manually review images. Tests will fail if snapshots are updated without manual review. ↓

fix Use --update-snapshots with caution; expect test failure to prompt manual review. Or use v1.x if automatic update is needed.

gotcha Snapshot name argument ('snapshot_name') is optional in v2.0+. Default name is auto-generated as test_name[browser][os].png. If you explicitly pass a name, it may conflict with the auto-generated one. ↓

fix Either omit snapshot_name to use default, or ensure unique names.

Imports

page
```
from pytest_playwright_visual.plugin import VisualPlugin
```
The plugin is registered as a pytest plugin; no direct import needed for the fixture. Fixture name is 'page' from pytest-playwright.

Quickstart

Basic visual test using the page fixture (provided by pytest-playwright). First run creates snapshots; subsequent runs compare.

import pytest
from playwright.sync_api import Page

def test_visual(page: Page):
    page.goto('https://example.com')
    page.screenshot(path='screenshot.png')  # snapshot auto-created on first run