simplecov 0.22.0 → 1.0.0.rc1

data/lib/simplecov/configuration/formatting.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "../formatter/multi_formatter"
+
+module SimpleCov
+  # Formatter selection (`formatter` / `formatters`), reporting toggles
+  # (`print_errors`), and the deprecated `# :nocov:` token hook.
+  module Configuration
+    attr_writer :formatter, :print_error_status
+
+    #
+    # Gets or sets the configured formatter. Pass `false` (or `nil`) to
+    # opt out of formatting entirely — worker processes in big parallel
+    # CI setups (see #964) only need their `.resultset.json` on disk so
+    # a final `SimpleCov.collate` job can produce the report; running
+    # them without a formatter saves the per-job HTML/multi-formatter
+    # overhead.
+    #
+    def formatter(formatter = :__no_arg__)
+      return @formatter if formatter == :__no_arg__
+
+      @formatter = formatter || nil # normalize `false` to `nil`
+    end
+
+    # Sets the configured formatters. Pass `[]` to opt out of
+    # formatting entirely; see `formatter` for the rationale.
+    def formatters(formatters = :__no_arg__)
+      return Array(formatter) if formatters == :__no_arg__
+
+      self.formatters = formatters
+      formatters
+    end
+
+    # Sets the configured formatters. Equivalent to `formatters [...]`.
+    def formatters=(formatters)
+      @formatter = formatters.empty? ? nil : SimpleCov::Formatter::MultiFormatter.new(formatters)
+    end
+
+    #
+    # Get or set whether SimpleCov colorizes its stderr diagnostics. Accepts
+    # `true` (always on), `false` (always off), or `:auto` (default: defer
+    # to `SimpleCov::Color`, which checks `$stderr.tty?` with `NO_COLOR`
+    # and `FORCE_COLOR` overrides). An explicit `true`/`false` wins over
+    # both auto-detection and the env vars, which is the right escape
+    # hatch when stderr is being piped through a wrapper that still
+    # renders ANSI in its own terminal (parallel_tests with
+    # `--combine-stderr`, log multiplexers, some CI runners). See #1157.
+    #
+    def color(value = :__no_arg__)
+      return defined?(@color) ? @color : :auto if value == :__no_arg__
+
+      @color = value
+    end
+
+    #
+    # Get or set whether SimpleCov prints its own diagnostic warnings to
+    # stderr. Covers per-check threshold violations, the trailing
+    # "SimpleCov failed with exit ..." summary, and the deferred-report /
+    # previous-error notices. Defaults to true. Set to false to silence
+    # SimpleCov entirely when parsing tooling output (see issue #1155).
+    #
+    def print_errors(value = :__no_arg__)
+      return defined?(@print_error_status) ? @print_error_status : true if value == :__no_arg__
+
+      @print_error_status = value
+    end
+
+    #
+    # Get or set whether `coverage.json` includes the full source-text
+    # array for every file. Defaults to true. Set to false when a
+    # downstream tool reads the project's source files directly and
+    # only needs the coverage metrics, so `coverage.json` doesn't carry
+    # a copy of the source tree (which dominates the payload on larger
+    # projects).
+    #
+    # The HTML viewer's `coverage_data.js` always includes source —
+    # the client-side renderer needs it. Only `coverage.json` honors
+    # this setting.
+    #
+    #     SimpleCov.start do
+    #       source_in_json false
+    #     end
+    #
+    def source_in_json(value = :__no_arg__)
+      return defined?(@source_in_json) ? @source_in_json : true if value == :__no_arg__
+
+      @source_in_json = value
+    end
+
+    # DEPRECATED: alias for `print_errors`. Same value, same behavior.
+    def print_error_status
+      warn "#{Kernel.caller.first}: [DEPRECATION] `SimpleCov.print_error_status` is deprecated. " \
+           "Replace with `SimpleCov.print_errors` (same value)."
+      defined?(@print_error_status) ? @print_error_status : true
+    end
+
+    #
+    # DEPRECATED: configure `# :nocov:` token override. Prefer
+    # `# simplecov:disable` / `# simplecov:enable` block comments (see
+    # SimpleCov::Directive). The `# :nocov:` toggle and this hook will
+    # be removed in a future release.
+    #
+    def nocov_token(nocov_token = nil)
+      warn "#{Kernel.caller.first}: [DEPRECATION] `SimpleCov.nocov_token` and `SimpleCov.skip_token` are deprecated. " \
+           "Replace with `# simplecov:disable` / `# simplecov:enable` block comments."
+      current_nocov_token(nocov_token)
+    end
+    alias skip_token nocov_token
+
+    # Internal accessor used by SimpleCov to recognise `# :nocov:`
+    # markers without emitting the public-API deprecation warning. Will
+    # be removed alongside the deprecated `nocov_token` setter.
+    def current_nocov_token(value = nil)
+      return @nocov_token if defined?(@nocov_token) && value.nil?
+
+      @nocov_token = value || "nocov"
+    end
+  end
+end

data/lib/simplecov/configuration/ignored_entries.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  # Coverage-entry filters scoped to branch / method criteria. See
+  # `ignore_branches` and `ignore_methods`, and #1033 /
+  # #1046 for the synthetic-entry detection rationale.
+  module Configuration
+    # Branch types accepted by `ignore_branches`.
+    IGNORABLE_BRANCH_TYPES = %i[implicit_else eval_generated].freeze
+    # Method types accepted by `ignore_methods`.
+    IGNORABLE_METHOD_TYPES = %i[eval_generated].freeze
+
+    # Variadic; multiple calls union. Setting is recorded regardless
+    # of whether branch coverage is enabled at call time. See #1033, #1046.
+    def ignore_branches(*types)
+      types.each { |type| raise_if_branch_type_unsupported(type) }
+      ignored_branches.concat(types).uniq!
+      ignored_branches
+    end
+
+    def ignored_branches
+      @ignored_branches ||= []
+    end
+
+    def ignored_branch?(type)
+      ignored_branches.include?(type)
+    end
+
+    # See `ignore_branches`. The only supported method-type token today
+    # is `:eval_generated`; see #1046 for the rationale.
+    def ignore_methods(*types)
+      types.each { |type| raise_if_method_type_unsupported(type) }
+      ignored_methods.concat(types).uniq!
+      ignored_methods
+    end
+
+    def ignored_methods
+      @ignored_methods ||= []
+    end
+
+    def ignored_method?(type)
+      ignored_methods.include?(type)
+    end
+
+  private
+
+    def raise_if_branch_type_unsupported(type)
+      return if IGNORABLE_BRANCH_TYPES.member?(type)
+
+      raise SimpleCov::ConfigurationError,
+            "Unsupported branch type #{type.inspect} for `ignore_branches`. " \
+            "Supported values are #{IGNORABLE_BRANCH_TYPES.inspect}"
+    end
+
+    def raise_if_method_type_unsupported(type)
+      return if IGNORABLE_METHOD_TYPES.member?(type)
+
+      raise SimpleCov::ConfigurationError,
+            "Unsupported method type #{type.inspect} for `ignore_methods`. " \
+            "Supported values are #{IGNORABLE_METHOD_TYPES.inspect}"
+    end
+  end
+end

data/lib/simplecov/configuration/merging.rb

@@ -0,0 +1,74 @@
+# 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)
+      warn "#{Kernel.caller.first}: [DEPRECATION] `SimpleCov.enable_for_subprocesses` is deprecated. " \
+           "Replace with `SimpleCov.merge_subprocesses` (same value, same behavior)."
+      return @enable_for_subprocesses if defined?(@enable_for_subprocesses) && value.nil?
+
+      @enable_for_subprocesses = value || false
+    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
+
+    # DEPRECATED: alias for `merging`. Same value, same behavior.
+    def use_merging(use = nil)
+      warn "#{Kernel.caller.first}: [DEPRECATION] `SimpleCov.use_merging` is deprecated. " \
+           "Replace with `SimpleCov.merging` (same value, same behavior)."
+      @use_merging = use unless use.nil?
+      @use_merging = true unless defined?(@use_merging) && @use_merging == false
+    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
+  end
+end

data/lib/simplecov/configuration/thresholds.rb

@@ -0,0 +1,174 @@
+# 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
+
+      coverage = {primary_coverage => coverage} if coverage.is_a?(Numeric)
+      raise_on_invalid_coverage(coverage, "minimum_coverage")
+      @minimum_coverage = 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
+
+      coverage = {primary_coverage => coverage} if coverage.is_a?(Numeric)
+      raise_on_invalid_coverage(coverage, "maximum_coverage")
+      @maximum_coverage = 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
+
+      coverage_drop = {primary_coverage => coverage_drop} if coverage_drop.is_a?(Numeric)
+      raise_on_invalid_coverage(coverage_drop, "maximum_coverage_drop")
+      @maximum_coverage_drop = 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)
+
+      warn "#{Kernel.caller.first}: [DEPRECATION] `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
+
+      warn "#{Kernel.caller.first}: [DEPRECATION] `SimpleCov.minimum_coverage_by_group` is deprecated. " \
+           "Replace it with:\n#{per_group_coverage_replacement(coverage)}"
+      @minimum_coverage_by_group = coverage.dup.transform_values do |group_coverage|
+        group_coverage = {primary_coverage => group_coverage} if group_coverage.is_a?(Numeric)
+        raise_on_invalid_coverage(group_coverage, "minimum_coverage_by_group")
+        group_coverage
+      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
+
+    # 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) }
+      defaults, raw = coverage.partition { |key, _| key.is_a?(Symbol) }.map(&:to_h)
+      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.new { |hash, criterion| hash[criterion] = [] }
+      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.new { |hash, criterion| hash[criterion] = [] }
+      coverage.each do |group_name, group_coverage|
+        group_coverage = {primary_coverage => group_coverage} if group_coverage.is_a?(Numeric)
+        group_coverage.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