Pluggable parallel-test-runner adapter interface

Coordination with parallel test runners (picking the "final" worker,
waiting for siblings, knowing how many resultsets to expect) used to
hard-code the parallel_tests gem. Env-var-only runners like
parallel_rspec hit the wrong branch of `final_result_process?` and every
worker thought it was the final one. They clobbered each other's
resultsets.

Introduce `SimpleCov::ParallelAdapters`, a small registry and selection
layer with a four-method contract (`active?`, `first_worker?`,
`wait_for_siblings`, `expected_worker_count`). `ParallelTestsAdapter`
wraps the historical gem API. `GenericAdapter` handles the env-var
convention without needing any specific gem. Adapters are tried in
registration order, and the first whose `active?` returns true is
chosen. parallel_rspec works out of the box, and users with custom
runners can plug in their own adapter via:

    SimpleCov::ParallelAdapters.register MyAdapter

Resolves #1065.

Author: sferik

CHANGELOG.md

@@ -25,6 +25,7 @@ Unreleased
 * `# :nocov:` toggle comments (and the configurable `SimpleCov.nocov_token` / `SimpleCov.skip_token`) are deprecated in favor of the new `# simplecov:disable` / `# simplecov:enable` directives. Each file that still uses `# :nocov:` emits a one-time deprecation warning to stderr at load time pointing at the recommended replacement, and any call to `SimpleCov.nocov_token` or `SimpleCov.skip_token` (getter or setter) likewise warns. The directive will be removed in a future release.
 
 ## Enhancements
+* Added `SimpleCov::ParallelAdapters` — a pluggable adapter interface for parallel test runners. SimpleCov's coordination with parallel test runners (deciding which worker does final-result work, waiting for siblings, knowing how many resultsets to expect) now routes through an adapter chain rather than hard-coding the `parallel_tests` gem's API. Two adapters ship: `ParallelTestsAdapter` wraps the historical grosser/parallel_tests gem (precise, gem-API-based); `GenericAdapter` handles any runner that follows the `TEST_ENV_NUMBER` / `PARALLEL_TEST_GROUPS` env-var convention without shipping a Ruby API. The practical impact: **parallel_rspec (and any similar env-var-only runner) now works out of the box** — previously every worker thought it was the "final" one and they clobbered each other's resultsets. Custom runners can register their own adapter via `SimpleCov::ParallelAdapters.register MyAdapter`, where `MyAdapter` subclasses `SimpleCov::ParallelAdapters::Base` and overrides the four contract methods (`active?`, `first_worker?`, `wait_for_siblings`, `expected_worker_count`). See #1065.
 * Added `SimpleCov.ignore_branches` for opting out of synthetic `:else` branches that Ruby's `Coverage` library reports for constructs with no literal `else` keyword — exhaustive `case/in` pattern matches, `case/when` without `else`, `||=` / `&&=`, and `if` / `unless` without `else`. Variadic; only `:implicit_else` is supported today, with room for future synthetic branch types. Calling it without (or before) `enable_coverage :branch` is harmless — the setting is stored and applies once branch coverage is enabled. Explicit `else` arms still count. See #1033.
 * Added `SimpleCov.cover` for declaring a positive coverage scope (the long-requested allowlist counterpart to `add_filter`). Accepts string globs, Regexps, blocks, or arrays of those; multiple calls union. When any `cover` matcher is configured the report drops every source file that doesn't match at least one of them, and string-glob matchers also expand on disk so files that exist but were never required during the run still appear in the report (at 0% coverage). Resolves the long-standing requests in #696 and #869. The companion `SimpleCov.no_default_skips` opts out of the filters that `SimpleCov.start` installs (hidden files, `vendor/bundle/`, test directories) so users who want to opt out wholesale don't have to call `clear_filters` themselves.
 * `SimpleCov.formatter false` (and the equivalent `SimpleCov.formatters []`) now opts out of formatting entirely instead of raising `ConfigurationError`. `SimpleCov::Result#format!` returns `nil` when no formatter is configured. Intended for worker processes in big parallel CI runs (hundreds of jobs) where only a final `SimpleCov.collate` step needs a report — every other worker just drops its `.resultset.json` and exits without paying for HTML or multi-formatter output. See #964.

README.md

@@ -1215,6 +1215,63 @@ $ simplecov uncovered --threshold 90 --top 5
 `--json` emits the same rows as a JSON array (an empty array when
 nothing is below the threshold), useful for piping into a CI gate.
 
+## Parallel-test-runner adapters
+
+SimpleCov coordinates with parallel test runners through a small pluggable
+adapter interface (`SimpleCov::ParallelAdapters`). Two adapters ship out of
+the box:
+
+- **`ParallelTestsAdapter`** — wraps the
+  [grosser/parallel_tests](https://github.com/grosser/parallel_tests) gem
+  and uses its `ParallelTests.first_process?` /
+  `ParallelTests.wait_for_other_processes_to_finish` APIs for precise
+  worker coordination.
+- **`GenericAdapter`** — catch-all for any runner that follows the
+  `TEST_ENV_NUMBER` / `PARALLEL_TEST_GROUPS` env-var convention but
+  doesn't ship a Ruby API (parallel_rspec, knapsack-style splitters,
+  custom CI sharding scripts). Activates when `TEST_ENV_NUMBER` is set
+  and no more-specific adapter is.
+
+Adapters are tried in registration order; the first whose `active?`
+returns `true` is chosen for the run. With both built-ins this means
+parallel_tests users get the precise gem-based path, and parallel_rspec
+(or any env-var-only runner) gets the polling-based fallback without any
+configuration change. See #1065.
+
+### Registering a custom adapter
+
+If you use a parallel runner that uses different env vars or has its own
+synchronization API, define a class that inherits from
+`SimpleCov::ParallelAdapters::Base` and register it:
+
+```ruby
+# In your spec_helper.rb / test_helper.rb (before SimpleCov.start)
+class MyRunnerAdapter < SimpleCov::ParallelAdapters::Base
+  def self.active?
+    !ENV["MY_RUNNER_PID"].nil?
+  end
+
+  def self.first_worker?
+    ENV["MY_RUNNER_PID"].to_i == 1
+  end
+
+  def self.wait_for_siblings
+    MyRunner.barrier!   # if your runner provides a sync primitive
+  end
+
+  def self.expected_worker_count
+    ENV["MY_RUNNER_WORKERS"].to_i
+  end
+end
+
+SimpleCov::ParallelAdapters.register MyRunnerAdapter
+```
+
+Custom adapters are inserted at the front of the selection chain so they
+take precedence over the built-ins. `Base` provides safe no-op defaults
+for any method you don't override (single-process semantics: `active?`
+returns `false`, `first_worker?` returns `true`, etc.).
+
 ## Merging resultsets from parallel CI workers
 
 CI matrices that produce one `.resultset.json` per worker can stitch

lib/simplecov.rb

@@ -131,7 +131,11 @@ def start_tracking
                                               ::Process.respond_to?(:_fork)
       # simplecov:enable
 
-      make_parallel_tests_available
+      # Trigger adapter selection now so the (possibly lazy)
+      # parallel_tests gem load happens at start_tracking time rather
+      # than mid-suite. `current` is memoized; subsequent calls are
+      # cheap.
+      SimpleCov::ParallelAdapters.current
 
       @result = nil
       self.pid = Process.pid
@@ -407,53 +411,44 @@ def result_exit_status(result)
     # @api private
     #
     def final_result_process?
-      return true unless defined?(ParallelTests) && ENV["TEST_ENV_NUMBER"]
-
-      # Pick the *first* started process to do the final-result work, not
-      # the last. Two reasons: (1) the parallel_tests README explicitly
-      # recommends `ParallelTests.first_process?` for "run something
-      # once after every worker finishes" hooks, so user code that
-      # implements its own `wait_for_other_processes_to_finish` (e.g. in
-      # an RSpec `after(:suite)`) overwhelmingly waits in the first
-      # process — picking the same side avoids the cross-process
-      # deadlock #922 reported. (2) `first_process?` naturally handles
-      # the PARALLEL_TEST_GROUPS=1 case: parallel_tests sets the first
-      # worker's TEST_ENV_NUMBER to "" and `first_process?` tests for
-      # that empty string, so a single-group run correctly returns true
-      # without needing the previous `GROUPS.to_i <= 1` workaround
-      # (#1066). Users who waited in the LAST process now hit the
-      # symmetric deadlock and must migrate to `first_process?`; the
-      # CHANGELOG calls this out.
-      ParallelTests.first_process?
+      adapter = SimpleCov::ParallelAdapters.current
+      return true unless adapter
+
+      adapter.first_worker?
     end
 
     #
     # @api private
     #
     # simplecov:disable
-    # Methods below only fire under parallel_tests; not reachable from a
-    # single-process rspec run. Cucumber's test_projects exercise the
-    # parallel_tests integration end-to-end in subprocesses, but those
-    # subprocesses don't merge their Coverage data back into the parent
-    # this dogfood report measures.
+    # Methods below only fire under a parallel test runner; not reachable
+    # from a single-process rspec run. Cucumber's test_projects exercise
+    # the parallel_tests integration end-to-end in subprocesses, but
+    # those subprocesses don't merge their Coverage data back into the
+    # parent this dogfood report measures.
     def wait_for_other_processes
-      return unless defined?(ParallelTests) && final_result_process?
+      adapter = SimpleCov::ParallelAdapters.current
+      return unless adapter && final_result_process?
 
-      ParallelTests.wait_for_other_processes_to_finish
+      # Native synchronization first (adapters that wrap a runner with a
+      # real "wait" primitive — parallel_tests' `wait_for_other_processes_to_finish`
+      # — implement this; adapters without a native API no-op and rely
+      # on the polling fallback below).
+      adapter.wait_for_siblings
 
-      # ParallelTests signals "done" before at_exit handlers finish, so other
-      # processes may still be writing their results. Poll the resultset until
-      # all parallel groups have reported or a timeout is reached.
-      wait_for_parallel_results
+      # The native wait can return before sibling at_exit handlers finish
+      # writing resultsets, and adapters without a native wait have nothing
+      # else. Either way, poll the resultset cache until all expected
+      # workers have reported or a timeout is reached.
+      wait_for_parallel_results(adapter.expected_worker_count)
     end
     # simplecov:enable
 
     # @api private
-    def wait_for_parallel_results
-      expected = ENV["PARALLEL_TEST_GROUPS"]&.to_i
-      return unless expected && expected > 1 # simplecov:disable branch — only false in real parallel_tests run
+    def wait_for_parallel_results(expected)
+      return unless expected > 1 # simplecov:disable branch — only false in real parallel runs
 
-      # simplecov:disable — only fires when ENV is set with >1 group
+      # simplecov:disable — only fires under multi-worker parallel runs
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 10
       loop do
         resultset = SimpleCov::ResultMerger.read_resultset
@@ -622,35 +617,6 @@ def defer_to_minitest_after_run
       Minitest.after_run { SimpleCov.at_exit_behavior }
     end
 
-    # Auto-require `parallel_tests` when it's installed AND the env vars
-    # it sets are present, so `wait_for_other_processes` and friends can
-    # call `ParallelTests.first_process?` later. `parallel_tests` is an
-    # optional dependency (see https://github.com/grosser/parallel_tests/issues/772),
-    # and `TEST_ENV_NUMBER` / `PARALLEL_TEST_GROUPS` are commonly set for
-    # other reasons (custom subprocess coordination, CI sharding), so a
-    # missing gem is treated as "user isn't using parallel_tests" — silently
-    # skip rather than warn. Users who want to override the auto-detect can
-    # set `SimpleCov.parallel_tests true` (force on) or `false` (force off).
-    # See #1018.
-    def make_parallel_tests_available
-      return if defined?(ParallelTests) # simplecov:disable — only true after a previous load
-      return if SimpleCov.parallel_tests == false # simplecov:disable — only fires when user opts out
-      # simplecov:disable — false outside parallel_tests
-      return unless SimpleCov.parallel_tests || probably_running_parallel_tests?
-
-      # simplecov:disable — only fires under a real parallel_tests setup
-      require "parallel_tests"
-    rescue LoadError
-      # The gem isn't installed; the env vars were set for some other
-      # reason. Stay quiet — warning here regressed users who use those
-      # env vars for their own subprocess coordination (see #1018).
-      # simplecov:enable
-    end
-
-    def probably_running_parallel_tests?
-      ENV.fetch("TEST_ENV_NUMBER", nil) && ENV.fetch("PARALLEL_TEST_GROUPS", nil)
-    end
-
     # JRuby coverage data is unreliable unless full-trace mode is enabled.
     # @see https://github.com/jruby/jruby/issues/1196
     # @see https://github.com/simplecov-ruby/simplecov/issues/420
@@ -690,6 +656,7 @@ def warn_if_jruby_full_trace_disabled
 require_relative "simplecov/last_run"
 require_relative "simplecov/lines_classifier"
 require_relative "simplecov/result_merger"
+require_relative "simplecov/parallel_adapters"
 require_relative "simplecov/command_guesser"
 require_relative "simplecov/version"
 require_relative "simplecov/result_adapter"

lib/simplecov/parallel_adapters.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "parallel_adapters/base"
+require_relative "parallel_adapters/parallel_tests"
+require_relative "parallel_adapters/generic"
+
+module SimpleCov
+  # Registry + selection for parallel-test-runner adapters. An adapter
+  # answers a small fixed set of questions on SimpleCov's behalf:
+  #
+  #   - `active?` — are WE the runner in charge for this process?
+  #   - `first_worker?` — should this process do the final-result work?
+  #   - `wait_for_siblings` — block until siblings finish (optional)
+  #   - `expected_worker_count` — how many workers total
+  #
+  # `SimpleCov::ParallelAdapters::Base` provides safe no-op defaults; two
+  # adapters ship out of the box:
+  #
+  #   - `ParallelTestsAdapter` — wraps the grosser/parallel_tests gem
+  #     (precise sync + first-process detection via the gem's own API).
+  #   - `GenericAdapter` — env-var-only detection for runners that follow
+  #     the parallel_tests `TEST_ENV_NUMBER` convention but don't ship a
+  #     Ruby API (parallel_rspec, custom CI sharding, knapsack-style
+  #     splitters). See https://github.com/simplecov-ruby/simplecov/issues/1065.
+  #
+  # Users can plug in additional adapters:
+  #
+  #   SimpleCov::ParallelAdapters.register MyRunnerAdapter
+  #
+  # An adapter just needs to be a class responding to the four methods
+  # above. Subclass `SimpleCov::ParallelAdapters::Base` to inherit the
+  # no-op defaults and override only what you need (the contract methods
+  # are defined as class methods, so plain inheritance is what carries
+  # them through; `extend Base` won't pick them up).
+  module ParallelAdapters
+  module_function
+
+    # Adapters in selection order. ParallelTestsAdapter first (most
+    # specific — uses the gem's own API when the gem is loaded); then
+    # GenericAdapter as the env-var fallback. User-registered adapters
+    # are prepended (#register puts new entries at the front) so
+    # downstream code can override the built-ins by registering a more
+    # specific match.
+    def adapters
+      @adapters ||= [ParallelTestsAdapter, GenericAdapter]
+    end
+
+    # Register a custom adapter. Newly registered adapters are inserted
+    # at the front of the selection list so a custom adapter for a
+    # specific runner takes precedence over the built-in ParallelTests
+    # and Generic adapters.
+    #
+    #   class MyRunnerAdapter < SimpleCov::ParallelAdapters::Base
+    #     def self.active?       = ENV["MY_RUNNER_PID"]
+    #     def self.first_worker? = ENV["MY_RUNNER_PID"].to_i == 1
+    #     def self.expected_worker_count = ENV["MY_RUNNER_WORKERS"].to_i
+    #   end
+    #
+    #   SimpleCov::ParallelAdapters.register MyRunnerAdapter
+    def register(adapter)
+      reset_current!
+      adapters.unshift(adapter) unless adapters.include?(adapter)
+      adapter
+    end
+
+    # The adapter SimpleCov should consult for this process — the first
+    # registered adapter whose `active?` returns true. Returns nil when
+    # no adapter is active (i.e., we're not running under any recognized
+    # parallel test runner), in which case the caller should treat the
+    # process as single-worker.
+    def current
+      return @current if defined?(@current)
+
+      @current = adapters.find(&:active?)
+    end
+
+    # Clear the memoized `current` selection. Primarily for tests that
+    # mutate env vars between examples; production runs are single-shot.
+    def reset_current!
+      remove_instance_variable(:@current) if defined?(@current)
+    end
+  end
+end

lib/simplecov/parallel_adapters/base.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module ParallelAdapters
+    # Default no-op implementations for a parallel-test-runner adapter.
+    # Real adapters subclass and override what they need; everything else
+    # falls back to "behave like a single-process run."
+    #
+    # Adapters are classes (used as singletons, never instantiated) — they
+    # answer a small fixed set of questions about whether THIS worker
+    # process is the one that should do final-result work, and provide an
+    # optional hook for waiting on sibling workers.
+    #
+    # @see SimpleCov::ParallelAdapters for the registry and selection.
+    class Base
+      class << self
+        # Should this adapter be selected for the current process? Adapters
+        # are tried in registration order; the first one whose `active?`
+        # returns true is chosen. Inactive adapters return `false`.
+        def active?
+          false
+        end
+
+        # Among the parallel workers in this run, should THIS worker do
+        # the final-result work (wait for siblings, merge resultsets,
+        # run threshold checks, format the report)? Default is `true`
+        # for the single-process case.
+        def first_worker?
+          true
+        end
+
+        # Optional: block until sibling workers have finished writing
+        # their resultsets. An adapter that wraps a parallel-test runner
+        # with a native synchronization primitive (e.g., `parallel_tests`'s
+        # `wait_for_other_processes_to_finish`) implements this for
+        # lower latency; otherwise SimpleCov polls the resultset cache
+        # as a fallback (see `SimpleCov.wait_for_parallel_results`).
+        def wait_for_siblings
+          # No-op default; polling fallback handles correctness.
+        end
+
+        # How many parallel workers are participating in this run. Used
+        # by the polling fallback to know how many resultset entries to
+        # expect. Defaults to 1 (single-process).
+        def expected_worker_count
+          1
+        end
+      end
+    end
+  end
+end

lib/simplecov/parallel_adapters/generic.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SimpleCov
+  module ParallelAdapters
+    # Catch-all adapter for parallel test runners that follow the
+    # `TEST_ENV_NUMBER` / `PARALLEL_TEST_GROUPS` env-var convention but
+    # don't ship a Ruby API for SimpleCov to hook (parallel_rspec,
+    # knapsack-style splitters, custom CI sharding scripts). Activates
+    # when `TEST_ENV_NUMBER` is set; doesn't require any specific gem to
+    # be loaded.
+    #
+    # Heuristic for `first_worker?`: the worker whose `TEST_ENV_NUMBER`
+    # is `""` (parallel_tests/parallel_rspec convention) or `"1"`
+    # (zero-based runners that start at 1). Any other value is treated
+    # as a non-first worker.
+    #
+    # `wait_for_siblings` is inherited from Base as a no-op — without a
+    # runner-provided API the only synchronization available is polling
+    # the resultset cache, which `SimpleCov.wait_for_parallel_results`
+    # does after the no-op returns.
+    class GenericAdapter < Base
+      class << self
+        def active?
+          !ENV.fetch("TEST_ENV_NUMBER", nil).nil?
+        end
+
+        # parallel_tests sets the first worker's TEST_ENV_NUMBER to "";
+        # parallel_rspec inherits that. Runners that number from 1 use
+        # "1" for the first worker. Both shapes match.
+        def first_worker?
+          ["", "1"].include?(ENV.fetch("TEST_ENV_NUMBER", nil))
+        end
+
+        def expected_worker_count
+          ENV["PARALLEL_TEST_GROUPS"]&.to_i || 1
+        end
+      end
+    end
+  end
+end