pytest-image-snapshot

pytest图像快照管理和比较的插件。

功能

• 图像比较：自动比较测试生成的图像与预先存储的快照，识别任何视觉差异。
• 快照创建：如果不存在参考快照，插件将在测试运行期间创建它，使初始设置轻松。
• 详细模式显示：在测试运行时使用-v标志，能够在出现不匹配时显示差异图像，以提供快速视觉反馈。
• 快照更新选项：包括--image-snapshot-update标志，用于更新现有快照或创建新的快照，以适应项目中的视觉变化。
• 阈值比较：使用threshold参数进行增强的图像比较，与pixelmatch库结合，实现抗锯齿像素检测。

需求

• Pillow
• pixelmatch（可选）

安装

您可以通过pip从PyPI安装"pytest-image-snapshot"。

$ pip install pytest-image-snapshot

可选依赖

pytest-image-snapshot通过可选的pixelmatch包提供增强功能，适用于高级图像比较场景。要安装包含此可选功能的pytest-image-snapshot，请使用以下命令

$ pip install pytest-image-snapshot[pixelmatch]

Pytest Image Snapshot 使用示例

image_snapshot 修复件是为 pytest 中的视觉回归测试设计的。它比较测试中生成的图像与存储的参考图像（快照）。如果快照不存在，它将自动创建。这使得修复件非常适合创建初始快照和在视觉测试中进行持续比较。

用法

以下是利用 image_snapshot 修复件的示例

from PIL import Image

def test_image(image_snapshot):
    # Create a new white image of 100x100 pixels
    image = Image.new('RGB', (100, 100), 'white')
    # Compare it to the snapshot stored in test_snapshots/test.png
    # If test_snapshots/test.png does not exist, it will be created
    image_snapshot(image, "test_snapshots/test.png")

image_snapshot 中的可选 threshold 参数

image_snapshot 函数包含一个可选的 threshold 参数。当设置时，如果图像与快照不匹配，将使用 pixelmatch 库进行具有抗锯齿像素检测的详细比较。

• 默认阈值：如果将 threshold 设置为 True，将使用默认阈值值。
• 自定义阈值：如果 threshold 是一个数值，则将其传递给 pixelmatch 库以指定图像比较的容错级别。

image_snapshot(image, "test_snapshots/test.png", True)
image_snapshot(image, "test_snapshots/test.png", 0.2)

⚠️ 警告

image_snapshot 修复件不会自动创建用于存储图像快照的目录。在运行测试之前，请确保在项目结构中创建了必要的目录（例如，test_snapshots/）。

详细模式（-v 或 --verbose）

详细模式增强了 image_snapshot 测试的输出细节

• -v：显示存在不匹配时的 'diff' 图像。
• -vv：显示所有三个图像 - 'diff'、'original' 和 'current'，以进行全面比较。

此功能有助于在测试失败时快速识别和分析视觉差异。

保存实际图像和 diff 图像（--image-snapshot-save-diff）

使用 --image-snapshot-save-diff 标志在存在不匹配时保存实际图像和 diff 图像。这在 CI 环境中进行调试特别有用。

pytest --image-snapshot-save-diff

更新快照（--image-snapshot-update）

使用 --image-snapshot-update 标志更新或创建新的参考快照。这对于将故意引入的视觉更改纳入测试，确保快照始终反映当前预期状态非常有用。

pytest --image-snapshot-update

当快照缺失时失败（--image-snapshot-fail-if-missing）

使用 --image-snapshot-fail-if-missing 标志在快照缺失时失败测试。这在 CI 检查中特别有用，以确保所有快照都存在且是最新的。

pytest --image-snapshot-fail-if-missing

示例

使用 playwright 对 Django 应用程序主页进行视觉回归测试

from PIL import Image
from io import BytesIO

def test_homepage(live_server, page: Page, image_snapshot):
    page.goto(f"{live_server}")
    # convert screenshot to image
    screenshot = Image.open(BytesIO(page.screenshot()))
    image_snapshot(screenshot, "test_snapshots/homepage.png", threshold=True)

贡献

欢迎贡献。可以使用 tox 运行测试，请在提交拉取请求之前确保覆盖率至少保持不变。

许可证

在 MIT 许可证的条款下分发，"pytest-image-snapshot" 是免费和开源软件

问题

如果您遇到任何问题，请与详细描述一起提交问题。

此 pytest 插件是用 Cookiecutter 以及 @hackebrot 的 cookiecutter-pytest-plugin 模板生成的。