CI/CD / 系统课时

生成测试覆盖率

生成测试覆盖率

覆盖率报告用于回答“哪些代码被测试执行过”,适合发现明显测试空白并辅助质量门禁,但它不能证明断言正确或业务场景完整。本课会生成终端、XML 和 HTML 报告,并设置一个不过度依赖覆盖率数字的门禁。

学习目标

  • 生成语句覆盖率和分支覆盖率报告
  • 保存 XML、HTML 等覆盖率产物供流水线和开发者使用
  • 正确设置覆盖率阈值,并理解覆盖率指标不能替代测试质量

生成可保存的覆盖率报告

下面创建一个最小 Python 项目,使用 pytest-cov 同时计算语句覆盖率和分支覆盖率。终端报告用于流水线日志,XML 适合交给质量平台解析,HTML 适合人工查看未覆盖行。

bash
set -euo pipefail
python -m venv .venv
. .venv/bin/activate
python -m pip install -q pytest pytest-cov
mkdir -p tests reports
cat > app.py <<'PY'
def classify(number):
    if number < 0:
        return "negative"
    if number == 0:
        return "zero"
    return "positive"
PY
cat > tests/test_app.py <<'PY'
from app import classify

def test_negative():
    assert classify(-1) == "negative"

def test_zero():
    assert classify(0) == "zero"

def test_positive():
    assert classify(1) == "positive"
PY
python -m pytest -q \
  --cov=app \
  --cov-branch \
  --cov-report=term-missing \
  --cov-report=xml:reports/coverage.xml \
  --cov-report=html:reports/htmlcov \
  --cov-fail-under=80

预期输出

text
...                                                                      [100%]
Name     Stmts   Miss Branch BrPart  Cover   Missing
----------------------------------------------------
app.py       6      0      4      0   100%
----------------------------------------------------
TOTAL        6      0      4      0   100%
3 passed in <TIME>s

实际耗时会替换 <TIME>。命令成功后还会生成 reports/coverage.xml 和 reports/htmlcov/index.html;不同 coverage.py 版本的表格间距可能略有差异,但覆盖率和文件路径应与配置一致。

把覆盖率阈值接入门禁

--cov-fail-under=80 表示总覆盖率低于 80% 时测试命令返回非零退出码,因此 CI 会失败。阈值应作为最低保护线,而不是团队追求的唯一目标;在已有项目中,先记录当前基线,再逐步提高,通常比一次性设置过高阈值更稳妥。

如果删除上例中的 test_zero,再次运行同一命令时会出现未覆盖分支。只要总覆盖率仍高于阈值,流水线可以继续通过;若低于阈值,命令会失败。由此可见,阈值控制的是一个汇总指标,不会自动判断“缺失的恰好是不是关键业务路径”。

在流水线中保存覆盖率构件

覆盖率文件不应只留在某次 runner 的临时磁盘。下面的 GitHub Actions 配置在测试完成后上传 XML 和 HTML 报告,并使用 if: always() 保证门禁失败时仍保留诊断产物。

yaml
name: coverage

on:
  push:
  pull_request:

jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: |
          python -m pip install pytest pytest-cov
          mkdir -p reports
          python -m pytest -q --cov=. --cov-branch \
            --cov-report=xml:reports/coverage.xml \
            --cov-report=html:reports/htmlcov \
            --cov-fail-under=80
      - name: Upload coverage reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: coverage-reports
          path: |
            reports/coverage.xml
            reports/htmlcov

这段配置的验证方法是检查作业日志中的覆盖率结果,并确认构件 coverage-reports 同时包含 XML 文件和 HTML 目录。若测试或阈值门禁失败,作业状态仍应失败,上传步骤不能把失败覆盖成成功。

正确理解覆盖率的边界

指标或做法 能说明什么 不能说明什么
语句覆盖率 某行可执行语句是否运行过 断言是否验证了正确结果
分支覆盖率 条件的不同分支是否执行过 输入边界是否完整、业务风险是否覆盖
全局阈值 防止整体覆盖率明显倒退 新增关键代码是否都有针对性测试

高覆盖率也可能来自只有执行、没有有效断言的测试;低风险生成代码则可能拉低数字但不值得投入同等测试成本。质量门禁更适合组合使用:覆盖率防止明显空白,测试结果保证行为断言,代码评审检查场景设计,必要时再针对新增或高风险代码设置更严格要求。

覆盖率最有价值的用法不是追求 100%,而是把报告当作“测试盲区地图”。当阈值稳定、报告可追溯,并且团队仍关注断言质量和关键业务分支时,覆盖率才能成为有效的持续集成信号。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

生成测试覆盖率

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通