simplecov 1.1.0 → 1.2.0

data/lib/simplecov/formatter/multi_formatter.rb

@@ -2,27 +2,21 @@
 
 module SimpleCov
   module Formatter
-    # Wraps multiple formatters so SimpleCov.formatter can drive several
-    # output formats (HTML + JSON, etc.) in a single run.
     class MultiFormatter
-      # Shared `#format` implementation; included into individual
-      # MultiFormatter subclasses built by `MultiFormatter.new`.
       module InstanceMethods
         def format(result)
           formatters.map do |formatter|
             Formatter.format(formatter, result)
-          rescue StandardError => e
-            warn("Formatter #{formatter} failed with #{e.class}: #{e.message} (#{(_ = e.backtrace).first})")
-            nil
+          rescue => e
+            warn("Formatter #{formatter} failed with #{e.class}: #{e} (#{(_ = e.backtrace).first})")
           end
         end
       end
 
+      # Normalized eagerly and captured in the closure. `Array()` is pure for every
+      # accepted input shape, so this is equivalent to the historical lazy
+      # per-instance memoization.
       def self.new(formatters = nil)
-        # Normalize eagerly and capture the list in the closure. Array()
-        # is pure for every accepted input shape (nil, single formatter,
-        # array, or another MultiFormatter class), so this is equivalent
-        # to the historical lazy per-instance memoization.
         formatter_list = Array(formatters)
         Class.new do
           define_method :formatters do

data/lib/simplecov/formatter/simple_formatter.rb

@@ -2,22 +2,16 @@
 
 module SimpleCov
   module Formatter
-    #
-    # A ridiculously simple formatter for SimpleCov results.
-    #
     class SimpleFormatter
-      # Takes a SimpleCov::Result and generates a string out of it
       def format(result)
         criterion = SimpleCov.coverage_statistics_key(SimpleCov.primary_coverage)
         result.groups.map { |name, files| format_group(name, files, criterion) }.join
       end
 
-    private
+      private
 
       def format_group(name, files, criterion)
-        header = "Group: #{name}\n#{'=' * 40}\n"
-        # The configured primary criterion is enabled, so every result file
-        # carries its corresponding statistic despite the nilable public API.
+        header = "Group: #{name}\n#{"=" * 40}\n"
         body = files.map do |file|
           "#{file.filename} (coverage: #{(_ = file.covered_percent(criterion)).floor(2)}%)\n"
         end.join

data/lib/simplecov/formatter.rb

@@ -1,20 +1,23 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  # Namespace for SimpleCov result formatters. Built-in formatters live
-  # below this module; custom formatters should respond to `#format(result)`
-  # and can be wired up via `SimpleCov.formatter=`.
-  # TODO: Documentation on how to build your own formatters
   module Formatter
-    # Formatters can be configured either as classes (instantiated
-    # fresh for every report) or as ready-built instances — the only
-    # way to reach constructor options like
-    # `HTMLFormatter.new(silent: true)`. See #1240.
+    # Formatters are configured either as classes, instantiated fresh for every
+    # report, or as ready-built instances, the only way to reach constructor
+    # options like `HTMLFormatter.new(silent: true)` (#1240).
     def self.instance_for(formatter)
-      formatter.is_a?(Class) ? formatter.new : formatter
+      instantiable?(formatter) ? formatter.new : formatter
     end
 
-    # Normalize a class or instance, then dispatch the result to it.
+    # mutant:disable
+    # `Class` cannot itself be subclassed, so `instance_of?(Class)` answers for
+    # every object exactly as `is_a?(Class)` does: a difference no example can
+    # show, which is why it is disabled here rather than pinned by a test.
+    def self.instantiable?(formatter)
+      formatter.is_a?(Class)
+    end
+    private_class_method :instantiable?
+
     def self.format(formatter, result)
       instance_for(formatter).format(result)
     end
@@ -24,3 +27,4 @@ end
 require_relative "formatter/simple_formatter"
 require_relative "formatter/multi_formatter"
 require_relative "formatter/json_formatter"
+require_relative "formatter/baseline_formatter"

data/lib/simplecov/group_names.rb

@@ -1,32 +1,33 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  # Semantic names owned by result processing rather than user configuration.
   module GroupNames
     UNGROUPED = "Ungrouped"
 
-  module_function
+    extend self
 
-    # Group names are Hash keys, report labels, and JSON object keys all at
-    # once, so they are normalized to Strings up front: a Symbol spelling
-    # (`group :Controllers`) means the String, and anything else has no
-    # sensible serialized form. Normalizing before `validate!` also keeps
-    # `group :Ungrouped` from slipping past the reservation below.
+    # Group names are Hash keys, report labels, and JSON object keys all at once,
+    # so they are normalized to Strings up front: a Symbol spelling means the
+    # String, and anything else has no sensible serialized form. Normalizing
+    # before `validate!` also keeps `group :Ungrouped` from slipping past the
+    # reservation below.
     def normalize(group_name)
       case group_name
       when String then group_name
       when Symbol then group_name.to_s
       else
-        raise SimpleCov::ConfigurationError,
-              "Group names must be Strings, got #{group_name.inspect} (#{group_name.class})"
+        raise ConfigurationError,
+          "Group names must be Strings, got #{group_name.inspect} (#{group_name.class})"
       end
     end
 
+    # Each name in turn, rather than asking the collection: a String asked
+    # whether it "includes" the reserved name answers about its own characters.
     def validate!(group_names)
-      return group_names unless group_names.include?(UNGROUPED)
+      return group_names unless group_names.any? { |name| name.eql?(UNGROUPED) }
 
-      raise SimpleCov::ConfigurationError,
-            "#{UNGROUPED.inspect} is reserved for files that do not match a configured group"
+      raise ConfigurationError,
+        "#{UNGROUPED.inspect} is reserved for files that do not match a configured group"
     end
   end
 end

data/lib/simplecov/history.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "time"
+require_relative "atomic_file"
+
+module SimpleCov
+  # A bounded record of past runs, coverage/.history.json (#1267): one entry
+  # per reported run carrying the per-criterion totals, the per-group and
+  # per-file percentages, a timestamp, and the branch and commit when the
+  # project is a git checkout. It is what turns "did the number move since the
+  # very last run" into direction of travel.
+  #
+  # Entries are capped and written atomically, and a corrupt or foreign file
+  # degrades to an empty history with a warning rather than crashing the
+  # at_exit hook, the same tolerance `.last_run.json` has. The file is
+  # deliberately plain committable JSON.
+  module History
+    ENVELOPE = "simplecov_history"
+    FORMAT_VERSION = 1
+
+    class << self
+      def history_path
+        File.join(SimpleCov.coverage_path, ".history.json")
+      end
+
+      def record(result)
+        limit = SimpleCov.history_limit
+        return if limit.zero?
+
+        entries = read
+        entries << entry_for(result)
+        write(entries.last(limit))
+      end
+
+      def read
+        return [] unless File.exist?(history_path)
+
+        content = File.read(history_path)
+        return [] if content.match?(/\A\s*\z/)
+
+        entries = JSON.parse(content).dig(ENVELOPE, "entries")
+        entries.instance_of?(Array) ? entries : invalid_history
+      rescue JSON::ParserError
+        invalid_history
+      end
+
+      # The recorded entries plus `result` as the newest, capped, and without
+      # writing anything: what the report artifacts embed, so the embedded history
+      # includes the run being reported even though recording happens later.
+      def entries_with(result)
+        (read << entry_for(result)).last(SimpleCov.history_limit)
+      end
+
+      # A detached HEAD reports its branch as nil rather than the literal "HEAD"
+      # most CI checkouts would record.
+      def git_info
+        branch = git("rev-parse", "--abbrev-ref", "HEAD")
+        branch = nil if branch.eql?("HEAD")
+        [branch, git("rev-parse", "HEAD")]
+      end
+
+      private
+
+      def entry_for(result)
+        branch, commit = git_info
+        {
+          # getutc, not utc: the destructive variant would rezone the Time the result
+          # still holds.
+          "created_at" => result.created_at.getutc.iso8601,
+          "branch" => branch,
+          "commit" => commit,
+          "totals" => measured_percents(result),
+          "groups" => result.groups.transform_values { |files| measured_percents(files) },
+          "files" => files_percents(result)
+        }
+      end
+
+      def measured_percents(stats_source)
+        stats_source.coverage_statistics.to_h do |criterion, stats|
+          [criterion.to_s, SimpleCov.round_coverage(stats.percent)]
+        end
+      end
+
+      def files_percents(result)
+        measured = result.coverage_statistics
+        initial = {} #: Hash[String, Hash[String, Numeric]]
+        result.files.each_with_object(initial) do |file, percents|
+          stats = file.coverage_statistics
+          percents[file.project_filename] = measured.to_h do |criterion, _run_total|
+            [criterion.to_s, SimpleCov.round_coverage(stats.fetch(criterion).percent)]
+          end
+        end
+      end
+
+      def write(entries)
+        payload = {ENVELOPE => {"format_version" => FORMAT_VERSION, "entries" => entries}}
+        AtomicFile.write(history_path, "#{JSON.pretty_generate(payload)}\n")
+      end
+
+      def invalid_history
+        warn "[SimpleCov]: Warning! Parsing JSON content of .history.json failed, starting a fresh history"
+        []
+      end
+
+      def git(*)
+        output, status = Open3.capture2e("git", "-C", SimpleCov.root.to_s, *)
+        output.rstrip if status.success?
+      rescue
+        nil
+      end
+    end
+  end
+end

data/lib/simplecov/last_run.rb

@@ -4,25 +4,23 @@ require "json"
 require_relative "atomic_file"
 
 module SimpleCov
-  # Reads and writes coverage/.last_run.json — the previous run's coverage
-  # percentages used by MaximumCoverageDropCheck.
   module LastRun
     class << self
       def last_run_path
         File.join(SimpleCov.coverage_path, ".last_run.json")
       end
 
+      # The maximum_coverage_drop check digs into a Hash, so anything else in a
+      # corrupt or hand-edited file counts as "no previous run" rather than
+      # crashing the at_exit hook.
       def read
         return nil unless File.exist?(last_run_path)
 
         json = File.read(last_run_path)
-        return nil if json.strip.empty?
+        return nil if json.match?(/\A\s*\z/)
 
         parsed = JSON.parse(json, symbolize_names: true)
-        # The maximum_coverage_drop check digs into a Hash, so anything
-        # else in a corrupt or hand-edited file counts as "no previous
-        # run" rather than crashing the at_exit hook.
-        parsed.is_a?(Hash) ? parsed : invalid_last_run
+        parsed.instance_of?(Hash) ? parsed : invalid_last_run
       rescue JSON::ParserError
         invalid_last_run
       end
@@ -31,11 +29,10 @@ module SimpleCov
         AtomicFile.write(last_run_path, "#{JSON.pretty_generate(json)}\n")
       end
 
-    private
+      private
 
       def invalid_last_run
         warn "[SimpleCov]: Warning! Parsing JSON content of .last_run.json failed, ignoring the previous run"
-        nil
       end
     end
   end

data/lib/simplecov/lines_classifier.rb

@@ -3,8 +3,8 @@
 require_relative "directive"
 
 module SimpleCov
-  # Classifies whether lines are relevant for code coverage analysis.
-  # Comments & whitespace lines, and :nocov: token blocks, are considered not relevant.
+  # Classifies whether lines are relevant for code coverage analysis. Comments,
+  # whitespace lines, and disabled blocks are considered not relevant.
   class LinesClassifier
     RELEVANT = 0
     NOT_RELEVANT = nil
@@ -27,45 +27,60 @@ module SimpleCov
       /^(\s*)#(\s*)(:#{SimpleCov.current_nocov_token}:)/o
     end
 
+    # A marker is itself a comment, so the cheap whitespace-or-comment test gates
+    # the token match: a line of real code cannot be a marker, and no longer pays
+    # to be checked against one. That matters because this runs per line of every
+    # tracked-but-unloaded file, once in every process of a parallel run.
     def self.no_cov_line?(line)
       no_cov_line.match?(line)
     rescue ArgumentError
-      # E.g., line contains an invalid byte sequence in UTF-8
       false
     end
 
     def self.whitespace_line?(line)
       WHITESPACE_OR_COMMENT_LINE.match?(line)
     rescue ArgumentError
-      # E.g., line contains an invalid byte sequence in UTF-8
       false
     end
 
+    class SkipState
+      def initialize
+        @skipping = false
+      end
+
+      def skipping?
+        @skipping
+      end
+
+      def toggle
+        @skipping = !@skipping
+      end
+    end
+
+    # The skip state lives in a one-slot box owned by this call rather than in an
+    # ivar, so one classifier instance can serve concurrent `classify` calls
+    # without the toggles interleaving.
     def classify(lines)
       lines = lines.to_a
       directive_disabled = directive_disabled_line_set(lines)
-      # The `:nocov:` skip state lives in a one-slot box owned by this
-      # call, not in an ivar, so one classifier instance can serve
-      # concurrent `classify` calls without the toggles interleaving.
-      skip_state = [false]
+      skip_state = SkipState.new
 
       lines.map.with_index(1) do |line, line_number|
         classify_line(line, line_number, directive_disabled, skip_state)
       end
     end
 
-  private
+    private
 
-    # A `:nocov:` marker is itself a comment, so the cheap
-    # whitespace-or-comment test can gate the token match: a line of real
-    # code cannot be a marker, and no longer pays to be checked against
-    # one. That matters because this runs per line of every
-    # tracked-but-unloaded file, once in every process of a parallel run.
+    # mutant:disable — `NOT_RELEVANT` is nil, so naming it and writing
+    # the literal are the same value, and so is an `unless` that falls
+    # off its end. The name is kept because it says which of the two
+    # verdicts a line got, which nil alone does not.
     def classify_line(line, line_number, directive_disabled, skip_state)
       if self.class.whitespace_line?(line)
-        skip_state[0] = !skip_state[0] if self.class.no_cov_line?(line)
+        skip_state.toggle if self.class.no_cov_line?(line)
         NOT_RELEVANT
-      elsif skip_state[0] || directive_disabled.include?(line_number)
+      elsif skip_state.skipping? || directive_disabled.include?(line_number)
         NOT_RELEVANT
       else
         RELEVANT

data/lib/simplecov/load_global_config.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-# `~/.simplecov` was historically resolved via a three-step fallback chain
-# (HOME, then `Etc.getpwuid.dir`, then `~$USER`) for hostile container
-# environments circa 2017. Modern CRuby/JRuby/TruffleRuby all set HOME
-# reliably, so trust it and skip silently when it isn't there. An ENV
-# check rather than Dir.home: JRuby raises from Dir.home with HOME
-# unset, and `File.expand_path("~")` raises for a set-but-empty HOME
-# (some container/CI images), which must not break `require "simplecov"`.
+# `~/.simplecov` was historically resolved through a three-step fallback chain
+# for hostile container environments circa 2017. Modern CRuby and JRuby both set
+# HOME reliably, so trust it and skip silently when it isn't there. An ENV check
+# rather than `Dir.home`: JRuby raises from `Dir.home` with HOME unset, and
+# `File.expand_path("~")` raises for a set-but-empty HOME, which must not break
+# `require "simplecov"`.
+
 unless ENV.fetch("HOME", "").empty?
   # simplecov:disable — only fires when ~/.simplecov exists, which is
   # developer-machine-dependent (we can't rely on it for the dogfood).

data/lib/simplecov/parallel_adapters/base.rb

@@ -3,73 +3,45 @@
 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.
+    # Everything not overridden falls back to behaving like a single-process
+    # run. Adapters are classes, used as singletons and never instantiated.
     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
 
-        # Does `wait_for_siblings` block until every sibling PROCESS has
-        # exited (so no further resultset can appear)? When true, the
-        # reporting worker can accept a settled resultset count below
-        # `expected_worker_count` as final instead of waiting out the whole
-        # `parallel_wait_timeout` for workers that produced no coverage.
-        # Defaults to false (no native wait; the poll is the only signal).
+        # Whether `wait_for_siblings` blocks until every sibling process has exited,
+        # so no further resultset can appear. When true, the reporting worker can
+        # accept a settled resultset count below `expected_worker_count` as final
+        # instead of waiting out the whole `parallel_wait_timeout`.
         def native_wait?
           false
         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
 
-        # The user's explicit `SimpleCov.parallel_tests false` opt-out,
-        # which every adapter's `active?` honors before its own
-        # detection.
+        # mutant:disable — `false` is a singleton, so comparing against
+        # it answers the same through ==, eql? and equal?, and no
+        # example can tell the three apart.
         def forced_off?
           SimpleCov.parallel_tests == false
         end
 
-        # Shared implementation of the PARALLEL_TEST_GROUPS convention
-        # both built-in adapters follow for `expected_worker_count`.
-        # Unset, empty, non-numeric, and non-positive values all mean 1:
-        # an unparseable value must not yield 0 workers, which would end
-        # the sibling wait before it started.
+        # Unset, empty, non-numeric, and non-positive values all mean 1: an
+        # unparseable value must not yield 0 workers, which would end the sibling
+        # wait before it started.
         def parallel_test_groups_count
-          count = Integer(ENV.fetch("PARALLEL_TEST_GROUPS", ""), exception: false)
+          count = Integer(ENV.fetch("PARALLEL_TEST_GROUPS", nil), exception: false)
           count&.positive? ? count : 1
         end
       end

data/lib/simplecov/parallel_adapters/generic.rb

@@ -5,21 +5,10 @@ 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.
+    # `TEST_ENV_NUMBER` / `PARALLEL_TEST_GROUPS` env-var convention but ship no
+    # Ruby API for SimpleCov to hook. `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.
     class GenericAdapter < Base
       class << self
         def active?
@@ -28,9 +17,9 @@ module SimpleCov
           ENV.key?("TEST_ENV_NUMBER")
         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.
+        # parallel_tests sets the first worker's TEST_ENV_NUMBER to "", and runners
+        # that number from 1 use "1". Both shapes match; any other value is a
+        # non-first worker.
         def first_worker?
           ["", "1"].include?(ENV.fetch("TEST_ENV_NUMBER", nil))
         end

data/lib/simplecov/parallel_adapters/parallel_tests.rb

@@ -4,47 +4,37 @@ require_relative "base"
 
 module SimpleCov
   module ParallelAdapters
-    # Adapter for [grosser/parallel_tests](https://github.com/grosser/parallel_tests).
-    # This is the historical default — SimpleCov has special-cased
-    # parallel_tests since 0.18 — and remains the most precise option for
-    # projects on it. Detection requires the full native coordination
-    # contract: the `ParallelTests` constant has been loaded,
-    # `TEST_ENV_NUMBER` is set, and `PARALLEL_PID_FILE` is set. The pid-file
-    # path is required because the native wait API reads it with `ENV.fetch`.
-    # When a runner only provides the env-var convention, GenericAdapter is
-    # the correct coordination path.
+    # Adapter for grosser/parallel_tests, the historical default and still the
+    # most precise option for projects on it. Detection requires the full native
+    # coordination contract: the `ParallelTests` constant loaded,
+    # `TEST_ENV_NUMBER` set, and `PARALLEL_PID_FILE` set, because the native
+    # wait API reads the pid-file path with `ENV.fetch`. A runner that only
+    # provides the env-var convention belongs to GenericAdapter.
     class ParallelTestsAdapter < Base
       class << self
         def active?
           return false if forced_off?
 
           ensure_loaded
-          # !! to coerce `defined?` (returns nil or "constant") to a proper bool.
           !!(defined?(::ParallelTests) && native_parallel_tests_environment?)
         end
 
-        # Pick the *first* started process to do the final-result work,
-        # not the last. The parallel_tests README recommends
-        # `first_process?` for "do something once after every worker
-        # finishes" hooks, so user code that has its own
-        # `wait_for_other_processes_to_finish` in an `RSpec.after(:suite)`
-        # overwhelmingly waits in the first process — picking the same
-        # side avoids the cross-process deadlock #922 reported. Also
-        # handles `PARALLEL_TEST_GROUPS=1` naturally (the only worker's
-        # `TEST_ENV_NUMBER` is "" and `first_process?` tests for that
-        # empty string).
+        # The first started process, not the last. The parallel_tests README
+        # recommends `first_process?` for "do something once after every worker
+        # finishes" hooks, so user code with its own
+        # `wait_for_other_processes_to_finish` overwhelmingly waits in the first
+        # process, and picking the same side avoids the cross-process deadlock #922
+        # reported.
         def first_worker?
-          ::ParallelTests.first_process?
+          ParallelTests.first_process?
         end
 
         def wait_for_siblings
           return unless native_parallel_tests_environment?
 
-          ::ParallelTests.wait_for_other_processes_to_finish
+          ParallelTests.wait_for_other_processes_to_finish
         end
 
-        # The native wait blocks until every sibling process exits, but only
-        # when the pid-file contract is present (see `wait_for_siblings`).
         def native_wait?
           native_parallel_tests_environment?
         end
@@ -53,30 +43,19 @@ module SimpleCov
           parallel_test_groups_count
         end
 
-        # Auto-require `parallel_tests` when it's installed AND the env
-        # vars it sets are present, so callers can rely on
-        # `defined?(::ParallelTests)` downstream. 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,
-        # the parallel_rspec gem which intentionally mirrors the env-var
-        # convention), so a missing gem is treated as "user isn't using
-        # parallel_tests" — silently skip and let GenericAdapter handle
-        # it. Users who want to override the auto-detect can set
-        # `SimpleCov.parallel_tests true` (force on) or `false` (force
-        # off). See #1018.
+        # parallel_tests is an optional dependency, and `TEST_ENV_NUMBER` /
+        # `PARALLEL_TEST_GROUPS` are commonly set for other reasons, so a missing
+        # gem is treated as "user isn't using parallel_tests": stay quiet and let
+        # GenericAdapter handle it. Warning here regressed users who use those env
+        # vars for their own subprocess coordination (#1018).
         def ensure_loaded
-          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 — env-var-only path
+          return if defined?(::ParallelTests)
+          return if forced_off?
           return unless SimpleCov.parallel_tests || env_suggests_parallel_tests?
 
           # simplecov:disable — only fires under a real parallel_tests setup
           require "parallel_tests"
         rescue LoadError
-          # Gem isn't installed; stay quiet — warning here regressed
-          # users who use those env vars for their own subprocess
-          # coordination.
           # simplecov:enable
         end