simplecov 0.22.0 → 1.1.1

data/lib/simplecov/configuration/merging.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  # Result merging and subprocess / parallel-test coordination:
+  # `merging`, `merge_subprocesses`, `merge_timeout`, `parallel_tests`.
+  module Configuration
+    #
+    # Get or set whether SimpleCov should hook `Process._fork` to
+    # attach itself to subprocesses. Required when the suite uses
+    # parallel test workers (e.g. Rails' `parallelize(workers:)`).
+    # Defaults to false.
+    #
+    def merge_subprocesses(value = nil)
+      return @enable_for_subprocesses if defined?(@enable_for_subprocesses) && value.nil?
+
+      @enable_for_subprocesses = value || false
+    end
+
+    # @api private — predicate used by `start_tracking` to decide
+    # whether to install the fork hook.
+    def enabled_for_subprocesses?
+      defined?(@enable_for_subprocesses) ? @enable_for_subprocesses : false
+    end
+
+    #
+    # Get or set whether SimpleCov should auto-require the
+    # `parallel_tests` gem when it sees `TEST_ENV_NUMBER` /
+    # `PARALLEL_TEST_GROUPS` in the environment. Defaults to auto-detect
+    # (nil). See #1018.
+    #
+    def parallel_tests(value = :__no_arg__)
+      return defined?(@parallel_tests) ? @parallel_tests : nil if value == :__no_arg__
+
+      @parallel_tests = value
+    end
+
+    # DEPRECATED: alias for `merge_subprocesses`. Same value/behavior.
+    def enable_for_subprocesses(value = nil)
+      SimpleCov::Deprecation.warn("`SimpleCov.enable_for_subprocesses` is deprecated. " \
+                                  "Replace with `SimpleCov.merge_subprocesses` (same value, same behavior).")
+      merge_subprocesses(value)
+    end
+
+    #
+    # Get or set whether to merge results from multiple test suites
+    # (test:units, test:functionals, cucumber, ...) into a single
+    # coverage report. Defaults to true.
+    #
+    def merging(use = nil)
+      @use_merging = use unless use.nil?
+      @use_merging = true unless defined?(@use_merging) && @use_merging == false
+      @use_merging
+    end
+
+    #
+    # Get or set whether SimpleCov's selected final process owns merge processing:
+    # waiting for sibling workers, building the merged result, formatting,
+    # enforcing thresholds, and writing `.last_run.json`.
+    #
+    # Defaults to true, except for recognized multi-worker parallel runs
+    # that explicitly write to a custom coverage destination while merging
+    # is enabled. Those runs are likely using an external `SimpleCov.collate`
+    # step to finalize the merge.
+    #
+    def finalize_merge(value = :__no_arg__)
+      unless value == :__no_arg__
+        @finalize_merge = value
+        @finalize_merge_explicit = true
+      end
+
+      return @finalize_merge if defined?(@finalize_merge_explicit) && @finalize_merge_explicit
+
+      inferred = inferred_finalize_merge?
+      warn_about_inferred_finalize_merge unless inferred
+      inferred
+    end
+
+    def finalize_merge?
+      finalize_merge
+    end
+
+    # @api private
+    def merge_finalization_owner?
+      collating_result? || (finalize_merge? && final_result_process?)
+    end
+
+    # DEPRECATED: alias for `merging`. Same value, same behavior.
+    # Delegating (rather than duplicating the body) also fixes the
+    # return value: this used to return nil where `merging` returns
+    # false, because the final expression was the skipped guard
+    # assignment rather than the stored value.
+    def use_merging(use = nil)
+      SimpleCov::Deprecation.warn("`SimpleCov.use_merging` is deprecated. " \
+                                  "Replace with `SimpleCov.merging` (same value, same behavior).")
+      merging(use)
+    end
+
+    #
+    # Defines the maximum age (in seconds) of a resultset to still be
+    # included in merged results. Default is 600 seconds (10 minutes).
+    #
+    def merge_timeout(seconds = nil)
+      @merge_timeout = seconds if seconds.is_a?(Integer)
+      @merge_timeout ||= 600
+    end
+
+    #
+    # Defines how long (in seconds) the reporting process waits for the
+    # remaining parallel-test workers to write their resultsets before it
+    # proceeds with a partial merge. Default is 60 seconds. Raise it when a
+    # slow worker routinely finishes well after the others, so its coverage
+    # is still included and the minimum / maximum coverage checks aren't
+    # skipped against a partial total.
+    #
+    def parallel_wait_timeout(seconds = nil)
+      @parallel_wait_timeout = seconds if seconds.is_a?(Integer)
+      @parallel_wait_timeout ||= 60
+    end
+
+  private
+
+    def inferred_finalize_merge?
+      return true unless merging
+
+      adapter = SimpleCov::ParallelAdapters.current
+      return true unless adapter
+      return true unless adapter.expected_worker_count > 1
+      return true unless parallel_worker_environment?
+      return true unless explicit_custom_coverage_destination?
+
+      false
+    end
+
+    def parallel_worker_environment?
+      ENV.key?("TEST_ENV_NUMBER") || ENV.key?("PARALLEL_TEST_GROUPS")
+    end
+
+    def explicit_custom_coverage_destination?
+      return false unless explicit_coverage_destination?
+
+      coverage_path != File.expand_path("coverage", root)
+    end
+
+    def explicit_coverage_destination?
+      (defined?(@coverage_path_explicit) && @coverage_path_explicit) ||
+        (defined?(@coverage_dir_explicit) && @coverage_dir_explicit)
+    end
+
+    def warn_about_inferred_finalize_merge
+      return if defined?(@finalize_merge_inference_warned) && @finalize_merge_inference_warned
+      return unless print_errors
+
+      @finalize_merge_inference_warned = true
+      warn SimpleCov::Color.colorize(inferred_finalize_merge_warning, :yellow)
+    end
+
+    def inferred_finalize_merge_warning
+      "SimpleCov inferred `finalize_merge false` because this parallel worker is merging " \
+        "into a custom coverage destination. Set `SimpleCov.finalize_merge false` to keep " \
+        "external collation ownership, or `SimpleCov.finalize_merge true` if this worker " \
+        "should wait, merge, format, enforce thresholds, and write `.last_run.json`. " \
+        "See https://github.com/simplecov-ruby/simplecov#merge-finalization-ownership."
+    end
+  end
+end

data/lib/simplecov/configuration/thresholds.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  # Coverage threshold configuration: `minimum_coverage`,
+  # `maximum_coverage`, `expected_coverage`, `maximum_coverage_drop`,
+  # `minimum_coverage_by_file`, `minimum_coverage_by_group`,
+  # `refuse_coverage_drop`, and friends.
+  module Configuration
+    #
+    # Defines the minimum overall coverage required for the testsuite to pass.
+    # Returns non-zero if the current coverage is below this threshold.
+    # Default is 0% (disabled).
+    #
+    def minimum_coverage(coverage = nil)
+      return @minimum_coverage ||= {} unless coverage
+
+      @minimum_coverage = normalized_threshold(coverage, "minimum_coverage")
+    end
+
+    def raise_on_invalid_coverage(coverage, coverage_setting)
+      coverage.each_key { |criterion| raise_if_criterion_disabled(criterion) }
+      coverage.each_value do |percent|
+        minimum_possible_coverage_exceeded(coverage_setting) if percent && percent > 100
+      end
+    end
+
+    #
+    # Defines the maximum overall coverage allowed for the testsuite to
+    # pass. Useful paired with `minimum_coverage` (or via
+    # `expected_coverage`) to pin coverage to an exact value, so an
+    # unexpected jump up fails the build. See #187.
+    #
+    def maximum_coverage(coverage = nil)
+      return @maximum_coverage ||= {} unless coverage
+
+      @maximum_coverage = normalized_threshold(coverage, "maximum_coverage")
+    end
+
+    #
+    # Pins the suite to an exact coverage figure by setting both
+    # `minimum_coverage` and `maximum_coverage`. See #187.
+    #
+    def expected_coverage(coverage = nil)
+      return minimum_coverage if coverage.nil?
+
+      minimum_coverage(coverage)
+      maximum_coverage(coverage)
+    end
+
+    #
+    # Defines the maximum coverage drop at once allowed for the
+    # testsuite to pass. Default is 100% (disabled).
+    #
+    def maximum_coverage_drop(coverage_drop = nil)
+      return @maximum_coverage_drop ||= {} unless coverage_drop
+
+      @maximum_coverage_drop = normalized_threshold(coverage_drop, "maximum_coverage_drop")
+    end
+
+    #
+    # Defines the minimum coverage per file required for the testsuite
+    # to pass. Accepts a Numeric (global threshold on the primary
+    # criterion), a Symbol-keyed Hash (per-criterion globals), or a
+    # Hash mixing Symbol keys with String / Regexp keys to declare
+    # per-path overrides. See README and #575.
+    #
+    def minimum_coverage_by_file(coverage = nil)
+      return @minimum_coverage_by_file ||= {} unless coverage
+
+      coverage = {primary_coverage => coverage} if coverage.is_a?(Numeric)
+      defaults, overrides = partition_per_file_thresholds(coverage)
+
+      SimpleCov::Deprecation.warn("`SimpleCov.minimum_coverage_by_file` is deprecated. " \
+                                  "Replace it with:\n#{per_file_coverage_replacement(defaults, overrides)}")
+
+      raise_on_invalid_coverage(defaults, "minimum_coverage_by_file")
+      overrides.each_value { |criteria| raise_on_invalid_coverage(criteria, "minimum_coverage_by_file") }
+
+      @minimum_coverage_by_file = defaults
+      @minimum_coverage_by_file_overrides = overrides
+    end
+
+    # Returns the per-path overrides set via `minimum_coverage_by_file`.
+    def minimum_coverage_by_file_overrides
+      @minimum_coverage_by_file_overrides ||= {}
+    end
+
+    #
+    # Defines the minimum coverage per group required for the testsuite
+    # to pass. Default is 0% (disabled).
+    #
+    def minimum_coverage_by_group(coverage = nil)
+      return @minimum_coverage_by_group ||= {} unless coverage
+
+      SimpleCov::Deprecation.warn("`SimpleCov.minimum_coverage_by_group` is deprecated. " \
+                                  "Replace it with:\n#{per_group_coverage_replacement(coverage)}")
+      @minimum_coverage_by_group = coverage.to_h do |group_name, group_coverage|
+        [GroupNames.normalize(group_name), normalized_threshold(group_coverage, "minimum_coverage_by_group")]
+      end
+    end
+
+    #
+    # Refuses any coverage drop. Coverage is only allowed to increase.
+    #
+    def refuse_coverage_drop(*criteria)
+      criteria = coverage_criteria if criteria.empty?
+      maximum_coverage_drop(criteria.to_h { |c| [c, 0] })
+    end
+
+  private
+
+    # Shared normalize-and-validate step behind every threshold setter:
+    # a bare Numeric targets the primary criterion, and the resulting
+    # per-criterion hash is validated before it is stored.
+    def normalized_threshold(coverage, setting)
+      coverage = {primary_coverage => coverage} if coverage.is_a?(Numeric)
+      raise_on_invalid_coverage(coverage, setting)
+      coverage
+    end
+
+    # Split a `minimum_coverage_by_file` argument into Symbol-keyed
+    # criterion defaults and String/Regexp-keyed per-path overrides;
+    # normalize Numeric override values to `{primary_coverage => N}`
+    # so downstream code only has one shape to handle.
+    def partition_per_file_thresholds(coverage)
+      coverage.each_key { |key| validate_per_file_key(key) }
+      pairs = coverage.partition { |key, _| key.is_a?(Symbol) }
+      # The assertions restate what the partition predicate guarantees:
+      # Symbol keys carry per-criterion Numeric defaults, the rest are paths.
+      defaults = pairs[0].to_h #: coverage_thresholds
+      raw = pairs[1].to_h #: Hash[String | Regexp, Numeric | coverage_thresholds]
+      overrides = raw.transform_values { |value| value.is_a?(Numeric) ? {primary_coverage => value} : value }
+      [defaults, overrides]
+    end
+
+    def validate_per_file_key(key)
+      return if key.is_a?(Symbol) || key.is_a?(String) || key.is_a?(Regexp)
+
+      raise SimpleCov::ConfigurationError,
+            "minimum_coverage_by_file keys must be Symbol (criterion), String, or Regexp; got #{key.inspect}"
+    end
+
+    def minimum_possible_coverage_exceeded(coverage_option)
+      warn "The coverage you set for #{coverage_option} is greater than 100%"
+    end
+
+    # Render the `coverage` configuration equivalent to a (deprecated)
+    # `minimum_coverage_by_file` argument so the deprecation warning can be
+    # copy-pasted verbatim into the user's config.
+    def per_file_coverage_replacement(defaults, overrides)
+      by_criterion = {} #: Hash[Symbol, Array[String]]
+      defaults.each { |criterion, percent| (by_criterion[criterion] ||= []) << "minimum_per_file #{percent}" }
+      overrides.each do |target, criteria|
+        criteria.each do |criterion, percent|
+          (by_criterion[criterion] ||= []) << "minimum_per_file #{percent}, only: #{target.inspect}"
+        end
+      end
+      render_coverage_blocks(by_criterion)
+    end
+
+    # Same, for a (deprecated) `minimum_coverage_by_group` argument.
+    def per_group_coverage_replacement(coverage)
+      by_criterion = {} #: Hash[Symbol, Array[String]]
+      coverage.each do |group_name, thresholds|
+        normalized = (thresholds.is_a?(Numeric) ? {primary_coverage => thresholds} : thresholds) #: coverage_thresholds
+        normalized.each do |criterion, percent|
+          (by_criterion[criterion] ||= []) << "minimum_per_group #{percent}, only: #{group_name.inspect}"
+        end
+      end
+      render_coverage_blocks(by_criterion)
+    end
+
+    def render_coverage_blocks(by_criterion)
+      by_criterion.map do |criterion, statements|
+        "  coverage(#{criterion.inspect}) { #{statements.join('; ')} }"
+      end.join("\n")
+    end
+  end
+end