pytest-cov使用笔记

pytest-cov 是 pytest 测试框架的插件，用于测量 Python 代码覆盖率 ，能帮开发者了解代码被测试覆盖情况，辅助提升测试质量与完整性，支持语句覆盖、分支覆盖等标准，可生成文本、HTML、XML 等多种类型报告，适配单元测试、持续集成、代码审查等场景。

安装

pip install pytest-cov

基础使用流程

项目结构示例

假设有 Python 项目，结构如下（以简单模块 myproj 为例 ）：

myproj/
├── myproj.py  
├── feature.py  
└── tests/  
    └── test_myproj.py  

核心命令格式

运行测试并生成覆盖率报告的基础命令：

pytest --cov=被测模块名 测试路径

1. 最简场景：单模块基础覆盖

若测试文件在 tests 目录，想测 myproj 模块，执行：

pytest --cov=myproj tests/

终端会输出覆盖率统计：

Name              Stmts  Miss  Cover
-------------------------------------
myproj/myproj.py     25     7    72%
myproj/feature.py    42     8    81%
TOTAL                69    15    78%

• • Stmts：代码总语句数
• • Miss：未被测试覆盖的语句数
• • Cover：覆盖率百分比

2. 生成 HTML 报告（可视化详情）

添加 --cov-report=html 参数，生成更直观的 HTML 报告：

pytest --cov=myproj --cov-report=html tests/

执行后，项目目录下会生成 htmlcov 文件夹，打开 htmlcov/index.html，可通过网页可视化查看：绿色为已覆盖代码行，红色为未覆盖，黄色为部分覆盖 。

3. 显示未覆盖代码行（终端细化）

用 --cov-report=term-missing，终端会额外列出未覆盖的具体行号：

pytest --cov=myproj --cov-report=term-missing tests/

输出示例（含 Missing 列 ）：

Name              Stmts  Miss  Cover  Missing
----------------------------------------------
myproj/myproj.py     25     7    72%   10, 15-17, 22
myproj/feature.py    42     8    81%   5, 20-23
TOTAL                69    15    78%

进阶用法

多模块 / 子包覆盖

若项目有多个子包（如 myproj.subpkg1、myproj.subpkg2 ），可：

• 方式 1：多次指定--cov

pytest --cov=myproj.subpkg1 --cov=myproj.subpkg2 tests/

• 方式 2：逗号分隔多包

pytest --cov=myproj.subpkg1,myproj.subpkg2 tests/

忽略文件 / 目录

用 --cov-ignore 跳过无需覆盖的代码：

• 忽略单个文件（如myproj/utils.py）：

pytest --cov=myproj --cov-ignore=myproj/utils.py tests/

• 忽略整个目录（如myproj/tests）：

pytest --cov=myproj --cov-ignore=myproj/tests/ tests/

合并多次测试覆盖率

持续集成等场景需合并多轮测试数据，用 --cov-append：

# 第一轮测试
pytest --cov=myproj --cov-append test_file1.py  
# 第二轮测试（数据合并）
pytest --cov=myproj --cov-append test_file2.py  
# 最终生成合并后的报告
pytest --cov=myproj --cov-report=html  

pytest.ini参数

可在项目根目录创建 pytest.ini，写入默认参数：

[pytest]
addopts = --cov=myproj --cov-report=term-missing  

之后直接运行 pytest，会自动加载这些 --cov 相关配置 。

（五）标记无需覆盖的代码段

对 if __name__ == '__main__' 等无需测试的代码，加注释 # pragma: no cover 跳过：

def main():
    print("程序入口")

if __name__ == "__main__":  # pragma: no cover
    main()

备注

• • 覆盖率≠测试质量：高覆盖率不代表逻辑测全，复杂分支、异常场景仍需重点验证；低覆盖率则需补测试。
• • 环境隔离：多项目 / 虚拟环境时，用 venv 或 conda 建独立环境，避免依赖冲突导致覆盖率异常。
• • 报告管理：HTML 报告目录（htmlcov ）勿上传 Git 仓库，仅作本地 / CI 临时查看；集成 Codecov/Coveralls 等平台时，注意路径、依赖与 CI 环境适配。

合理用 pytest-cov 可精准发现测试盲区，结合高质量用例，能有效提升代码可靠性～

https://github.com/pytest-dev/pytest-cov

#Python #PythonCov