minitest-heat 0.0.9 → 0.0.13

data/lib/minitest/heat/locations.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Minitest
+  module Heat
+    # Convenience methods for determining the file and line number where the problem occurred.
+    #   There are several layers of specificity to help make it easy to communicate the relative
+    #   location of the failure:
+    #   - 'final' represents the final line of the backtrace regardless of where it is
+    #   - 'test_definition' represents where the test is defined
+    #   - 'test_failure' represents the last line from the project's tests. It is further differentiated by
+    #     the line where the test is defined and the actual line of code in the test that geneated
+    #     the failure or exception
+    #   - 'source_code' represents the last line from the project's source code
+    #   - 'project' represents the last source line, but falls back to the last test line
+    #   - 'most_relevant' represents the most specific file to investigate starting with the source
+    #     code and then looking to the test code with final line of the backtrace as a fallback
+    class Locations
+      attr_reader :test_definition, :backtrace
+
+      def initialize(test_definition_location, backtrace = [])
+        test_definition_pathname, test_definition_line_number = test_definition_location
+        @test_definition          = ::Minitest::Heat::Location.new(pathname: test_definition_pathname, line_number: test_definition_line_number)
+
+        @backtrace = Backtrace.new(backtrace)
+      end
+
+      # Prints the pathname and line number of the location most likely to be the source of the
+      #   test failure
+      #
+      # @return [String] ex. 'path/to/file.rb:12'
+      def to_s
+        "#{most_relevant.absolute_filename}:#{most_relevant.line_number}"
+      end
+
+      # Knows if the failure is contained within the test. For example, if there's bad code in a
+      #   test, and it raises an exception, then it's really a broken test rather than a proper
+      #   faiure.
+      #
+      # @return [Boolean] true if final file in the backtrace is the same as the test location file
+      def broken_test?
+        !test_failure.nil? && test_failure == final
+      end
+
+      # Knows if the failure occurred in the actual project source code—as opposed to the test or
+      #   an external piece of code like a gem.
+      #
+      # @return [Boolean] true if there's a non-test project file in the stacktrace but it's not
+      #   a result of a broken test
+      def proper_failure?
+        !source_code.nil? && !broken_test?
+      end
+
+      # The file most likely to be the source of the underlying problem. Often, the most recent
+      #   backtrace files will be a gem or external library that's failing indirectly as a result
+      #   of a problem with local source code (not always, but frequently). In that case, the best
+      #   first place to focus is on the code you control.
+      #
+      # @return [Array] file and line number of the most likely source of the problem
+      def most_relevant
+        [
+          source_code,
+          test_failure,
+          final
+        ].compact.first
+      end
+
+      def freshest
+        backtrace.recently_modified_locations.first
+      end
+
+      # Returns the final test location based on the backtrace if present. Otherwise falls back to
+      #   the test location which represents the test definition. The `test_definition` attribute
+      #   provides the location of where the test is defined. `test_failure` represents the actual
+      #   line from within the test where the problem occurred
+      #
+      # @return [Location] the final location from the test files
+      def test_failure
+        backtrace.test_locations.any? ? backtrace.test_locations.first : test_definition
+      end
+
+      # Returns the final source code location based on the backtrace
+      #
+      # @return [Location] the final location from the source code files
+      def source_code
+        backtrace.source_code_locations.first
+      end
+
+      # Returns the final project location based on the backtrace if present. Otherwise falls back
+      #   to the test location which represents the test definition.
+      #
+      # @return [Location] the final location from the project files
+      def project
+        backtrace.project_locations.any? ? backtrace.project_locations.first : test_definition
+      end
+
+      # The line number from within the `test_file` test definition where the failure occurred
+      #
+      # @return [Location] the last location from the backtrace or the test location if a backtrace
+      #   was not passed to the initializer
+      def final
+        backtrace.locations.any? ? backtrace.locations.first : test_definition
+      end
+    end
+  end
+end

data/lib/minitest/heat/map.rb

@@ -2,6 +2,7 @@
 
 module Minitest
   module Heat
+    # Structured approach to collecting the locations of issues for generating a heat map
     class Map
       MAXIMUM_FILES_TO_SHOW = 5
 
@@ -11,18 +12,29 @@ module Minitest
         @hits = {}
       end
 
-      def add(filename, line_number, type)
-        @hits[filename] ||= Hit.new(filename)
-
-        @hits[filename].log(type, line_number)
+      # Records a hit to the list of files and issue types
+      # @param filename [String] the unique path and file name for recordings hits
+      # @param line_number [Integer] the line number where the issue was encountered
+      # @param type [Symbol] the type of issue that was encountered (i.e. :failure, :error, etc.)
+      #
+      # @return [void]
+      def add(pathname, line_number, type, backtrace: [])
+        @hits[pathname.to_s] ||= Hit.new(pathname)
+        @hits[pathname.to_s].log(type.to_sym, line_number, backtrace: backtrace)
       end
 
+      # Returns a subset of affected files to keep the list from being overwhelming
+      #
+      # @return [Array] the list of files and the line numbers for each encountered issue type
       def file_hits
         hot_files.take(MAXIMUM_FILES_TO_SHOW)
       end
 
       private
 
+      # Sorts the files by hit "weight" so that the most problematic files are at the beginning
+      #
+      # @return [Array] the collection of files that encountred issues
       def hot_files
         hits.values.sort_by(&:weight).reverse
       end

data/lib/minitest/heat/output/backtrace.rb

@@ -3,110 +3,137 @@
 module Minitest
   module Heat
     class Output
-      # Builds the collection of tokens for a backtrace when an exception occurs
+      # Builds the collection of tokens for displaying a backtrace when an exception occurs
       class Backtrace
         DEFAULT_LINE_COUNT = 10
         DEFAULT_INDENTATION_SPACES = 2
 
-        attr_accessor :location, :backtrace
+        attr_accessor :locations, :backtrace
 
-        def initialize(location)
-          @location = location
-          @backtrace = location.backtrace
+        def initialize(locations)
+          @locations = locations
+          @backtrace = locations.backtrace
           @tokens = []
         end
 
         def tokens
-          # There could be option to expand and display more than one line of source code for the
-          # final backtrace line if it might be relevant/helpful?
-
           # Iterate over the selected lines from the backtrace
-          backtrace_entries.each do |backtrace_entry|
-            # Get the source code for the line from the backtrace
-            parts = [
-              indentation_token,
-              path_token(backtrace_entry),
-              *file_and_line_number_tokens(backtrace_entry),
-              source_code_line_token(backtrace_entry.source_code)
-            ]
-
-            parts << file_freshness(backtrace_entry) if most_recently_modified?(backtrace_entry)
-
-            @tokens << parts
-          end
-
-          @tokens
+          @tokens = backtrace_locations.map { |location| backtrace_location_tokens(location) }
         end
 
+        # Determines the number of lines to display from the backtrace.
+        #
+        # @return [Integer] the number of lines to limit the backtrace to
         def line_count
+          # Defined as a method instead of using the constant directlyr in order to easily support
+          # adding options for controlling how many lines are displayed from a backtrace.
+          #
+          # For example, instead of a fixed number, the backtrace could dynamically calculate how
+          # many lines it should displaye in order to get to the origination point. Or it could have
+          # a default, but inteligently go back further if the backtrace meets some criteria for
+          # displaying more lines.
           DEFAULT_LINE_COUNT
         end
 
-        # This should probably be smart about what lines are displayed in a backtrace.
-        # Maybe...
-        # ...it could intelligently display the full back trace?
-        # ...only the backtrace from the first/last line of project source?
-        # ...it behaves a little different when it's a broken test vs. a true exception?
-        # ...it could be smart about subtly flagging the lines that show up in the heat map frequently?
-        # ...it could be influenced by a "compact" or "robust" reporter super-style?
-        # ...it's smart about exceptions that were raised outside of the project?
-        # ...it's smart about highlighting lines of code differently based on whether it's source code, test code, or external code?
-        def backtrace_entries
-          all_entries
+        # A subset of parsed lines from the backtrace.
+        #
+        # @return [Array<Location>] the backtrace locations determined to be most relevant to the
+        #   context of the underlying issue
+        def backtrace_locations
+          # This could eventually have additional intelligence to determine what lines are most
+          # relevant for a given type of issue. For now, it simply takes the line numbers, but the
+          # idea is that long-term, it could adjust that on the fly to keep the line count as low
+          # as possible but expand it if necessary to ensure enough context is displayed.
+          #
+          # - If there's no clear cut details about the source of the error from within the project,
+          #   it could display the entire backtrace without filtering anything.
+          # - It could scan the backtrace to the first appearance of project files and then display
+          #   all of the lines that occurred after that instance
+          # - It coudl filter the lines differently whether the issue originated from a test or from
+          #   the source code.
+          # - It could allow supporting a "compact" or "robust" reporter style so that someone on
+          #   a smaller screen could easily reduce the information shown so that the results could
+          #   be higher density even if it means truncating some occasionally useful details
+          # - It could be smarter about displaying context/guidance when the full backtrace is from
+          #   outside the project's code
+          #
+          # But for now. It just grabs some lines.
+          backtrace.locations.take(line_count)
         end
 
         private
 
-        def all_backtrace_entries_from_project?
-          backtrace_entries.all? { |line| line.path.to_s.include?(project_root_dir) }
-        end
-
-        def project_root_dir
-          Dir.pwd
-        end
-
-        def project_entries
-          backtrace.project_entries.take(line_count)
+        def backtrace_location_tokens(location)
+          [
+            indentation_token,
+            path_token(location),
+            *file_and_line_number_tokens(location),
+            containining_element_token(location),
+            source_code_line_token(location),
+            most_recently_modified_token(location),
+          ].compact
         end
 
-        def all_entries
-          backtrace.parsed_entries.take(line_count)
+        # Determines if all lines to be displayed are from within the project directory
+        #
+        # @return [Boolean] true if all lines of the backtrace being displayed are from the project
+        def all_backtrace_from_project?
+          backtrace_locations.all?(&:project_file?)
         end
 
-        def most_recently_modified?(line)
-          # If there's more than one line being displayed, and the current line is the freshest
-          backtrace_entries.size > 1 && line == backtrace.freshest_project_location
+        # Determines if the file referenced by a backtrace line is the most recently modified file
+        #   of all the files referenced in the visible backtrace locations.
+        #
+        # @param [Location] location the location to examine
+        #
+        # @return [<type>] <description>
+        #
+        def most_recently_modified?(location)
+          # If there's more than one line being displayed (otherwise, with one line, of course it's
+          # the most recently modified because there_aren't any others) and the current line is the
+          # same as the freshest location in the backtrace
+          backtrace_locations.size > 1 && location == locations.freshest
         end
 
         def indentation_token
           [:default, ' ' * indentation]
         end
 
-        def path_token(line)
-          style = line.to_s.include?(Dir.pwd) ? :default : :muted
-          path = "#{line.path}/"
+        def path_token(location)
+          # If the line is a project file, help it stand out from the backtrace noise
+          style = location.project_file? ? :default : :muted
 
-          # If all of the backtrace lines are from the project, no point in the added redundant
-          #  noise of showing the project root directory over and over again
-          path = path.delete_prefix(project_root_dir) if all_backtrace_entries_from_project?
+          # If *all* of the backtrace lines are from the project, no point in the added redundant
+          # noise of showing the project root directory over and over again
+          path_format = all_backtrace_from_project? ? :relative_path : :absolute_path
 
-          [style, path]
+          [style, location.send(path_format)]
         end
 
-        def file_and_line_number_tokens(backtrace_entry)
-          style = backtrace_entry.to_s.include?(Dir.pwd) ? :bold : :muted
+        def file_and_line_number_tokens(location)
+          style = location.to_s.include?(Dir.pwd) ? :bold : :muted
           [
-            [style, backtrace_entry.file],
+            [style, location.filename],
             [:muted, ':'],
-            [style, backtrace_entry.line_number]
+            [style, location.line_number]
           ]
         end
 
-        def source_code_line_token(source_code)
-          [:muted, " #{Output::SYMBOLS[:arrow]} `#{source_code.line.strip}`"]
+        def source_code_line_token(location)
+          return nil unless location.project_file?
+
+          [:muted, " #{Output::SYMBOLS[:arrow]} `#{location.source_code.line.strip}`"]
         end
 
-        def file_freshness(_line)
+        def containining_element_token(location)
+          return nil if !location.project_file? || location.container.nil? || location.container.empty?
+
+          [:muted, " in #{location.container}"]
+        end
+
+        def most_recently_modified_token(location)
+          return nil unless most_recently_modified?(location)
+
           [:default, " #{Output::SYMBOLS[:middot]} Most Recently Modified File"]
         end
 
@@ -121,10 +148,6 @@ module Minitest
         def indentation
           DEFAULT_INDENTATION_SPACES
         end
-
-        def style_for(path)
-          style = path.to_s.include?(Dir.pwd) ? :default : :muted
-        end
       end
     end
   end

data/lib/minitest/heat/output/issue.rb

@@ -3,37 +3,27 @@
 module Minitest
   module Heat
     class Output
-      class Issue
-        attr_accessor :issue
+      # Formats issues to output based on the issue type
+      class Issue # rubocop:disable Metrics/ClassLength
+        attr_accessor :issue, :locations
 
         def initialize(issue)
           @issue = issue
+          @locations = issue.locations
         end
 
         def tokens
           case issue.type
-          when :error then error_tokens
-          when :broken then broken_tokens
-          when :failure then failure_tokens
-          when :skipped then skipped_tokens
-          when :painful then painful_tokens
-          when :slow then slow_tokens
+          when :error, :broken  then exception_tokens
+          when :failure         then failure_tokens
+          when :skipped         then skipped_tokens
+          when :painful, :slow  then slow_tokens
           end
         end
 
         private
 
-        def error_tokens
-          [
-            headline_tokens,
-            test_location_tokens,
-            summary_tokens,
-            *backtrace_tokens,
-            newline_tokens
-          ]
-        end
-
-        def broken_tokens
+        def exception_tokens
           [
             headline_tokens,
             test_location_tokens,
@@ -60,14 +50,6 @@ module Minitest
           ]
         end
 
-        def painful_tokens
-          [
-            headline_tokens,
-            slowness_summary_tokens,
-            newline_tokens
-          ]
-        end
-
         def slow_tokens
           [
             headline_tokens,
@@ -77,75 +59,82 @@ module Minitest
         end
 
         def headline_tokens
-          [[issue.type, issue.label], spacer_token, [:default, issue.test_name]]
+          [label_token(issue), spacer_token, [:default, test_name(issue)]]
+        end
+
+        # Creates a display-friendly version of the test name with underscores removed and the
+        #   first letter capitalized regardless of the formatt used for the test definition
+        # @param issue [Issue] the issue to use to generate the test name
+        #
+        # @return [String] the cleaned up version of the test name
+        def test_name(issue)
+          test_prefix = 'test_'
+          identifier = issue.test_identifier
+
+          if identifier.start_with?(test_prefix)
+            identifier.delete_prefix(test_prefix).gsub('_', ' ').capitalize
+          else
+            identifier
+          end
         end
 
-        def test_name_and_class_tokens
-          [[:default, issue.test_class], *test_location_tokens ]
+        def label_token(issue)
+          [issue.type, issue_label(issue.type)]
         end
 
-        def backtrace_tokens
-          backtrace = ::Minitest::Heat::Output::Backtrace.new(issue.location)
-
-          backtrace.tokens
+        def test_name_and_class_tokens
+          [[:default, issue.test_class], *test_location_tokens]
         end
 
         def test_location_tokens
-          [[:default, test_file_short_location], [:muted, ':'], [:default, issue.test_definition_line], arrow_token, [:default, issue.test_failure_line], [:muted, test_line_source]]
+          [
+            [:default, locations.test_definition.relative_filename],
+            [:muted, ':'],
+            [:default, locations.test_definition.line_number],
+            arrow_token,
+            [:default, locations.test_failure.line_number],
+            [:muted, "\n  #{locations.test_failure.source_code.line.strip}"]
+          ]
         end
 
         def location_tokens
-          [[:default, most_relevant_short_location], [:muted, ':'], [:default, issue.location.most_relevant_failure_line], [:muted, most_relevant_line_source]]
+          [
+            [:default, locations.most_relevant.relative_filename],
+            [:muted, ':'],
+            [:default, locations.most_relevant.line_number],
+            [:muted, "\n  #{locations.most_relevant.source_code.line.strip}"]
+          ]
         end
 
         def source_tokens
-          filename    = issue.location.project_file
-          line_number = issue.location.project_failure_line
-
+          filename    = locations.project.filename
+          line_number = locations.project.line_number
           source = Minitest::Heat::Source.new(filename, line_number: line_number)
+
           [[:muted, " #{Output::SYMBOLS[:arrow]} `#{source.line.strip}`"]]
         end
 
         def summary_tokens
-          [[:italicized, issue.summary.delete_suffix("---------------")]]
+          [[:italicized, issue.summary.delete_suffix('---------------').strip]]
         end
 
         def slowness_summary_tokens
           [
-            [:bold, issue.slowness],
+            [:bold, slowness(issue)],
             spacer_token,
-            [:default, issue.location.test_file.to_s.delete_prefix(Dir.pwd)],
+            [:default, locations.test_definition.relative_path],
+            [:default, locations.test_definition.filename],
             [:muted, ':'],
-            [:default, issue.location.test_definition_line]
+            [:default, locations.test_definition.line_number]
           ]
         end
 
-        def newline_tokens
-          []
-        end
-
-        def most_relevant_short_location
-          issue.location.most_relevant_file.to_s.delete_prefix("#{Dir.pwd}/")
-        end
-
-        def test_file_short_location
-          issue.location.test_file.to_s.delete_prefix("#{Dir.pwd}/")
+        def slowness(issue)
+          "#{issue.execution_time.round(2)}s"
         end
 
-        def most_relevant_line_source
-          filename    = issue.location.project_file
-          line_number = issue.location.project_failure_line
-
-          source = Minitest::Heat::Source.new(filename, line_number: line_number)
-          "\n  #{source.line.strip}"
-        end
-
-        def test_line_source
-          filename    = issue.location.test_file
-          line_number = issue.location.test_failure_line
-
-          source = Minitest::Heat::Source.new(filename, line_number: line_number)
-          "\n  #{source.line.strip}"
+        def newline_tokens
+          []
         end
 
         def spacer_token
@@ -156,6 +145,26 @@ module Minitest
           Output::TOKENS[:muted_arrow]
         end
 
+        def backtrace_tokens
+          @backtrace_tokens ||= ::Minitest::Heat::Output::Backtrace.new(locations).tokens
+        end
+
+        # The string to use to describe the failure type when displaying results/
+        # @param issue_type [Symbol] the symbol representing the issue's failure type
+        #
+        # @return [String] the display-friendly string describing the failure reason
+        def issue_label(issue_type)
+          case issue_type
+          when :error   then 'Error'
+          when :broken  then 'Broken Test'
+          when :failure then 'Failure'
+          when :skipped then 'Skipped'
+          when :slow    then 'Passed but Slow'
+          when :painful then 'Passed but Very Slow'
+          when :passed  then 'Success'
+          else 'Unknown'
+          end
+        end
       end
     end
   end