Coverage.py 使用详解：Python代码覆盖率测试完全指南

一、基础用法

1. 安装与基本命令

# 安装
pip install coverage

# 运行测试并收集覆盖率数据
coverage run -m pytest tests/

# 生成报告
coverage report -m

# 输出示例
Name                      Stmts   Miss  Cover   Missing
------------------------------------------------------
my_module.py                57      3    95%   24-26, 42
tests/test_module.py        23      0   100%
------------------------------------------------------
TOTAL                        80      3    96%

2. 常用命令行参数

二、高级配置

1. 配置文件.coveragerc

[run]
source = src
omit = 
    */tests/*
    */migrations/*
    */__init__.py
branch = True
parallel = True

[report]
exclude_lines =
    pragma: no cover
    def __repr__
    raise NotImplementedError
    if __name__ == .__main__.:
ignore_errors = True
fail_under = 80

[html]
directory = coverage_html
title = My Project Coverage

2. 分支覆盖率

# 启用分支覆盖率分析
coverage run --branch -m pytest

# 报告显示分支覆盖率
coverage report -m
# 输出新增BR列显示分支覆盖率
Name      Stmts   Miss Branch BrPart  Cover   Missing
----------------------------------------------------
module.py     10      2      2      1    75%   3-4, 3->5

三、报告生成与分析

1. 多种报告格式

# 控制台报告（默认）
coverage report

# HTML报告（交互式）
coverage html
open htmlcov/index.html

# XML报告（CI集成）
coverage xml

# JSON报告
coverage json

2. 动态排除代码块

def uncovered_function():  # pragma: no cover
    """这个函数不计入覆盖率统计"""
    pass

def partial_cover(x):
    if x < 0:  # pragma: no branch
        return "negative"
    return "positive"

四、API编程接口

1. 程序化控制覆盖率

import coverage

cov = coverage.Coverage(
    source=["src"],
    omit=["src/tests/*"],
    branch=True
)
cov.start()

# 运行被测代码
import my_module
my_module.main()

cov.stop()
cov.save()

# 生成报告
cov.report()
cov.html_report(directory='cov_html')

2. 合并多进程数据

# 主进程
cov = coverage.Coverage(data_file='.coverage.main')
cov.start()
# ...启动子进程...
cov.stop()
cov.save()

# 子进程
cov = coverage.Coverage(data_file='.coverage.child1')
cov.start()
# ...执行代码...
cov.stop()
cov.save()

# 合并
cov.combine(data_paths=['.coverage.main', '.coverage.child1'])
cov.report()

五、持续集成集成

1. GitHub Actions配置

name: Test with Coverage

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Set up Python
      uses: actions/setup-python@v2
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install pytest coverage
    - name: Test with coverage
      run: |
        coverage run -m pytest
        coverage report --fail-under=90
    - name: Upload coverage
      uses: codecov/codecov-action@v1

2. 与Codecov集成

# 安装上传工具
pip install codecov

# 本地生成并上传报告
coverage run -m pytest
coverage xml
codecov -f coverage.xml

六、高级技巧

1. 选择性覆盖

# 只统计特定代码段的覆盖率
cov = coverage.Coverage()
cov.start()

with cov.collect():
    # 只收集这个块内的覆盖率
    important_function()

cov.stop()

2. 上下文管理器

with coverage.Coverage() as cov:
    test_suite.run()
    cov.report()

七、常见问题解决

1. 缺失覆盖率数据

# 检查数据文件是否存在
ls -la .coverage

# 强制重新收集
coverage erase
coverage run -m pytest

2. 虚拟环境问题

# 确保在同一个Python环境中运行
which python
which coverage

# 使用模块方式运行
python -m coverage run -m pytest

八、最佳实践

1. 合理设置阈值：核心模块100%，工具脚本80%
2. 定期检查趋势：使用Codecov等工具监控覆盖率变化
3. 结合质量门禁：在CI中设置--fail-under
4. 关注关键路径：不要盲目追求100%覆盖率
5. 排除不需要的代码：合理使用omit和pragma: no cover

完整工作流示例

# 1. 配置
echo "[run]
source = src
omit = */tests/*
branch = True" > .coveragerc

# 2. 运行测试
coverage run -m pytest tests/ -v

# 3. 生成报告
coverage html --skip-covered
coverage report --show-missing

# 4. CI集成 (GitLab示例)
coverage xml
curl -s https://codecov.io/bash | bash

通过系统化使用Coverage.py，您可以：

• 精确掌握代码测试覆盖情况
• 发现未经测试的代码路径
• 提高测试代码的有效性
• 建立质量保障的量化指标