Python 代码覆盖率完全指南 - 衡量测试质量黄金标准

# 安装 coverage
pip install coverage

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

# 查看覆盖率报告（文本格式）
coverage report

# 查看详细报告（包含未覆盖的行号）
coverage report -m

# 安装 pytest-cov
pip install pytest-cov

# 运行测试并显示覆盖率
pytest --cov=my_project

# 指定覆盖率的源代码目录
pytest --cov=my_project --cov=src/

# 显示详细覆盖率（包含缺失行号）
pytest --cov=my_project --cov-report=term-missing

# 生成 HTML 报告
pytest --cov=my_project --cov-report=html

# 生成 XML 报告（用于 CI/CD 集成）
pytest --cov=my_project --cov-report=xml

# calculator.py - 被测试的代码
class Calculator:
    def add(self, a, b):
        return a + b

    def subtract(self, a, b):
        return a - b

    def divide(self, a, b):
        if b == 0:
            raise ValueError("除数不能为0")
        return a / b

    def power(self, a, b):
        """计算幂"""
        if b < 0:
            return 1 / (a ** abs(b))
        return a ** b

# test_calculator.py - 测试代码
import pytest
from calculator import Calculator

class TestCalculator:
    def setup_method(self):
        self.calc = Calculator()

    def test_add(self):
        assert self.calc.add(2, 3) == 5

    def test_subtract(self):
        assert self.calc.subtract(5, 3) == 2

    def test_divide(self):
        assert self.calc.divide(10, 2) == 5

    def test_divide_by_zero(self):
        with pytest.raises(ValueError):
            self.calc.divide(1, 0)

# 演示不同覆盖率类型的示例代码
def categorize_score(score):
    """根据分数返回等级"""
    if score >= 90:        # 分支1
        return "A"
    elif score >= 80:      # 分支2
        return "B"
    elif score >= 70:      # 分支3
        return "C"
    elif score >= 60:      # 分支4
        return "D"
    else:                  # 分支5
        return "F"

# 如果只测试了 categorize_score(95)：
# - 行覆盖率: 约 17% (只执行了第一行 return)
# - 分支覆盖率: 20% (5个分支只覆盖了1个)
# - 函数覆盖率: 100% (函数被调用了)

# 需要测试所有分支才能达到高覆盖率：
# categorize_score(95), categorize_score(85),
# categorize_score(75), categorize_score(65), categorize_score(50)

# 简洁报告
$ pytest --cov=calculator --cov-report=term

Name              Stmts   Miss  Cover
-------------------------------------
calculator.py        10      2    80%
-------------------------------------
TOTAL                10      2    80%

# 详细报告（显示缺失的行号）
$ pytest --cov=calculator --cov-report=term-missing

Name              Stmts   Miss  Cover   Missing
-----------------------------------------------
calculator.py        10      2    80%   15, 18
-----------------------------------------------
TOTAL                10      2    80%

# 生成 HTML 报告
pytest --cov=my_project --cov-report=html

# 报告生成在 htmlcov/ 目录下
# 用浏览器打开 htmlcov/index.html 查看

# HTML 报告功能：
# - 每行代码的执行状态（绿色=已覆盖，红色=未覆盖）
# - 点击文件名查看详细代码覆盖情况
# - 分支覆盖率的可视化标记

# 同时输出多种格式
pytest --cov=my_project \
    --cov-report=term-missing \
    --cov-report=html \
    --cov-report=xml \
    --cov-report=json

# 各格式用途：
# term-missing: 终端快速查看
# html: 本地可视化浏览
# xml:  CI/CD 集成（如 Jenkins、Codecov）
# json:  程序化处理

# .coveragerc 或 pyproject.toml
[tool.coverage.run]
source = ["my_project"]
omit = [
    "*/tests/*",
    "*/migrations/*",
    "*/__init__.py",
    "*/manage.py",
]

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "def __repr__",
    "if self.debug:",
    "if __name__ == .__main__.:",
    "raise NotImplementedError",
    "pass",
]
show_missing = true
fail_under = 80  # 覆盖率低于80%时失败

[tool.coverage.html]
directory = "htmlcov"

# 在代码中使用注释排除
def debug_only_function():
    # pragma: no cover
    """这个函数只在调试时使用，不纳入覆盖率统计"""
    print("debug info")

class MyClass:
    def __repr__(self):
        # pragma: no cover
        return f"MyClass({self.value})"

# 运行单元测试
coverage run --source=my_project -m pytest tests/unit/

# 运行集成测试
coverage run --source=my_project -m pytest tests/integration/ --append

# 合并并生成报告
coverage report -m
coverage html