simplecov 1.1.0 → 1.2.0

data/lib/simplecov/test_tracker.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  #
+  # Records each test as a context in a `ContextMap`. Enabled by the
+  # `track_tests` configuration; installed into RSpec by
+  # `SimpleCov.start_tracking` and into Minitest by the minitest plugin.
+  # Any other runner can wrap its own units of work with
+  # `SimpleCov.track_test`.
+  #
+  # The contract is `track(id) { }`: attribute the lines the block executed to
+  # `id`, or abstain (`recorded_map` nil), never guess. How the lines are
+  # obtained is this class's private business, and today's engine is a
+  # peek-diff: sample `Coverage.peek_result` around the block and take the
+  # lines whose execution count grew. If Ruby's Coverage ever grows native
+  # contexts the engine is what gets replaced; the contract, the `ContextMap`,
+  # and everything downstream stay.
+  #
+  # Two limits are the peek-diff engine's, not the contract's. It needs
+  # per-line execution counts, which is why `track_tests` refuses to run under
+  # `:oneshot_line`. And tests overlapping across threads cannot be told
+  # apart, because the counters being diffed are process-global.
+  #
+  #
+  class TestTracker
+    attr_reader :map
+
+    # The context id everything since the last boundary belongs to, and the
+    # peek that boundary took.
+    Segment = Struct.new(:id, :opening)
+    private_constant :Segment
+
+    def initialize(root_regex: UselessResultsRemover.root_regex, granularity: :test)
+      unless Configuration::TRACK_TESTS_GRANULARITIES.include?(granularity)
+        raise ArgumentError, "unknown granularity #{granularity.inspect}, " \
+                             "expected one of #{Configuration::TRACK_TESTS_GRANULARITIES.inspect}"
+      end
+
+      @map = ContextMap.new
+      # Only files under the project root are attributed, judged by the same
+      # regex the report's own universe is rooted with. A peek covers every
+      # file the process loaded, every gem included, and diffing all of them on
+      # every test is the cost that would make tracking unaffordable.
+      @delta = Delta.new(root_regex: root_regex)
+      @granularity = granularity
+      @lock = Mutex.new
+      @depth = 0
+      @poisoned = false
+    end
+
+    # Records the lines the block executed as covered by `test_id`'s context
+    # (the test itself at :test granularity, its file at :file). A failing
+    # test's lines are still attributed when its segment closes.
+    def track(test_id)
+      id = context_id(test_id)
+      nested_opening = begin_track(id)
+      begin
+        yield
+      ensure
+        settle(id, nested_opening)
+      end
+    end
+
+    def poisoned?
+      @poisoned
+    end
+
+    # nil once poisoned: a poisoned recording must vanish like one that never
+    # happened, so the merge's all-or-nothing rule drops the run's map instead
+    # of keeping a wrong one. Flushes the open segment, so the answer carries
+    # every finished track. At process exit `Coverage.result` has already
+    # stopped measurement, so result-building passes the final coverage it just
+    # took as the closing snapshot instead of peeking again.
+    def recorded_map(closing: nil)
+      return nil if poisoned?
+
+      flush_segment(closing)
+      @map
+    end
+
+    private
+
+    # Same-thread reentrancy is fine, since a line the inner test executed was
+    # executed on the outer test's watch too, but a second thread means
+    # concurrent tests and `Coverage`'s counters are process-global: their
+    # deltas cannot be told apart, so recording shuts off rather than
+    # misattribute.
+    def begin_track(id)
+      outermost = note_entry
+      return nil if @poisoned
+      return Coverage.peek_result unless outermost
+
+      open_segment(id)
+      nil
+    end
+
+    def note_entry
+      @lock.synchronize do
+        if @depth.zero?
+          @owner = Thread.current
+        elsif !@owner.equal?(Thread.current)
+          poison
+        end
+        @depth += 1
+        @depth.equal?(1)
+      end
+    end
+
+    # A nested track records immediately against its own opening peek; an
+    # outermost one leaves its segment open for the next boundary. The owner
+    # needs no clearing: the next track to find the depth back at zero takes
+    # ownership itself.
+    def settle(id, nested_opening)
+      @map.record(id, @delta.call(nested_opening, Coverage.peek_result)) if nested_opening && !@poisoned
+    ensure
+      @lock.synchronize { @depth -= 1 }
+    end
+
+    # Peeking is the dominant cost of tracking (the copy covers every file the
+    # process loaded, branch and method tables included), so recording settles
+    # at segment boundaries: consecutive tracks with one context id share one
+    # open segment and pay nothing in between. In-root code that runs between
+    # two segments is attributed to the later one, the documented price.
+    def open_segment(id)
+      return if @segment&.id.eql?(id)
+
+      boundary = Coverage.peek_result
+      close_segment(boundary)
+      @segment = Segment.new(id, boundary)
+    end
+
+    def close_segment(closing)
+      segment = @segment
+      @map.record(segment.id, @delta.call(segment.opening, closing)) if segment
+    end
+
+    def flush_segment(closing)
+      return unless @segment
+
+      close_segment(closing || Coverage.peek_result)
+      @segment = nil
+    end
+
+    # An id with no `:line` tail (an exotic runner's fallback) stays whole.
+    def context_id(test_id)
+      return test_id unless @granularity.equal?(:file)
+
+      path, sep, tail = test_id.rpartition(":")
+      (sep.empty? || !tail.match?(/\A\d+\z/)) ? test_id : path
+    end
+
+    def poison
+      return if @poisoned
+
+      @poisoned = true
+      return unless SimpleCov.print_errors
+
+      warn "[SimpleCov]: tests are running concurrently in this process (parallel threads), " \
+           "so per-test coverage cannot be attributed. Dropping this process's test map."
+    end
+  end
+end

data/lib/simplecov/unloaded_file_injector.rb

@@ -3,46 +3,36 @@
 require_relative "simulate_coverage"
 
 module SimpleCov
-  # Fills in coverage for files that were tracked (via `cover` / `track_files`)
-  # but never loaded, so they count toward the denominators instead of being
-  # absent from the report entirely.
-  #
-  # This is the mechanism; the merge-time policy of *when* to inject and
-  # which criteria the simulated files carry lives in
-  # `ResultMerger::UnloadedFiles` — easy names to confuse.
+  # Fills in coverage for files that were tracked but never loaded, so they
+  # count toward the denominators instead of being absent from the report.
+  # This is the mechanism; the merge-time policy of when to inject lives in
+  # `ResultMerger::UnloadedFiles`.
   #
   # Everything arrives as arguments rather than being read from the SimpleCov
-  # singleton. The merge step performs this injection on behalf of the processes
-  # that contributed to it, and it does not necessarily share their
-  # configuration: a standalone `collate` never ran `SimpleCov.start`, so it has
-  # no `cover` glob of its own and takes the tracked paths from the resultsets
-  # instead. See #1250.
+  # singleton, because the merge performs this injection on behalf of
+  # processes whose configuration it does not necessarily share (#1250).
   module UnloadedFileInjector
-  module_function
+    extend self
 
-    # Expand `globs` into absolute paths, relative to `root` rather than
-    # `Dir.pwd` — test runners that chdir (or CI scripts that invoke the suite
-    # from a subdirectory) would otherwise silently miss files and produce a
-    # different set per environment. See #1106.
+    # Globs expand relative to `root` rather than `Dir.pwd`: runners that chdir
+    # would otherwise silently miss files and produce a different set per
+    # environment (#1106).
+    #
     # `reject:` are the producing process's path-decidable filters. Paths its
     # own report would exclude must not be recorded as tracked, or a merge that
-    # does not share the configuration would simulate them back in. Before
-    # injection moved to the merge the producer filtered them out of its own
-    # result and they never reached a resultset. A block filter is handed the
-    # source file and may consult coverage that does not exist yet, so those
-    # still fall to the merging process's filter chain. See #1250.
+    # does not share the configuration would simulate them back in. A block
+    # filter is handed the source file and may consult coverage that does not
+    # exist yet, so those still fall to the merging process's filter chain.
     def discover(globs, root:, reject: [])
       paths = globs.compact
-                   .flat_map { |glob| Dir.glob(glob, base: root) }
-                   .uniq
-                   .map { |path| File.expand_path(path, root) }
+        .flat_map { |glob| Dir.glob(glob, base: root) }
+        .uniq
+        .map { |path| File.expand_path(path, root) }
       return paths if reject.empty?
 
       paths.reject { |path| rejected?(path, reject) }
     end
 
-    # `SourceFile` reads source and builds lines lazily, so a path-only filter
-    # answers without anything here touching disk.
     def rejected?(path, filters)
       candidate = SourceFile.new(path, NO_COVERAGE_YET, loaded: false)
       filters.any? { |filter| filter.matches?(candidate) }
@@ -52,12 +42,9 @@ module SimpleCov
     NO_COVERAGE_YET = no_coverage_yet.freeze
     private_constant :NO_COVERAGE_YET
 
-    # Add simulated coverage for every path `coverage` does not already carry.
-    # Paths that are present are left alone, whoever put them there, which is
+    # Paths already present are left alone, whoever put them there, which is
     # what lets this run over resultsets a previous SimpleCov already injected
     # into without double-counting or overwriting real data.
-    #
-    # Returns the augmented coverage and the set of paths that were added.
     def call(coverage, paths, synthesize:, lines:)
       injected = Set.new
       augmented = coverage.dup

data/lib/simplecov/useless_results_remover.rb

@@ -1,26 +1,27 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  # Drop coverage entries whose paths live outside `SimpleCov.root` so the
-  # report only reflects the project's own source. Vendored gems, stdlib
-  # files, and anything else that happens to have been touched during the
-  # run never make it into the formatted result.
+  # Drops coverage entries whose paths live outside `SimpleCov.root`, so vendored
+  # gems, stdlib files, and anything else touched during the run never make it
+  # into the formatted result.
   module UselessResultsRemover
     def self.call(coverage_result)
       coverage_result.select { |path, _coverage| path.match?(root_regex) }
     end
 
-    # The `/i` flag covers case-insensitive matches on Windows / macOS-HFS+
+    # The `/i` flag covers case-insensitive matches on Windows and macOS-HFS+,
     # where the on-disk path's case can differ from `SimpleCov.root`'s.
     def self.root_regex
       root = SimpleCov.root
-      return @root_regex if root == @root_regex_root
+      return @root_regex if root.eql?(@root_regex_root)
 
       @root_regex_root = root
       @root_regex = /\A#{Regexp.escape(root.chomp(File::SEPARATOR) + File::SEPARATOR)}/i
     end
 
     def self.root_regx
+      Deprecation.warn("`SimpleCov::UselessResultsRemover.root_regx` is deprecated. " \
+                       "Replace with `root_regex`.")
       root_regex
     end
   end

data/lib/simplecov/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/lib/simplecov/view_coverage/template_compiler.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module ViewCoverage
+    #
+    # Compiles a single ActionView template: builds a `Template` for the file on
+    # disk and defines its method into a throwaway module, without ever
+    # rendering it.
+    #
+    # Defining the method is the whole trick. `Template#compile` hands the
+    # handler's generated Ruby to `module_eval(source, identifier, offset)`,
+    # and evaluating a `def` records the body as executable-but-unexecuted
+    # rather than running it, so `Coverage` comes away with a zeroed line array
+    # and a full set of branch tuples for the template.
+    #
+    # Never compile a template the suite already rendered. Evaluating the same
+    # identifier a second time replaces that file's entry in `Coverage` rather
+    # than adding to it, so the recompile would zero the hits the run actually
+    # earned and leave a duplicate set of branch tuples behind. `ViewCoverage`
+    # filters those out before calling here.
+    #
+    module TemplateCompiler
+      extend self
+
+      # False in any project that doesn't load ActionView, which is the common
+      # case and not an error: view coverage simply has nothing to do there.
+      def available?
+        !defined?(::ActionView::Template).nil?
+      end
+
+      # Answers whether the compile produced coverage data. A template that
+      # doesn't compile can't render either, so the suite has bigger problems
+      # than its coverage, but the report is not the place to discover that and
+      # a broken view must not take the whole run down.
+      def call(path)
+        template = build_template(path, File.binread(path))
+        return false unless template
+
+        compile_into_throwaway_module(template)
+        true
+      rescue StandardError, ScriptError => e
+        warn "[SimpleCov]: Skipping #{path}, which did not compile (#{e.class})"
+        false
+      end
+
+      # ActionView keeps `compile` private, and the module it compiles into is
+      # thrown away: what is wanted is the coverage the compile records, not the
+      # method it defines.
+      #
+      # mutant:disable -- `send` and `__send__` are the same call.
+      def compile_into_throwaway_module(template)
+        template.send(:compile, Module.new)
+      end
+
+      # The format the template renders, taken from the extension in front of the
+      # handler's: `show.html.erb` is `:html`. It reaches the handler's codegen
+      # (an HTML template escapes interpolations, a text one does not), but
+      # never the line structure, so a template named without one compiles fine
+      # as nil.
+      def format_for(path)
+        segments = File.basename(path).split(".")
+        return nil if segments.length < 3
+
+        segments.fetch(-2).to_sym
+      end
+
+      # The single place ActionView is named. The handler lookup is the one the
+      # resolver performs, so a template language the project has registered a
+      # handler for compiles here the way it does when rendered. Nil when
+      # nothing is registered for the extension, which is how a default glob
+      # naming `.haml` behaves in a project that has no Haml: ActionView would
+      # hand back the raw handler and the template would report as static text.
+      def build_template(path, source)
+        extension = File.extname(path).delete_prefix(".")
+        handler = ActionView::Template.registered_template_handler(extension)
+        return nil unless handler
+
+        no_locals = [] #: Array[Symbol]
+        ActionView::Template.new(source, path, handler, locals: no_locals, format: format_for(path))
+      end
+    end
+  end
+end

data/lib/simplecov/view_coverage.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "view_coverage/template_compiler"
+
+module SimpleCov
+  # Brings ActionView templates into the report, for projects that opt in with
+  # `cover_views`.
+  #
+  # Rendering a template is already enough to measure it: ActionView compiles
+  # each one with `module_eval(source, identifier, offset)` where `identifier`
+  # is the template's own path, and the offset cancels the `def` line its
+  # wrapper adds, so eval coverage attributes the generated code back to the
+  # `.erb` file at its own line numbers.
+  #
+  # A template no test renders is never compiled, so `Coverage` never hears
+  # about it and the report omits it entirely. That is the flattering
+  # direction to be wrong in, so every template the run didn't reach is
+  # compiled here instead, which lands it in the report at 0%.
+  module ViewCoverage
+    extend self
+
+    # Called once per process, immediately before `Coverage.result`. It has to
+    # happen here rather than at the merge point, where unloaded `.rb` files are
+    # injected, because compiling a template needs ActionView and the merging
+    # process need not have it loaded. A standalone `simplecov merge` never
+    # does.
+    def compile_unrendered
+      return [] unless enabled?
+
+      rendered = measured_paths
+      discover.reject { |path| rendered.include?(path) }
+        .select { |path| TemplateCompiler.call(path) }
+    end
+
+    def enabled?
+      SimpleCov.view_coverage? && Coverage.running? && TemplateCompiler.available?
+    end
+
+    # Expanded against `SimpleCov.root` rather than the working directory, and
+    # filtered through the same path-only filters the rest of the report honors,
+    # so `skip "app/views/admin"` keeps those templates out instead of compiling
+    # them only to drop them later.
+    def discover
+      globs = SimpleCov.view_globs || [] #: Array[String?]
+      UnloadedFileInjector.discover(globs, root: SimpleCov.root, reject: SimpleCov.filters.select(&:path_only?))
+    end
+
+    # The files `Coverage` is already holding data for, which for a template
+    # means the run rendered it. `peek_result` copies the whole coverage state
+    # to answer, so this stays a once-per-process call.
+    def measured_paths
+      Coverage.peek_result.keys.to_set
+    end
+  end
+end

data/lib/simplecov-html.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
 
 # Backward-compatibility shim: simplecov-html is now part of simplecov.
+
 require_relative "simplecov/formatter/html_formatter"