升级前先对齐版本:测试框架与主框架的绑定关系

原创2026-11-07 10:20:281,711 阅读
文章标签:后端Web框架ORM前端

升级前先对齐版本:测试框架与主框架的绑定关系

Rails 升级出问题,很多时候原因并非业务代码本身,而在于测试框架的版本没跟上主框架。Rails 的测试栈并不依赖 Rails 自身,它依赖 Minitest;而 Minitest 从 5 跨到 6 时,一批被 Rails 长期当作“内部 API”使用的方法发生了位移:-n/--name 的语义、run 与 run_suite 的拆分、filter 与 include 的键名、run_one_method、parallel_executor、run_order……这些名字一旦错位,表现往往是“测试跑了 0 个”“报告器崩了”“并行 worker 静默退出”,而且报错位置离真实原因很远。

本文以当前仓库(RAILS_VERSION 为 8.2.0.alpha)的真实源码为线索,梳理一条可执行的核对顺序:先看版本声明层,再看运行时探测层,最后看 CLI 参数层。读者可以直接对着仓库里的文件核对本地项目的状态。

三层版本三角:Ruby、Rails、Minitest

升级时最容易被忽略的,是版本约束其实分布在三个不同的地方,而且三处的宽松程度完全不同。

第一层是 Ruby 下限。 仓库里所有 gemspec 都写死了同一条约束:

s.required_ruby_version = ">= 3.3.5"

见 rails.gemspec 与 activesupport.gemspec。升级指南 也明确列出:Rails 8.2 需要 Ruby 3.3.5 或更新,而 Rails 8.0/8.1 只要求 Ruby 3.2.0。这条约束是硬性的——Ruby 版本不够,bundle install 直接失败,属于“不会静默出错”的那一类,反而最安全。

第二层是 Rails 自身的版本一致性。 rails.gemspec 里每个子组件都用同一个 version 变量声明依赖:

version = File.read(File.expand_path("RAILS_VERSION", __dir__)).strip
s.add_dependency "activesupport", version
s.add_dependency "actionpack",    version
# ...

这是“等值约束”而非“范围约束”,所以 Rails 的各个 gem 不可能出现半升级状态。这一层通常不需要人操心。

第三层才是真正的风险点:Minitest 的约束是一条极宽的下界。

activesupport.gemspec 中写着:

s.add_dependency "minitest", ">= 5.1"

>= 5.1 意味着 Minitest 5.x、6.x 甚至将来的 7.x 都满足声明,Bundler 会解析到它认为最合适的最新版本。而 Rails 8.2 的开发分支本身已经切到了 6:

# Gemfile
gem "minitest", "~> 6.0"
gem "minitest-mock"
# Gemfile.lock
minitest (6.0.6)
minitest-mock (5.27.0)

注意这里的落差:Gemfile 钉住 ~> 6.0,gemspec 只承诺 >= 5.1。对 Rails 仓库自己而言没问题,因为它有 Gemfile.lock;但对一个普通应用来说,activesupport 只是传递依赖,Bundler 会按自己的规则求解,minitest 最终是什么版本,取决于依赖图,而非你的意图。

更微妙的是,新生成的应用的 Gemfile 里根本不出现 minitest。应用模板 Gemfile 的 :test 组只有两项:

group :test do
  # Use system testing
  gem "capybara", require: false
  gem "selenium-webdriver", require: false
end

也就是说,绝大多数 Rails 项目的测试框架版本是“隐式解析出来的”。另外 rails-dom-testing 本身也依赖 minitest(见 Gemfile.lock 中该 gem 的依赖列表),所以即使你不写一行测试,Minitest 也会被拉进依赖图。这正是“测试框架与主框架绑定关系”必须在升级前显式核对的原因:它的版本不受你控制,却决定了 bin/rails test 的行为。

顺带一提,社区里讨论 RSpec 生态时给出的经验也是同一条:测试框架与 Rails 之间存在事实上的版本对应关系,升级时语义化版本的破坏性变更会直接体现在测试基类上。这个规律对 Minitest 同样成立,甚至更隐蔽,因为 Minitest 是默认依赖,没人会主动去读它的版本号。

核对顺序:先看解析结果,再看声明,最后看运行时

推荐的自检顺序是“从结果反推”,而不是“从文档正推”,因为只有解析结果才是真相。

第一步:确认实际解析到的版本

bundle info minitest
bundle exec ruby -e 'require "minitest"; puts Minitest::VERSION'

bundle info 会给出当前 lock 中的版本与路径,第二行确认运行时加载的是同一个版本。之所以要两条,是因为在容器或 CI 中,可能存在系统 gem 与 bundle 路径互相干扰的情况;autorun.rb 的注释里就记录了这种场景:

# This respond_to check handles tests running sub-processes in an
# unbundled environment, which triggers MT5 usage.
Minitest.load :rails if Minitest.respond_to? :load
Minitest.autorun

Rails 不得不用 respond_to? 来兼容“子进程跑在非 bundle 环境、结果加载到 Minitest 5”的情况。如果你在 CI 中看到测试输出格式突然从 Rails 的彩色点变成 Minitest 原始输出,八成就是某个子进程走到了另一份 Minitest。

第二步:检查应用侧是否显式声明

如果应用的 Gemfile 里有自己的 gem "minitest",那它才是权威;如果没有,就应当补一条显式约束,把隐式解析变成可审查的声明。修改时用保守更新,避免顺带把 Rails 抬上去:

bundle update --conservative minitest

第三步:检查代码里对 Minitest 的直接引用

grep -rn "Minitest::\|minitest/" test/ lib/

这一条比前两条更能暴露问题,因为 Rails 自己就在做大量“贴着 Minitest 内部结构”的事,应用里的自定义 reporter、断言模块、test_helper 往往照着 Rails 源码抄,抄的正是最容易变的那些点。

升级前的三项前置检查

检查一:bin/rails test 的过滤参数还能不能表达你的意图

Rails 对 Minitest 6 的参数兼容是这样处理的,见 railties/lib/minitest/rails_plugin.rb:

if Minitest::VERSION > "6" then
  opts.on "-n", "--name PATTERN", "Include /regexp/ or string for run." do |a|
    warn "Please switch from -n/--name to -i/--include"
    options[:include] = a
  end
end

这段代码传递了两个信息:Minitest 6 侧推荐用 -i/--include;而 Rails 把 -n 作为兼容别名重新挂了回去,并打印弃用提示。也就是说,-n 在 MT6 下仍然能用,但它是 Rails 补的桥,不是 Minitest 的原生行为。

这层桥此前还出过真问题。railties/CHANGELOG.md 的第一条就是:

Fix bin/rails test -n ClassName#test_name running no tests. This has been broken since Rails 7.1. It also made isolated tests fail on platforms without fork, like JRuby and Windows.

而 railties/test/application/test_runner_test.rb 里保留了对应的回归用例:

run_test_command("test/models/post_test.rb:4 -n test_by_name").tap do |output|
  assert_match "by line", output
  assert_match "by name", output
  assert_match "2 runs, 2 assertions", output
end

这里有个值得玩味的细节:文件行号 :4 和 -n test_by_name 同时给出时,期望结果是两个测试都跑。因为 Rails 把两种过滤条件做了并集,而不是交集,实现位于 runner.rb 的 CompositeFilter:

# minitest uses === to find matching filters.
def ===(method)
  @filters.any? { |filter| filter === method }
end

升级前一定要跑一次你这套过滤命令,确认“跑几个、跑哪些”符合预期。这类错误最危险的地方在于:它不报错,只是少跑了测试,CI 仍然是绿的。

检查二:并行测试的执行器有没有被接管

Rails 的并行测试并不是 Minitest 原生并行,而是把 Minitest 的执行器换成了自己的实现。test_case.rb 里:

Minitest.parallel_executor = ActiveSupport::Testing::ParallelizeExecutor.new(
  size: workers, with: with, threshold: threshold, work_stealing: work_stealing
)

而 parallelize_executor.rb 判断是否需要并行、统计测试总数的写法,全部贴着 Minitest 的类方法:

def parallelize
  @parallelized = true
  Minitest::Test.parallelize_me!
end

def tests_count
  @tests_count ||= Minitest::Runnable.runnables.sum { |runnable| runnable.runnable_methods.size }
end

另一侧,isolation.rb 用“是否已经是 Rails 的执行器”来避免重复接管:

parallelize_me! unless Minitest.parallel_executor.is_a?(ActiveSupport::Testing::ParallelizeExecutor)

这条判断就是一层防御性代码:如果 Minitest 换了执行器接口,或某个 gem 抢先接管了 parallel_executor,这里的行为会变。升级后请重点确认三件事:并行输出里是否还有 Running N tests in parallel using M processes 这类提示;“阈值以下单进程跑”的逻辑是否仍然生效(阈值来自 config.active_support.test_parallelization_threshold);test_helper 模板 里 with: :threads 的分支在无 fork 平台上是否仍被正确选中。

与之相关的是 worker 侧的兼容分支,见 parallelization/worker.rb:

if Minitest.respond_to?(:run_one_method) then
  Minitest.run_one_method(klass, method)
else
  klass.new(method).run
end

这类 respond_to? 是好事,说明 Rails 在用特性探测而非版本号猜测;但它也意味着:一旦 Minitest 保留方法名却改了语义,探测就失效了。所以升级后必须实跑一次全量测试,而不是只看 bundle install 是否成功。

检查三:自定义 reporter 与断言扩展

Rails 的报告器直接继承 Minitest 的内部类,见 railties/lib/rails/test_unit/reporter.rb:

class TestUnitReporter < Minitest::StatisticsReporter

插件的初始化还会替换 Minitest 自带的两个报告器:

if reporter.reporters.reject! { |reporter| reporter.kind_of?(SummaryReporter) }
  reporter << SuppressedSummaryReporter.new(options[:io], options)
end

if reporter.reporters.reject! { |reporter| reporter.kind_of?(ProgressReporter) }
  reporter << ::Rails::TestUnitReporter.new(options[:io], options)
end

这意味着任何“替换内置 reporter”的第三方插件、任何继承 Minitest::Reporter 的自研统计器,都在同一片竞争区域里。升级前把这类代码找出来,确认它们只依赖 record(result)、report 这类稳定钩子,而不是 result.result_code 之外的内部字段。

断言一侧同理。assertions.rb 里有两处版本判断:

error = "#{error}\n#{diff before_value + diff, actual}" if Minitest::VERSION > "6"
error = "#{error}\n#{diff before, after}" if Minitest::VERSION > "6"

这里用的是字符串比较。对 5.x 与 6.x 目前是正确的,但它属于典型的“靠字符串猜语义”,一旦版本号形态变化就会失准。应用侧如果抄了这种写法,建议在升级时顺手改成特性探测,或者至少改成 Gem::Version 比较。

破坏性变更的常见落点

把仓库里所有分支汇总起来,Minitest 5 到 6 的位移集中在四个落点,而 Rails 为每一个落点都写了分支代码——这本身就是最好的变更清单。

落点一:测试执行入口从 run 变成 run_suite。 见 line_filtering.rb:

case Minitest::VERSION
when /^5/ then
  obj.extend MT5
when /^6/ then
  obj.extend MT6
end

module MT5
  def run(reporter, options = {})
    options = options.merge(filter: Rails::TestUnit::Runner.compose_filter(self, options[:filter]))
    super
  end
end

module MT6
  def run_suite(reporter, options = {})
    options = options.merge(include: Rails::TestUnit::Runner.compose_filter(self, options[:include]))
    super
  end
end

这段代码同时说明了三件事:方法名从 run 改为 run_suite;选项键从 filter 改为 include;以及 Rails 的“按行号过滤”必须挂在正确的入口上才生效。如果你自己写模块 extend 到测试类上做过滤,升级时必须同步这套分支。

落点二:测试类可选方法从 test_order 迁移到 run_order。 test_case.rb 里:

if Minitest::Runnable.respond_to? :run_order # MT6 API change
  def run_order
    test_order
  end
end

这里用的是探测而非版本判断,属于正确示范。应用侧如果覆写了 test_order 期望改变执行顺序,需要确认在 MT6 下是否还需要同时提供 run_order。

落点三:mock/stub 能力成为独立依赖。 Rails 根 Gemfile 显式声明了 gem "minitest-mock",lock 中解析为 5.27.0,与 minitest 6.0.6 是两个包。而 method_call_assertions.rb 的第一行仍然是:

require "minitest/mock"

这就是典型的“require 路径不变、提供者变了”。应用如果大量使用 Minitest::Mock、object.stub,升级后要确认 minitest-mock 是否在依赖图里;否则 require "minitest/mock" 会在某个测试文件首次加载时炸掉,而错误信息指向的是那行 require,不是版本问题。

落点四:CLI 参数语义。 前面提到的 -n 兼容层是显性的,-i/--include 是新的原生写法。升级期间建议先做一次“参数扫描”:把 CI 脚本、Rake 任务、编辑器里的测试运行配置、TESTOPTS 环境变量全部 grep 一遍,把 -n 统一改为 -i,不要长期依赖 Rails 的兼容桥——因为桥的实现位置在 Minitest::VERSION > "6" 的分支里,它本身也是会变的。

一次可复用的对齐流程

把上述内容压缩成升级时可以直接照做的顺序:

  1. bundle info minitest 确认实际版本,凡是与 Rails 版本组合未见过的搭配,先降级到已知组合再谈升级。
  2. 在 Gemfile 中显式声明 minitest(以及需要 mock 时的 minitest-mock),把隐式传递依赖变成可评审的约束。
  3. grep -rn "Minitest::\|minitest/" test/ lib/,把所有贴着内部 API 的代码列出来,逐个对照上文的四个落点。
  4. 实跑一次过滤命令(行号、-n/-i、文件、目录混合),确认“跑几个测试”的数量与预期一致——这一步比全量跑更能抓出静默失效。
  5. 实跑一次并行全量,确认并行执行器仍被 Rails 接管,worker 没有静默退出。
  6. 最后再走 Rails 官方升级路径:升级指南 明确建议先升 Ruby、再逐个 minor 升 Rails,并在每一跳都“跑测试、修弃用”。

顺序上有一个原则值得强调:先对齐版本,再动业务代码。因为版本错位造成的问题是“框架层静默降级”,它会让后面所有的失败都变得难以归因——你以为在修新版本的破坏性变更,实际在修一个跑错了测试框架的测试进程。把 bundle info minitest 的输出贴在升级 PR 的描述里,是个成本极低、收益很高的习惯。

登录后查看全文
rails