SimpleCov 入门：Ruby 测试覆盖率分析完全指南
SimpleCov 是 Ruby 代码覆盖率分析的标准工具。本文讲解安装配置、行/分支覆盖率解读、阈值设定、文件过滤与 CI 集成，帮你把覆盖率变成有效的质量信号。
SimpleCov 在测试运行时统计哪些代码行被执行，生成 HTML 覆盖率报告。用法是在测试辅助文件最顶部 SimpleCov.start，跑完测试打开 coverage/index.html 查看。配置过滤与最低阈值后接入 CI，覆盖率低于阈值即构建失败。
覆盖率能告诉你什么（和不能）
覆盖率回答"哪些代码被测试执行过"——没被执行的行一定没被测试保障；但被执行过不代表被验证过（没有断言的测试照样刷满覆盖率）。覆盖率是发现测试盲区的手电筒，不是质量合格证。
安装与配置
# Gemfile
group :test do
gem 'simplecov', require: false
end
关键：必须在 spec_helper/test_helper 的最顶部启动，早于任何应用代码加载：
require 'simplecov'
SimpleCov.start 'rails' do
add_filter '/spec/'
add_filter '/config/'
add_group 'Services', 'app/services'
add_group 'Jobs', 'app/jobs'
end
require_relative '../config/environment' # 必须在 SimpleCov 之后
跑完测试，打开 coverage/index.html：绿行已覆盖、红行未覆盖，按文件/分组查看。
读懂覆盖率指标
- 行覆盖率（Line Coverage）：被执行行数 / 总行数，基础指标；
- 分支覆盖率（Branch Coverage）：
enable_coverage :branch开启，统计 if/else、case 各分支是否都走过——80% 行覆盖率的代码可能只有 50% 分支覆盖，分支指标更接近"路径完备性"； - 按组查看：Models/Services/Jobs 分组统计，快速定位薄弱层。
阈值与渐进收紧
SimpleCov.start 'rails' do
minimum_coverage 85 # 总覆盖率低于 85% 返回失败
minimum_coverage line: 85, branch: 70
maximum_coverage_drop 2 # 单次提交覆盖率下降超 2% 失败
end
maximum_coverage_drop 是老项目的神器：总覆盖率可以低（历史债），但每次提交不许变得更差——债务只减不增，覆盖率随时间自然爬升。
过滤的正确姿势
只统计"你写的代码"：过滤 spec/、config/、vendor/、db/；生成的代码（Rails 脚手架、迁移文件）按需排除。警惕过滤过度——把难测的核心文件加进过滤清单，等于把盲区藏进地毯。第三方代码本身就不在统计范围（SimpleCov 只跟踪项目内加载的文件）。
CI 集成与报告
CI 中跑完测试后 SimpleCov 自动按阈值设置退出码；配合 simplecov-lcov 等 formatter 输出 LCOV 格式，可接入 Codecov/Coveralls 在 PR 上评论覆盖率变化。并行测试（parallel_tests）时用 SimpleCov.command_name 区分各进程结果，自动合并。
常见问题（FAQ）
Q：覆盖率要追求 100% 吗？
没有适用于所有项目的目标百分比：核心业务逻辑（金额计算、权限判断）追求 100%，脚手架代码、简单委派不必强求。为凑数字写的无断言测试反而制造虚假安全感。
Q：测试结果里覆盖率明显不对（很多 0%）？
九成是 SimpleCov 启动顺序错了——必须先 SimpleCov.start 再加载应用代码；Spring 等预加载器也可能导致文件在 SimpleCov 之前加载，测试时禁用 Spring 或配置其重启钩子。
Q：如何只报告本次改动相关的覆盖情况？
配合 undercover gem：分析 git diff，只报告"变更行"的覆盖状态，PR review 时精确拦截"新代码没测试"的情况——比全量阈值更适合大团队。
参考文档
本文依据公开文档整理，示例需按项目依赖版本验证；不将文档中的性能描述视为本项目实测结果。
