Add post-suite hooks for SimpleCov integration

[cb341]

🤖 This PR was authored by Claude Haiku and Opus (Anthropic).

Problem

SimpleCov doesn't support rspec-conductor. When tests run across forked workers, each process writes its own coverage data, but there's no mechanism to merge results in the parent process after workers exit.

SimpleCov handles this for parallel_tests through explicit integration:

• CommandGuesser.from_env detects PARALLEL_TEST_GROUPS / TEST_ENV_NUMBER to assign unique command names per worker
• final_result_process? gates reporting to run only in the last ParallelTests process
• wait_for_other_processes calls ParallelTests.wait_for_other_processes_to_finish before merging

None of this works for rspec-conductor. Users are forced to manually invoke ResultMerger.merged_result and process_result after rspec-conductor exits, e.g. in CI:

# Merge and validate SimpleCov results from all workers
bundle exec ruby -r simplecov -e "
  result = SimpleCov::ResultMerger.merged_result
  if result
    result.format!
    SimpleCov.process_result(result)
  end
"

Related SimpleCov issues:

• #1156: rspec-conductor support (the direct request)
• #232: minimum_coverage validates too early, before all processes finish
• #350: merging parallel test results requires manual command_name / merge_timeout setup
• #1091: branch coverage data lost when merging across parallel runners (Flatware)

Solution

Add a post-suite hook mechanism: callbacks that run in the parent process after all workers complete, before printing the summary.

RSpec::Conductor.register_post_suite_hook do
  # runs in parent, after workers exit
end

When SimpleCov is defined, rspec-conductor automatically registers a hook that calls merged_result and process_result. No application-side code needed. This mirrors what SimpleCov does internally for parallel_tests via final_result_process? + wait_for_other_processes, but driven from the runner side.

Changes

• Server.post_suite_hooks / Server.register_post_suite_hook: class-level hook registry
• Server#run: call hooks after suite_run.suite_complete, before print_summary
• RSpec::Conductor.register_post_suite_hook: public API (delegates to Server)
• Auto-register SimpleCov hook when SimpleCov constant is defined (parent process only)

[cb341]

@markiz, what are your thoughts on the simplecov issue?

[markiz]

@cb341
Hey, first of all, sorry about the long response, I missed this PR completely.

But my question is gonna be: what's so bad about running a one-line bash-script in the CI? I'm a bit reluctant to add a feature that's specific to simplecov unless there's something that's not achievable in a straightforward way with other tools.

[cb341]

Thanks for your quick response @markiz. Sorry for finding time only now to respond.

---

Because rspec-conductor can in some ways be interpreted as the natural successor to parallel_tests, inlining features such as coverage report concatenation for SimpleCov reduces the friction of migrating to rspec-conductor.

User experience was designed to serve as a simple, almost drop-in, replacement for the parallel_tests gem.

I believe that not having to update existing project configuration to accommodate rspec-conductor will improve the developer experience. SimpleCov already has built-in support for parallel_tests, and if rspec-conductor is supposed to serve as a drop-in replacement, I'd expect coverage to work out of the box. It seems reasonable for me to assume people running tests with parallel_tests also have code coverage checks with simplecov.

Alternatively, we could mention the changes needed for SimpleCov to work properly directly in the README. Figuring out how to configure SimpleCov to concatenate reports by yourself takes time.
I have made a proposal here: 98e9047

Reading the gem's development philosophy:

This library is very minimalistic by design. While there is a dependency on rspec-core, obviously, but there are no dependencies beyond that. Even the TUI stuff is handled internally.

it'd probably make the most sense to stick with the README changes to adhere to the gem's philosophy.

[markiz]

@cb341
Yeah, README change is okay.

I don't think you need to do the SimpleCov.command_name "rspec#{ENV.fetch('TEST_ENV_NUMBER', '')}" anymore, though, that part should be covered by the simplecov auto detection seeing the PARALLEL_TEST_GROUPS env var. scratch that, simplecov is trying to be smart to its own detriment.

Let me think about this a little. Maybe we need a per-worker post-suite-require (in line with the other config options), so that you could write the simplecov result there

[markiz]

@cb341

Can you try adding this file to your app, let's say spec/simplecov_config.rb

require 'bundler/setup'
require 'simplecov'
require 'rspec/core'

SimpleCov.start do
  formatter SimpleCov::Formatter::MultiFormatter.new(
    [
      SimpleCov::Formatter::HTMLFormatter,
      SimpleCov::Formatter::SimpleFormatter,
    ]
  )
end

RSpec.configure do |config|
  # This will trigger per worker on suite start
  config.before(:suite) do
    if ENV['TEST_ENV_NUMBER']
      SimpleCov.command_name "rspec #{ENV['TEST_ENV_NUMBER']}"
    else
      SimpleCov.command_name "rspec"
    end
  end

  # This will trigger per worker on suite finish
  config.after(:suite) do
    SimpleCov.result.format!
  end
end

# This will trigger once all workers finish
SimpleCov.at_exit do
  result = SimpleCov::ResultMerger.merged_result
  if result
    result.format!
    SimpleCov.process_result(result)
  end
end

# This will load the rails app
require_relative '../config/application'

then run with bundle exec rspec-conductor --prefork-require spec/simplecov_config.rb --format plain spec/

This should about cover it, I think? Piggybacking off the rspec before/after suite hooks since those are run per worker already.