======== 概览

.. start-badges

.. list-table:: :stub-columns: 1

• • 文档
    • |docs|
    • • 测试
      • |github-actions|
    • • 包
      • |version| |conda-forge| |wheel| |supported-versions| |supported-implementations| |commits-since|

.. |docs| image:: https://readthedocs.org/projects/pytest-cov/badge/?style=flat :target: https://readthedocs.org/projects/pytest-cov/ :alt: 文档状态

.. |github-actions| image:: https://github.com/pytest-dev/pytest-cov/actions/workflows/test.yml/badge.svg :alt: GitHub Actions 状态 :target: https://github.com/pytest-dev/pytest-cov/actions

.. |version| image:: https://img.shields.io/pypi/v/pytest-cov.svg :alt: PyPI 包最新版本 :target: https://pypi.org/project/pytest-cov

.. |conda-forge| image:: https://img.shields.io/conda/vn/conda-forge/pytest-cov.svg :target: https://anaconda.org/conda-forge/pytest-cov .. |wheel| image:: https://img.shields.io/pypi/wheel/pytest-cov.svg :alt: PyPI Wheel :target: https://pypi.org/project/pytest-cov

.. |supported-versions| image:: https://img.shields.io/pypi/pyversions/pytest-cov.svg :alt: 支持的 Python 版本 :target: https://pypi.org/project/pytest-cov

.. |supported-implementations| image:: https://img.shields.io/pypi/implementation/pytest-cov.svg :alt: 支持的 Python 实现 :target: https://pypi.org/project/pytest-cov

.. |commits-since| image:: https://img.shields.io/github/commits-since/pytest-dev/pytest-cov/v5.0.0.svg :alt: 自最新版本后的提交 :target: https://github.com/pytest-dev/pytest-cov/compare/v5.0.0...master

.. end-badges

本插件用于生成覆盖率报告。与直接使用 coverage run 相比，它提供了以下增强功能：

• 子进程支持：无需额外配置即可覆盖子进程或分叉执行的代码。
• Xdist 支持：在使用 pytest-xdist 所有功能的同时仍能获取覆盖率数据。
• 一致的 pytest 行为。若运行 coverage run -m pytest，sys.path 会略有不同（当前工作目录会被包含，而直接运行 pytest 时不会）。

coverage 包提供的所有功能均可通过 pytest-cov 的命令行选项或 coverage 的配置文件使用。

• 开源协议：MIT

安装

使用 pip 安装：::

pip install pytest-cov

如需分布式测试支持，请安装 pytest-xdist：::

pip install pytest-xdist

从旧版 pytest-cov 升级

pytest-cov 2.0 采用了新的 .pth 文件（pytest-cov.pth）。建议手动删除旧版遗留的 init_cov_core.pth，该文件不会自动移除。

卸载

使用 pip 卸载：::

pip uninstall pytest-cov

某些情况下可能会残留 .pth 文件在 site-packages 目录中：

• pytest-cov 2.0 在非 wheel 安装时（如 easy_install、setup.py install 等）可能遗留 pytest-cov.pth。
• pytest-cov 1.8 或更早版本 会遗留 init_cov_core.pth。

使用说明

::

pytest --cov=myproj tests/

将生成如下报告：::

-------------------- coverage: ... --------------------- 名称 语句数 未覆盖 覆盖率 ---------------------------------------- myproj/init 2 0 100% myproj/myproj 257 13 94% myproj/feature4286 94 7 92% ---------------------------------------- 总计 353 20 94%

文档

https://pytest-cov.readthedocs.io/en/latest/

覆盖率数据文件

测试开始时数据文件会被清空，确保每次测试运行都有干净的数据。如需合并多次测试运行的覆盖率数据，可使用 --cov-append 选项将本次数据追加到之前的结果中。

测试结束后数据文件会被保留，以便使用常规 coverage 工具进行分析。

限制说明

分布式测试环境下，所有工作节点必须安装 pytest-cov 包。因为需要通过 setuptools 注册插件才能在节点上激活。

子进程覆盖率测量要求主进程的环境变量能传递到子进程。子进程使用的 Python 必须安装 pytest-cov，且需正常初始化站点环境以检测环境变量并启动覆盖率统计。

致谢

虽然本插件是全新构建，但受到了以下项目的影响：

• pytest-coverage（Ross Lawley, James Mills, Holger Krekel）
• nose-cover（Jason Pellerin）

特别感谢：

• Ned Batchelder 开发的 coverage 工具及其并行运行结果合并功能
• Holger Krekel 提供的 pytest 分布式测试支持
• Jason Pellerin 开发的 nose
• Michael Foord 贡献的 unittest2

当然，这些工具的背后还有许多其他贡献者。