simplecov 0.22.0 → 1.3.0

data/lib/simplecov/combine.rb

@@ -1,30 +1,6 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  # Functionally for combining coverage results
-  #
   module Combine
-  module_function
-
-    #
-    # Combine two coverage based on the given combiner_module.
-    #
-    # Combiners should always be called through this interface,
-    # as it takes care of short-circuiting of one of the coverages is nil.
-    #
-    # @return [Hash]
-    def combine(combiner_module, coverage_a, coverage_b)
-      return existing_coverage(coverage_a, coverage_b) if empty_coverage?(coverage_a, coverage_b)
-
-      combiner_module.combine(coverage_a, coverage_b)
-    end
-
-    def empty_coverage?(coverage_a, coverage_b)
-      !(coverage_a && coverage_b)
-    end
-
-    def existing_coverage(coverage_a, coverage_b)
-      coverage_a || coverage_b
-    end
   end
 end

data/lib/simplecov/command_guesser.rb

@@ -1,63 +1,120 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  #
-  # Helper that tries to find out what test suite is running (for SimpleCov.command_name)
-  #
   module CommandGuesser
     class << self
-      # Storage for the original command line call that invoked the test suite.
-      # This has got to be stored as early as possible because i.e. rake and test/unit 2
-      # have a habit of tampering with ARGV, which makes i.e. the automatic distinction
-      # between rails unit/functional/integration tests impossible without this cached
-      # item.
-      attr_accessor :original_run_command
+      # The original command line call that invoked the test suite. This has to
+      # be stored as early as possible because rake and test/unit 2 have a habit
+      # of tampering with ARGV.
+      attr_reader :original_run_command
+
+      # Assigning the flattened command clears any separately recorded program
+      # name so the two can never describe different runs. Callers that know the
+      # real one assign it immediately afterwards, as `defaults.rb` does.
+      def original_run_command=(command)
+        @original_program_name = nil
+        @original_run_command = command
+      end
+
+      # The invoked program on its own. `original_run_command` joins
+      # `$PROGRAM_NAME` and `ARGV` with a space, so a program path containing
+      # one (`/opt/My Ruby/bin/rspec`) cannot be recovered from it afterwards.
+      # Falls back to the first token for callers that set only the flattened
+      # command, which is every caller outside `defaults.rb`.
+      attr_writer :original_program_name
+
+      def original_program_name
+        @original_program_name || original_run_command.to_s[/\A\s*(\S+)/, 1]
+      end
 
       def guess
-        from_env || from_command_line_options || from_defined_constants
+        framework = from_executable_name || from_command_line_options || from_defined_constants
+        [framework, parallel_data].compact.join(" ")
       end
 
-    private
+      private
 
-      def from_env
-        # If being run from inside parallel_tests set the command name according to the process number
-        return unless ENV["PARALLEL_TEST_GROUPS"] && ENV["TEST_ENV_NUMBER"]
+      # When parallel_tests (or a compatible runner) is driving the suite, tag
+      # the command name with this worker's position in the pool.
+      def parallel_data
+        groups, number = ENV.values_at("PARALLEL_TEST_GROUPS", "TEST_ENV_NUMBER")
+        return unless groups && number
 
-        number = ENV["TEST_ENV_NUMBER"]
+        # parallel_tests sets the first worker's TEST_ENV_NUMBER to "" rather
+        # than "1"; restore the position so the rendered label reads cleanly.
         number = "1" if number.empty?
-        "(#{number}/#{ENV['PARALLEL_TEST_GROUPS']})"
+        "(#{number}/#{groups})"
       end
 
+      # The command is `"#{$PROGRAM_NAME} #{ARGV.join(' ')}"`, so a keyword only
+      # carries meaning when it begins a path segment or an argument. Matching
+      # it as a bare substring lets any part of the interpreter path decide the
+      # suite name: a Ruby installed under `latest/bin` (as mise does) contains
+      # "test/", so every run through it was labelled "Unit Tests".
+      #
+      # A backslash bounds a segment too, or a Windows `spec\foo_spec.rb` would
+      # lose a match. The `test/` patterns below still spell their separator as
+      # `/` only, which is how it has always been.
+      SEGMENT_START = %r{(?<![^\s/\\])}
+      private_constant :SEGMENT_START
+      SEGMENT_END = %r{(?=[\s/\\]|\z)}
+      private_constant :SEGMENT_END
+
+      COMMAND_LINE_FRAMEWORKS = {
+        %r{#{SEGMENT_START}test/functional/} => "Functional Tests",
+        %r{#{SEGMENT_START}test/\{.*functional.*\}/} => "Functional Tests",
+        %r{#{SEGMENT_START}test/integration/} => "Integration Tests",
+        %r{#{SEGMENT_START}test/} => "Unit Tests",
+        /#{SEGMENT_START}spec#{SEGMENT_END}/ => "RSpec",
+        /#{SEGMENT_START}cucumber#{SEGMENT_END}/ => "Cucumber Features",
+        /#{SEGMENT_START}features#{SEGMENT_END}/ => "Cucumber Features"
+      }.freeze
+      private_constant :COMMAND_LINE_FRAMEWORKS
+
       def from_command_line_options
-        case original_run_command
-        when /test\/functional\//, /test\/\{.*functional.*\}\//
-          "Functional Tests"
-        when /test\/integration\//
-          "Integration Tests"
-        when /test\//
-          "Unit Tests"
-        when /spec/
-          "RSpec"
-        when /cucumber/, /features/
-          "Cucumber Features"
-        end
+        # A command that was never recorded matches nothing, which `match?`
+        # answers for a nil of its own accord.
+        COMMAND_LINE_FRAMEWORKS.find { |pattern, _| pattern.match?(original_run_command) }&.last
       end
 
+      # Which binary was invoked outranks everything else on the command line.
+      # `rspec features` is an RSpec suite whose examples live in features/, not
+      # a Cucumber run, and only the executable name says so. Generic runners
+      # (`ruby`, `rake`, a bare `*_test.rb` script) are absent on purpose: they
+      # name no framework, so those runs fall through to the path patterns.
+      EXECUTABLE_FRAMEWORKS = {
+        "rspec" => "RSpec",
+        "cucumber" => "Cucumber Features"
+      }.freeze
+      private_constant :EXECUTABLE_FRAMEWORKS
+
+      def from_executable_name
+        program = original_program_name
+        return unless program
+
+        # The extension is trimmed so Windows' rspec.bat is recognized too.
+        EXECUTABLE_FRAMEWORKS[File.basename(program, ".*")]
+      end
+
+      # Inner array literals after the first are flagged uncovered by Ruby's
+      # Coverage module even though the constant evaluates as a whole, a known
+      # quirk with multi-line array literals.
+      DEFINED_CONSTANT_FRAMEWORKS = [
+        ["RSpec", -> { defined?(::RSpec) }],
+        ["Unit Tests", -> { defined?(Test::Unit) }],   # simplecov:disable
+        ["Minitest", -> { defined?(::Minitest) }],   # simplecov:disable
+        ["MiniTest", -> { defined?(MiniTest) }]      # simplecov:disable
+      ].freeze
+      private_constant :DEFINED_CONSTANT_FRAMEWORKS
+
       def from_defined_constants
-        # If the command regexps fail, let's try checking defined constants.
-        if defined?(RSpec)
-          "RSpec"
-        elsif defined?(Test::Unit)
-          "Unit Tests"
-        elsif defined?(Minitest)
-          "Minitest"
-        elsif defined?(MiniTest)
-          "MiniTest"
-        else
-          # TODO: Provide link to docs/wiki article
-          warn "SimpleCov failed to recognize the test framework and/or suite used. Please specify manually using SimpleCov.command_name 'Unit Tests'."
-          "Unknown Test Framework"
-        end
+        DEFINED_CONSTANT_FRAMEWORKS.each { |name, defined_check| return name if defined_check.call }
+
+        warn(
+          "SimpleCov failed to recognize the test framework and/or suite used. " \
+          "Please specify manually using SimpleCov.command_name 'Unit Tests'."
+        )
+        "Unknown Test Framework"
       end
     end
   end

data/lib/simplecov/configuration/baseline.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Configuration
+    # The baseline's path, relative to `SimpleCov.root`; an absolute path is
+    # honored as given. The file's presence is the opt-in: generate it with
+    # `simplecov ratchet`, check it in, and the exit check holds every listed
+    # file to its own floor (#1268).
+    def baseline_file(path = nil)
+      return @baseline_file ||= Baseline::DEFAULT_FILENAME unless path
+
+      self.baseline_file = path
+      _ = @baseline_file
+    end
+
+    def baseline_file=(path)
+      @baseline_file = path
+    end
+
+    # Memoized per resolved path so the exit check and the JSON formatter's
+    # errors section read the file once, while a `baseline_file` or `root` change
+    # between reads is still picked up.
+    def baseline
+      resolved = File.expand_path(baseline_file, root)
+      return @baseline if @baseline_path.eql?(resolved)
+
+      @baseline_path = resolved
+      @baseline = Baseline.read_if_exists(resolved)
+    end
+  end
+end

data/lib/simplecov/configuration/coverage.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Configuration
+    COVERAGE_THRESHOLD_OPTIONS = %i[minimum maximum exact maximum_drop ignore minimum_per_file
+      maximum_missed maximum_missed_per_file].freeze
+
+    def coverage(criterion, primary: false, enabled: true, oneshot: false, **thresholds, &block)
+      criterion = enable_coverage_criterion(criterion, enabled: enabled, oneshot: oneshot)
+      # The cast admits :eval, which primary_coverage rejects at runtime.
+      primary_coverage(_ = criterion) if primary
+
+      configurator = CoverageCriterion.new(self, criterion)
+      apply_threshold_options(configurator, thresholds)
+      configurator.instance_eval(&block) if block
+
+      criterion
+    end
+
+    private
+
+    def apply_threshold_options(configurator, options)
+      options.each do |verb, value|
+        unless COVERAGE_THRESHOLD_OPTIONS.include?(verb)
+          raise ConfigurationError,
+            "Unknown `coverage` option #{verb.inspect}. " \
+            "Supported options are #{COVERAGE_THRESHOLD_OPTIONS.inspect}."
+        end
+
+        configurator.public_send(verb, value)
+      end
+    end
+
+    def enable_coverage_criterion(criterion, enabled:, oneshot:)
+      criterion = resolve_criterion_variant(criterion, oneshot)
+      enabled ? enable_coverage(criterion) : disable_coverage(criterion)
+      criterion
+    end
+
+    def resolve_criterion_variant(criterion, oneshot)
+      return criterion unless oneshot
+
+      raise ConfigurationError, "`oneshot: true` is only valid for `coverage :line`" unless criterion.equal?(:line)
+
+      ONESHOT_LINE_COVERAGE_CRITERION
+    end
+
+    # @api private
+    def store_overall_threshold(setting, criterion, percent)
+      raise_on_invalid_coverage({criterion => percent}, setting)
+      public_send(setting)[criterion] = percent
+    end
+
+    def store_missed_cap(setting, criterion, count)
+      raise_if_criterion_disabled(criterion)
+      raise_on_invalid_missed_cap(count, setting)
+      public_send(setting)[criterion] = count
+    end
+
+    def store_maximum_missed_per_file(criterion, count, target)
+      raise_if_criterion_disabled(criterion)
+      raise_on_invalid_missed_cap(count, "maximum_missed_per_file")
+      return maximum_missed_per_file[criterion] = count if target.nil?
+
+      unless target.is_a?(String) || target.is_a?(Regexp)
+        raise ConfigurationError, "`only:` must be a String path or Regexp, got #{target.inspect}"
+      end
+
+      (maximum_missed_per_file_overrides[target] ||= {})[criterion] = count
+    end
+
+    def store_minimum_per_file(criterion, percent, target)
+      raise_on_invalid_coverage({criterion => percent}, "minimum_coverage_by_file")
+      return minimum_coverage_by_file[criterion] = percent if target.nil?
+
+      unless target.is_a?(String) || target.is_a?(Regexp)
+        raise ConfigurationError, "`only:` must be a String path or Regexp, got #{target.inspect}"
+      end
+
+      (minimum_coverage_by_file_overrides[target] ||= {})[criterion] = percent
+    end
+
+    def store_minimum_per_group(criterion, percent, group_name)
+      raise_on_invalid_coverage({criterion => percent}, "minimum_coverage_by_group")
+      # Normalized like `group` does, so `per: group(:Models)` finds the group
+      # defined as `group "Models"` at check time.
+      (minimum_coverage_by_group[GroupNames.normalize(group_name)] ||= {})[criterion] = percent
+    end
+
+    #
+    # Receiver for a `coverage <criterion> do ... end` block.
+    #
+    class CoverageCriterion
+      def initialize(config, criterion)
+        @config = config
+        @criterion = criterion
+      end
+
+      def minimum(percent, per: nil)
+        case per
+        when nil then @config.__send__(:store_overall_threshold, :minimum_coverage, @criterion, percent)
+        when :file then @config.__send__(:store_minimum_per_file, @criterion, percent, nil)
+        when String, Regexp then @config.__send__(:store_minimum_per_file, @criterion, percent, per)
+        when GroupTarget then @config.__send__(:store_minimum_per_group, @criterion, percent, per.name)
+        else raise_invalid_per(per)
+        end
+      end
+
+      def maximum(percent)
+        @config.__send__(:store_overall_threshold, :maximum_coverage, @criterion, percent)
+      end
+
+      def exact(percent)
+        minimum(percent)
+        maximum(percent)
+      end
+
+      def maximum_drop(percent)
+        @config.__send__(:store_overall_threshold, :maximum_coverage_drop, @criterion, percent)
+      end
+
+      def maximum_missed(count, per: nil)
+        case per
+        when nil then @config.__send__(:store_missed_cap, :maximum_missed, @criterion, count)
+        when :file then @config.__send__(:store_maximum_missed_per_file, @criterion, count, nil)
+        when String, Regexp then @config.__send__(:store_maximum_missed_per_file, @criterion, count, per)
+        when GroupTarget
+          raise ConfigurationError,
+            "maximum_missed does not support `per: group(...)` yet; see docs/Roadmap.md"
+        else raise_invalid_per(per)
+        end
+      end
+
+      def group(name)
+        GroupTarget.new(name: name)
+      end
+
+      # The flatten serves the one-liner keyword form, whose value arrives as a
+      # single argument (`ignore: %i[implicit_else]`).
+      def ignore(*types)
+        case @criterion
+        when :branch then @config.__send__(:store_ignored_branches, types.flatten)
+        when :method then @config.__send__(:store_ignored_methods, types.flatten)
+        else
+          raise ConfigurationError,
+            "`ignore` is supported for `coverage :branch` and `coverage :method`, not #{@criterion.inspect}"
+        end
+      end
+
+      def minimum_per_file(percent, only: nil)
+        Deprecation.warn("`minimum_per_file` is deprecated. " \
+                         "Replace with `minimum #{percent}, per: #{(only || :file).inspect}`.")
+        @config.__send__(:store_minimum_per_file, @criterion, percent, only)
+      end
+
+      def minimum_per_group(percent, only:)
+        Deprecation.warn("`minimum_per_group` is deprecated. " \
+                         "Replace with `minimum #{percent}, per: group(#{only.inspect})`.")
+        @config.__send__(:store_minimum_per_group, @criterion, percent, only)
+      end
+
+      def maximum_missed_per_file(count, only: nil)
+        Deprecation.warn("`maximum_missed_per_file` is deprecated. " \
+                         "Replace with `maximum_missed #{count}, per: #{(only || :file).inspect}`.")
+        @config.__send__(:store_maximum_missed_per_file, @criterion, count, only)
+      end
+
+      def primary
+        # @criterion is Symbol-wide because this receiver is also built for
+        # :eval; primary_coverage validates at runtime.
+        @config.primary_coverage(_ = @criterion)
+      end
+
+      GroupTarget = Data.define(:name)
+
+      private
+
+      def raise_invalid_per(per)
+        raise ConfigurationError,
+          "`per:` must be :file, a String path, a Regexp, or group(\"Name\"), got #{per.inspect}"
+      end
+    end
+  end
+end

data/lib/simplecov/configuration/coverage_criteria.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Configuration
+    SUPPORTED_COVERAGE_CRITERIA = %i[line branch method oneshot_line].freeze
+    DEFAULT_COVERAGE_CRITERION = :line
+    ONESHOT_LINE_COVERAGE_CRITERION = :oneshot_line
+    LINE_COVERAGE_ALTERNATIVES = {line: :oneshot_line, oneshot_line: :line}.freeze #: line_coverage_alternatives
+    private_constant :LINE_COVERAGE_ALTERNATIVES
+
+    def enable_coverage(*criteria)
+      criteria.each do |criterion|
+        criterion.equal?(:eval) ? enable_eval_coverage : add_coverage_criterion(_ = criterion)
+      end
+    end
+
+    # Disabling every criterion raises at `start_tracking`, not here, so config
+    # files that toggle criteria in arbitrary order don't have to worry about
+    # transient empty states.
+    def disable_coverage(criterion)
+      return disable_eval_coverage if criterion.equal?(:eval)
+
+      raise_if_criterion_unsupported(_ = criterion)
+      coverage_criteria.delete(_ = criterion)
+      @primary_coverage = nil if @primary_coverage.equal?(criterion)
+    end
+
+    def primary_coverage(criterion = nil)
+      if criterion.nil?
+        @primary_coverage ||= default_primary_coverage
+      else
+        self.primary_coverage = criterion
+      end
+    end
+
+    def primary_coverage=(criterion)
+      raise_if_criterion_disabled(criterion)
+      @primary_coverage = criterion
+    end
+
+    def coverage_criteria
+      @coverage_criteria ||= Set[DEFAULT_COVERAGE_CRITERION]
+    end
+
+    def coverage_criterion_enabled?(criterion)
+      coverage_criteria.member?(criterion)
+    end
+
+    def clear_coverage_criteria
+      @coverage_criteria = nil
+      @primary_coverage = nil
+    end
+
+    def validate_coverage_criteria!
+      return unless coverage_criteria.empty?
+
+      raise ConfigurationError,
+        "At least one coverage criterion must be enabled. " \
+        "Re-enable one with `enable_coverage :line`, `:branch`, or `:method`."
+    end
+
+    # Whether this run produces line data at all. The oneshot variant counts:
+    # `ResultAdapter` turns its executed-line list back into a line array. A
+    # branch-only or method-only run produces none, and `Coverage.result`
+    # entries for the files it loaded carry no `"lines"` key.
+    def line_coverage?
+      coverage_criterion_enabled?(DEFAULT_COVERAGE_CRITERION) ||
+        coverage_criterion_enabled?(ONESHOT_LINE_COVERAGE_CRITERION)
+    end
+
+    def branch_coverage?
+      branch_coverage_supported? && coverage_criterion_enabled?(:branch)
+    end
+
+    def branch_coverage_supported?
+      coverage_criterion_supported?(:branches)
+    end
+
+    def method_coverage?
+      method_coverage_supported? && coverage_criterion_enabled?(:method)
+    end
+
+    def method_coverage_supported?
+      coverage_criterion_supported?(:methods)
+    end
+
+    # Older Rubies don't expose `Coverage.supported?`, so fall back to the
+    # historical engine check that line/branch/method were unavailable on JRuby.
+    # `:eval` was added later, so its fallback is "always unsupported".
+    def coverage_criterion_supported?(criterion)
+      load_coverage
+      return Coverage.supported?(criterion) if Coverage.respond_to?(:supported?)
+
+      !criterion.eql?(:eval) && !RUBY_ENGINE.eql?("jruby")
+    end
+
+    # Loading `simplecov/configuration` on its own leaves Coverage undefined, and
+    # this question is asked at configuration time.
+    def load_coverage
+      require "coverage"
+    end
+
+    private
+
+    def add_coverage_criterion(criterion)
+      raise_if_criterion_unsupported(criterion)
+      incompatible = LINE_COVERAGE_ALTERNATIVES[criterion]
+      disable_coverage(incompatible) if incompatible
+      coverage_criteria << criterion
+    end
+
+    # Answering `:line` even when it is disabled would propagate broken state
+    # into `minimum_coverage 90`, so fall back to whichever criterion the user
+    # actually enabled, in insertion order.
+    def default_primary_coverage
+      return DEFAULT_COVERAGE_CRITERION if coverage_criterion_enabled?(DEFAULT_COVERAGE_CRITERION)
+
+      _ = coverage_criteria.first
+    end
+
+    def raise_if_criterion_disabled(criterion)
+      if criterion.equal?(:eval)
+        raise ConfigurationError,
+          "Coverage criterion :eval only toggles measuring eval'd code; " \
+          "it cannot carry thresholds or serve as the primary criterion"
+      end
+
+      raise_if_criterion_unsupported(criterion)
+      return if coverage_criterion_enabled?(criterion)
+
+      raise ConfigurationError,
+        "Coverage criterion #{criterion}, is disabled! " \
+        "Please enable it first through enable_coverage #{criterion} (if supported)"
+    end
+
+    def raise_if_criterion_unsupported(criterion)
+      return if SUPPORTED_COVERAGE_CRITERIA.member?(criterion)
+
+      raise ConfigurationError,
+        "Unsupported coverage criterion #{criterion}, supported values are #{SUPPORTED_COVERAGE_CRITERIA}"
+    end
+  end
+end

data/lib/simplecov/configuration/deprecations.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "../deprecation"
+
+module SimpleCov
+  module Configuration
+    DEPRECATION_MODES = Deprecation::MODES
+
+    # The configuration DSL migrates by warn-and-delegate, which means a project
+    # can run on deprecated spellings indefinitely without noticing.
+    # `deprecations :raise` turns every deprecated API into a ConfigurationError,
+    # so a project that has migrated can guard in CI against old spellings
+    # creeping back. There is deliberately no silencing mode: a deprecation you
+    # cannot see is a migration you never make.
+    def deprecations(mode = nil)
+      return Deprecation.mode unless mode
+
+      Deprecation.mode = mode
+    end
+  end
+end

data/lib/simplecov/configuration/eval_coverage.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Configuration
+    # The standalone eval-coverage toggle, kept apart from the criteria-set logic
+    # in `coverage_criteria.rb` because `:eval` is a boolean toggle, never a
+    # member of the enabled-criteria set.
+    def coverage_for_eval_supported?
+      coverage_criterion_supported?(:eval)
+    end
+
+    def coverage_for_eval_enabled?
+      @coverage_for_eval_enabled ||= false
+    end
+
+    def enable_coverage_for_eval
+      Deprecation.warn("`SimpleCov.enable_coverage_for_eval` is deprecated. " \
+                       "Replace with `SimpleCov.enable_coverage :eval`.")
+      enable_eval_coverage
+    end
+
+    private
+
+    def enable_eval_coverage
+      if coverage_for_eval_supported?
+        @coverage_for_eval_enabled = true
+      else
+        warn "Coverage for eval is not available on this Ruby"
+      end
+    end
+
+    # No support check needed: off is a safe state on every Ruby.
+    def disable_eval_coverage
+      @coverage_for_eval_enabled = false
+    end
+  end
+end