pytest-mpl 项目使用教程

1. 项目的目录结构及介绍

pytest-mpl 项目是一个用于 Matplotlib 图像比较的 pytest 插件。以下是项目的目录结构及文件介绍：

pytest-mpl/
├── .github/                # GitHub 工作流和配置文件
├── docs/                   # 文档源文件
├── pytest_mpl/             # pytest-mpl 插件的核心代码
│   ├── __init__.py
│   ├── plugins.py
│   └── tolerance.py
├── tests/                  # 测试用例和测试数据
│   ├── __init__.py
│   ├── test compare.py
│   ├── test generate.py
│   └── ...                # 其他测试文件
├── .gitignore              # Git 忽略文件
├── .pre-commit-config.yaml # pre-commit 配置文件
├── .readthedocs.yaml       # Read the Docs 配置文件
├── CHANGES.md              # 更改记录
├── LICENSE                 # 许可证文件
├── MANIFEST.in             # 打包包含文件
├── README.rst              # 项目说明文件
├── RELEASING.md            # 发布指南
├── pyproject.toml          # 项目配置文件
├── setup.cfg               # 设置配置文件
├── setup.py                # 设置文件
└── tox.ini                 # tox 测试配置文件

• .github/: 包含 GitHub Actions 工作流文件，用于自动化测试、构建和发布等。
• docs/: 包含项目的文档源文件，通常使用 Sphinx 或 MkDocs 等工具生成 HTML 文档。
• pytest_mpl/: 包含 pytest-mpl 插件的核心代码和模块。
• tests/: 包含用于验证 pytest-mpl 功能的测试用例和测试数据。
• .gitignore: 指定 Git 忽略的文件和目录。
• .pre-commit-config.yaml: 配置 pre-commit 工具，用于在提交代码前执行一些格式化任务。
• .readthedocs.yaml: 配置 Read the Docs，用于在线托管文档。
• CHANGES.md: 记录了项目的更改历史。
• LICENSE: 包含项目的许可证信息。
• MANIFEST.in: 指定打包时包含的文件和目录。
• README.rst: 项目的主要说明文件，包含了项目的介绍和基本使用方法。
• RELEASING.md: 包含了发布新版本项目的指南。
• pyproject.toml: 包含了项目的元数据和构建系统配置。
• setup.cfg: 包含了安装、打包和测试等配置。
• setup.py: 用于安装和打包项目的脚本。
• tox.ini: 配置 tox 工具，用于自动化测试。

2. 项目的启动文件介绍

pytest-mpl 插件的启动主要是通过在测试文件中使用 pytest 命令来触发的。以下是启动项目的基本步骤：

1. 安装 pytest-mpl 插件：

   pip install pytest-mpl
   

2. 编写包含图像比较测试的测试函数，并使用 @pytest.mark.mpl_image_compare 装饰器标记这些测试函数。

3. 运行测试并生成参考图像：

   pytest --mpl-generate-path=baseline
   

4. 运行测试并比较生成的图像与参考图像：

   pytest --mpl
   

5. 如果需要，可以生成图像比较结果的 HTML 汇总：

   pytest --mpl-generate-summary=html
   

3. 项目的配置文件介绍

pytest-mpl 插件的配置主要通过以下文件进行：

• .pre-commit-config.yaml: 用于配置 pre-commit 工具，它会在提交代码前自动执行指定的钩子，例如代码格式化、静态分析等。

• .readthedocs.yaml: 用于配置 Read the Docs 服务，它允许你将项目的文档托管在 Read the Docs 上，并自动构建和发布文档。

• pyproject.toml: 用于定义项目的元数据和构建系统配置，它也被用来配置构建工具如 pip 和 build。

• setup.cfg: 用于配置打包和安装过程，它包括项目信息和命令行选项。

• tox.ini: 用于配置 tox 测试工具，它可以帮助你在多个 Python 环境中运行测试。

通过修改这些配置文件，你可以根据项目的需要和开发流程来自定义 pytest-mpl 插件的行为。