pytest-mpl 0.16.1

带有基线图像

要使用，您只需使用@pytest.mark.mpl_image_compare标记要比较图像的函数，并确保该函数返回一个 Matplotlib 图形（或任何具有 savefig方法的图形对象）：

import pytest
import matplotlib.pyplot as plt

@pytest.mark.mpl_image_compare
def test_succeeds():
    fig = plt.figure()
    ax = fig.add_subplot(1,1,1)
    ax.plot([1,2,3])
    return fig

要生成基线图像，请使用 --mpl-generate-path选项以及应放置生成图像的目录名称运行测试：

pytest --mpl-generate-path=baseline

如果该目录不存在，则会创建该目录。该目录将被解释为相对于您运行pytest的位置。一旦您对生成的图像感到满意，您应该将它们移动到一个相对于测试文件称为基线的子目录（此名称是可配置的，见下文）。您也可以直接在正确的目录中生成基线图像。

使用哈希库

您可以与 SHA-256 哈希的 JSON 库进行比较，而不是与基线图像进行比较。这样做的好处是不必将基线图像与测试一起检查到存储库中，或者从远程源下载它们。

可以使用 --mpl-generate-hash-library=path_to_file.json 生成哈希库。要使用的哈希库可以通过--mpl-hash-library=命令行参数指定，也可以通过@pytest.mark.mpl_image_compare装饰器的hash_library=关键字参数 指定。

生成哈希库时，测试也将照常针对--mpl-hash-library或关键字参数指定的现有哈希库运行。但是，生成基线图像总是会导致测试被跳过。

混合模式：哈希和图像

可以配置哈希和基线图像。在这种情况下，只有哈希比较才能确定测试结果。如果哈希比较失败，则测试将失败，但是将执行与基线图像的比较，以便可以看到实际差异。如果哈希比较通过，将跳过与基线图像的比较（除非始终配置结果）。

如果基线图像位于包含测试的存储库外部，并且可以通过 HTTP 访问，这将特别有用。在这种情况下，如果哈希匹配，则不会检索基线图像，从而节省时间和带宽。此外，它允许修改测试并更新哈希以反映更改，而无需修改外部图像。

运行测试

一旦使用基线图像、哈希库或两者进行比较编写测试，可以使用以下命令运行测试：

pytest --mpl

如果图像相同，测试将通过。如果省略 --mpl选项，测试将运行，但只会检查代码是否运行，而不检查输出图像。

生成测试摘要

通过指定--mpl-generate-summary=html CLI 参数，将生成一个 HTML 摘要页面，显示测试结果、日志条目和生成的结果图像。在（默认）图像比较模式下，还将显示基线图像、差异图像和 RMS（如果有）以及每个测试的容差。在哈希比较模式下，也会显示基线哈希和结果哈希。在混合模式下，所有这些都包括在内。

生成 HTML 摘要时，会自动应用--mpl-results-always选项（请参阅下面的部分）。因此，还将显示通过测试的图像。

与html一样，basic-html可以指定为不依赖 JavaScript 或外部资源的替代 HTML 摘要。 也可以保存一个json摘要。多个选项可以用逗号分隔。

宽容

图像比较的 RMS 容差（默认为 2）可以在mpl_image_compare装饰器中使用容差 参数指定：

@pytest.mark.mpl_image_compare(tolerance=20)
def test_image():
    ...

Savefig 选项

您可以使用 mpl_image_compare装饰器中的savefig_kwargs将关键字参数传递给savefig：

@pytest.mark.mpl_image_compare(savefig_kwargs={'dpi':300})
def test_image():
    ...

基线图像

基线目录（默认为基线）和绘图的文件名（默认为带有 .png后缀的测试名称）可以使用mpl_image_compare装饰器中的基线目录和 文件名参数进行自定义：

@pytest.mark.mpl_image_compare(baseline_dir='baseline_images',
                               filename='other_name.png')
def test_image():
    ...

上面装饰器中的基线目录将被解释为相对于测试文件。请注意，基线目录也可以是 URL（应以http://或https://开头并以斜杠结尾）。如果要指定镜像，请将baseline_dir设置为以逗号分隔的 URL 列表（URL 中的实际逗号应编码为%2C）。

最后，您还可以在运行测试时全局设置自定义基线目录，方法是运行pytest：

pytest --mpl --mpl-baseline-path=baseline_images

该目录将被解释为与运行 pytest 的位置相关。但是，如果还包括--mpl-baseline-relative选项，则该目录将被解释为相对于当前测试目录。此外，如果此选项和​​mpl_image_compare装饰器中的baseline_dir 选项都使用，则装饰器中的选项优先。

结果总是

默认情况下，只为失败的测试保存结果图像。将--mpl -results-always传递给 pytest 将强制保存所有测试的结果图像，即使是通过的测试。

在混合模式下，即使测试通过了哈希比较，也会与基线图像进行比较，并为所有测试保存基线图像和差异图像（如果图像比较失败）。此二次比较不会影响测试的成功状态。

此选项对于始终将结果图像与基线图像进行比较很有用，同时仅针对哈希库评估测试。如果您只在合并 PR 后更新基线图像，此选项意味着生成的摘要将始终显示 PR 如何影响基线图像，每个测试的成功状态（基于哈希库）也会显示在生成的摘要中. 此选项在生成 HTML 摘要时自动应用。

当--mpl-results-always选项处于活动状态并执行一些哈希比较测试时，包含所有结果哈希的哈希库也将保存到结果目录的根目录。文件名将按顺序从--mpl-generate-hash-library、 --mpl-hash-library或hash_library=中提取。

基本款

默认情况下，测试将使用 Matplotlib 的“经典”样式运行（忽略任何本地定义的 RC 参数）。这可以通过使用style参数覆盖：

@pytest.mark.mpl_image_compare(style='fivethirtyeight')
def test_image():
    ...

包版本依赖

不同版本的 Matplotlib 和 FreeType 可能会导致图像略有不同。在多个平台上或作为管道的一部分进行测试时，确保这些包的版本与用于生成用于比较的图像的版本相匹配非常重要。固定 Matplotlib 和 FreeType 的版本可能很有用，以避免测试失败的自动更新。

删除文本

如果您正在运行一个您对比较文本标签不感兴趣的测试，您可以使用装饰器的remove_text参数：

@pytest.mark.mpl_image_compare(remove_text=True)
def test_image():
    ...

这将使测试对例如 freetype 库中的更改不敏感。