必须用 pytest-cov 配合 --cov-report=xml 输出，因 gitlab/jenkins 仅解析符合 cobertura schema 的 coverage.xml 结构化数据，不识别控制台文本报告；--cov=src 必须显式指定源码路径避免扫描 tests/、venv/ 导致覆盖率虚高或归零；ci 中还需配置 artifacts 保留 coverage.xml 并启用 --cov-branch 才能获取真实分支覆盖率。
必须用 pytest-cov 配合 --cov-report=xml 输出，其他格式 GitLab/Jenkins 无法自动解析覆盖率数值。
为什么 coverage report 在 CI 里没用？
CI 系统（如 GitLab、Jenkins）不读控制台输出的文本报告，它们只认结构化数据。你运行 coverage report -m 或 coverage html，结果只会留在日志里，无法触发覆盖率趋势图、MR 中的 badge、或阈值检查。
- GitLab 的
coverage字段依赖正则从 stdout 提取百分比，但该方式不稳定——只要测试命令输出带数字的行（比如日志、debug print），就可能误匹配 - Jenkins 的 Cobertura 插件、GitLab 原生覆盖率解析，都只接受
coverage.xml（符合 Cobertura schema） -
pytest-cov生成的 XML 是唯一被广泛支持的工业级标准格式
pytest-cov 必须加 --cov=src 而不是 --cov=.
源码目录定位不准，是 CI 中覆盖率归零或虚高的最常见原因。用 . 会让 coverage.py 扫描整个工作区，包括 tests/、venv/、.git/，导致分母膨胀、覆盖率被稀释，甚至因权限问题跳过关键模块。
SkillSub Pro - Python 题解与代码注释双功能技能功能概述SkillSub Pro - Python 题解与代码注释双功能技能是一项面向实际任务的技能，主要用于SkillSub Pro 是一个 Python 题解生成与代码注释的 双功能合体技能 ，专为学生、算法学习者和开发者设计；✅ 一个技能，两种用途 ：；核心要点📝 题解模式 ：输入题目/题号，自动生成完整 Python 题解（含详细注释、解题思路、复杂度分析）；💬 注释模式 ：输入 Python 代码，自动添加详细中。它将相关步骤、
- 明确指定业务代码路径，例如
--cov=src、--cov=app、--cov=my_package - 如果项目用
setuptools安装（pip install -e .），确保setup.py或pyproject.toml中packages声明与--cov=值一致 - 多模块项目可叠加：
--cov=src --cov=utils --cov=adapters
GitLab CI 必须配置 artifacts 和 coverage 正则双保险
只生成 coverage.xml 不够，GitLab 需要两件事同时满足才能在 MR 中显示覆盖率卡片：
-
artifacts:paths显式保留coverage.xml，否则 job 结束后文件被清理 -
coverage: '/\d+\.\d+%/'正则仍需保留——它用于 fallback：当 XML 解析失败时，GitLab 会退回到匹配 console 输出里的百分比 - 注意正则写法：
/\d+\.\d+%/匹配87.3%，不能漏掉小数点和百分号；/Coverage.*\d+%/这类模糊写法容易失效
test:
script:
- pip install pytest pytest-cov
- pytest tests/ --cov=src --cov-report=xml:coverage.xml --cov-report=term-missing
artifacts:
paths: [coverage.xml]
coverage: '/\d+\.\d+%/ '
--cov-branch 不是可选项，是上线前必开的开关
只统计行覆盖（line coverage）会掩盖大量逻辑漏洞。一个 if/else 块只要进过 if 分支，整行就算“已覆盖”，但 else 可能永远没被执行过——这在金融、风控类逻辑中极其危险。
- 加上
--cov-branch后，coverage.xml会包含<lines></lines>和<branches></branches>两类数据，CI 系统可据此计算分支覆盖率 - GitLab UI 中会显示两个数字：Line 和 Branch，后者才是真实健壮性的指标
- 若已有历史报告，开启该参数后首次覆盖率通常下降 15–40%，这是正常现象——它暴露了你原本以为“已覆盖”实则漏测的分支
真正卡住团队的，往往不是不会生成报告，而是 --cov= 指向错误目录、XML 被 artifact 漏掉、或默认关闭分支覆盖却没人意识到它缺失。这三个点，比选什么 HTML 主题或加多少插件重要得多。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
