CI/CD / 系统课时
生成测试覆盖率
生成测试覆盖率
覆盖率报告用于回答“哪些代码被测试执行过”,适合发现明显测试空白并辅助质量门禁,但它不能证明断言正确或业务场景完整。本课会生成终端、XML 和 HTML 报告,并设置一个不过度依赖覆盖率数字的门禁。
学习目标
- 生成语句覆盖率和分支覆盖率报告
- 保存 XML、HTML 等覆盖率产物供流水线和开发者使用
- 正确设置覆盖率阈值,并理解覆盖率指标不能替代测试质量
生成可保存的覆盖率报告
下面创建一个最小 Python 项目,使用 pytest-cov 同时计算语句覆盖率和分支覆盖率。终端报告用于流水线日志,XML 适合交给质量平台解析,HTML 适合人工查看未覆盖行。
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预期输出
... [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() 保证门禁失败时仍保留诊断产物。
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%,而是把报告当作“测试盲区地图”。当阈值稳定、报告可追溯,并且团队仍关注断言质量和关键业务分支时,覆盖率才能成为有效的持续集成信号。