minitest-heat 0.0.7 → 0.0.11

data/lib/minitest/heat/location.rb

@@ -2,179 +2,178 @@
 
 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' 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
+    # Consistent structure for extracting information about a given location. In addition to the
+    #   pathname to the file and the line number in the file, it can also include information about
+    #   the containing method or block and retrieve source code for the location.
     class Location
-      TestDefinition = Struct.new(:pathname, :line_number) do
-        def initialize(pathname, line_number)
-          @pathname = Pathname(pathname)
-          @line_number = Integer(line_number)
-          super
-        end
-      end
+      UNRECOGNIZED = '(Unrecognized File)'
+      UNKNOWN_MODIFICATION_TIME = Time.at(0)
+      UNKNOWN_MODIFICATION_SECONDS = -1
 
-      attr_reader :test_location, :backtrace
+      attr_accessor :raw_pathname, :raw_line_number, :raw_container
 
-      def initialize(test_location, backtrace = [])
-        @test_location = TestDefinition.new(*test_location)
-        @backtrace = Backtrace.new(backtrace)
+      # Initialize a new Location
+      #
+      # @param [Pathname, String] pathname: the pathname to the file
+      # @param [Integer] line_number: the line number of the location within the file
+      # @param [String] container: nil the containing method or block for the issue
+      #
+      # @return [self]
+      def initialize(pathname:, line_number:, container: nil)
+        @raw_pathname = pathname
+        @raw_line_number = line_number
+        @raw_container = container
       end
 
-      # Prints the pathname and line number of the location most likely to be the source of the
-      #   test failure
+      # Generates a formatted string describing the line of code similar to the original backtrace
       #
-      # @return [String] ex. 'path/to/file.rb:12'
+      # @return [String] a consistently-formatted, human-readable string about the line of code
       def to_s
-        "#{most_relevant_file}:#{most_relevant_failure_line}"
-      end
-
-      def local?
-        broken_test? || proper_failure?
+        "#{absolute_path}#{filename}:#{line_number} in `#{container}`"
       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.
+      # Generates a simplified location array with the pathname and line number
       #
-      # @return [Boolean] true if most relevant file is the same as the test location file
-      def broken_test?
-        !test_file.nil? && test_file == most_relevant_file
+      # @return [Array<Pathname, Integer>] a no-frills location pair
+      def to_a
+        [
+          pathname,
+          line_number
+        ]
       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.
+      # A short relative pathname and line number pair
       #
-      # @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_file.nil? && !broken_test?
+      # @return [String] the short filename/line number combo. ex. `dir/file.rb:23`
+      def short
+        "#{relative_filename}:#{line_number}"
       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.
+      # Determine if there is a file and text at the given line number
       #
-      # @return [String] the relative path to the file from the project root
-      def most_relevant_file
-        Pathname(most_relevant_location.pathname)
+      # @return [Boolean] true if the file exists and has text at the given line number
+      def exists?
+        pathname.exist? && source_code.lines.any?
       end
 
-      # The line number of the `most_relevant_file` where the failure originated
+      # The pathanme for the location. Written to be safe and fallbackto the project directory if
+      #   an exception is raised ocnverting the value to a pathname
       #
-      # @return [Integer] line number
-      def most_relevant_failure_line
-        most_relevant_location.line_number
+      # @return [Pathname] a pathname instance for the relevant file
+      def pathname
+        Pathname(raw_pathname)
+      rescue ArgumentError
+        Pathname(Dir.pwd)
       end
 
-      # The final location of the stacktrace regardless of whether it's from within the project
+      # A safe interface to getting a string representing the path portion of the file
       #
-      # @return [String] the relative path to the file from the project root
-      def final_file
-        Pathname(final_location.pathname)
+      # @return [String] either the path/directory portion of the file name or '(Unrecognized File)'
+      #   if the offending file can't be found for some reason
+      def path
+        pathname.exist? ? pathname.dirname.to_s : UNRECOGNIZED
       end
 
-      # The line number of the `final_file` where the failure originated
-      #
-      # @return [Integer] line number
-      def final_failure_line
-        final_location.line_number
+      def absolute_path
+        pathname.exist? ? "#{path}/" : UNRECOGNIZED
       end
 
-      # The final location of the stacktrace regardless of whether it's from within the project
-      #
-      # @return [String] the relative path to the file from the project root
-      def project_file
-        broken_test? ? test_file : source_code_file
+      def relative_path
+        pathname.exist? ? absolute_path.delete_prefix("#{project_root_dir}/") : UNRECOGNIZED
       end
 
-      # The line number of the `project_file` where the failure originated
+      # A safe interface for getting a string representing the filename portion of the file
       #
-      # @return [Integer] line number
-      def project_failure_line
-        broken_test? ? test_failure_line || test_definition_line : source_code_failure_line
+      # @return [String] either the filename portion of the file or '(Unrecognized File)'
+      #   if the offending file can't be found for some reason
+      def filename
+        pathname.exist? ? pathname.basename.to_s : UNRECOGNIZED
       end
 
-      # The final location from the stacktrace that is within the project directory
-      #
-      # @return [String, nil] the relative path to the file from the project root
-      def source_code_file
-        return nil unless backtrace.source_code_entries.any?
+      def absolute_filename
+        pathname.exist? ? pathname.to_s : UNRECOGNIZED
+      end
 
-        backtrace.final_source_code_location.pathname
+      def relative_filename
+        pathname.exist? ? pathname.to_s.delete_prefix("#{project_root_dir}/") : UNRECOGNIZED
       end
 
-      # The line number of the `source_code_file` where the failure originated
+      # Line number identifying the specific line in the file
+      #
+      # @return [Integer] line number for the file
       #
-      # @return [Integer] line number
-      def source_code_failure_line
-        return nil unless backtrace.source_code_entries.any?
+      def line_number
+        Integer(raw_line_number)
+      rescue ArgumentError
+        1
+      end
 
-        backtrace.final_source_code_location.line_number
+      # The containing method or block details for the location
+      #
+      # @return [String] the containing method of the line of code
+      def container
+        raw_container.nil? ? '(Unknown Container)' : String(raw_container)
       end
 
-      # The final location from the stacktrace that is within the project's test directory
+      # Looks up the source code for the location. Can return multiple lines of source code from
+      #   the surrounding lines of code for the primary line
       #
-      # @return [String, nil] the relative path to the file from the project root
-      def test_file
-        Pathname(test_location.pathname)
+      # @param [Integer] max_line_count: 1 the maximum number of lines to return from the source
+      #
+      # @return [Source] an instance of Source for accessing lines and their line numbers
+      def source_code(max_line_count: 1)
+        Minitest::Heat::Source.new(
+          pathname.to_s,
+          line_number: line_number,
+          max_line_count: max_line_count
+        )
       end
 
-      # The line number of the `test_file` where the test is defined
+      # Determines if a given file is from the project directory
       #
-      # @return [Integer] line number
-      def test_definition_line
-        test_location.line_number
+      # @return [Boolean] true if the file is in the project (source code or test)
+      def project_file?
+        path.include?(project_root_dir)
       end
 
-      # The line number from within the `test_file` test definition where the failure occurred
+      # Determines if a given file follows the standard approaching to naming test files.
       #
-      # @return [Integer] line number
-      def test_failure_line
-        backtrace.final_test_location&.line_number || test_definition_line
+      # @return [Boolean] true if the file name starts with `test_` or ends with `_test.rb`
+      def test_file?
+        filename.to_s.start_with?('test_') || filename.to_s.end_with?('_test.rb')
       end
 
-      # The line number from within the `test_file` test definition where the failure occurred
+      # Determines if a given file is a non-test file from the project directory
       #
-      # @return [Location] the last location from the backtrace or the test location if a backtrace
-      #   was not passed to the initializer
-      def final_location
-        backtrace? ? backtrace.final_location : test_location
+      # @return [Boolean] true if the file is in the project but not a test file
+      def source_code_file?
+        project_file? && !test_file?
       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.
+      # A safe interface to getting the last modified time for the file in question
       #
-      # @return [Array] file and line number of the most likely source of the problem
-      def most_relevant_location
-        [
-          source_code_location,
-          test_location,
-          final_location
-        ].compact.first
+      # @return [Time] the timestamp for when the file in question was last modified or `Time.at(0)`
+      #   if the offending file can't be found for some reason
+      def mtime
+        pathname.exist? ? pathname.mtime : UNKNOWN_MODIFICATION_TIME
       end
 
-      def project_location
-        source_code_location || test_location
+      # A safe interface to getting the number of seconds since the file was modified
+      #
+      # @return [Integer] the number of seconds since the file was modified or `-1` if the offending
+      #   file can't be found for some reason
+      def age_in_seconds
+        pathname.exist? ? seconds_ago : UNKNOWN_MODIFICATION_SECONDS
       end
 
-      def source_code_location
-        backtrace.final_source_code_location
+      private
+
+      def project_root_dir
+        Dir.pwd
       end
 
-      def backtrace?
-        backtrace.parsed_entries.any?
+      def seconds_ago
+        (Time.now - mtime).to_i
       end
     end
   end

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,43 +2,39 @@
 
 module Minitest
   module Heat
+    # Structured approach to collecting the locations of issues for generating a heat map
     class Map
       MAXIMUM_FILES_TO_SHOW = 5
 
       attr_reader :hits
 
-      # So we can sort hot spots by liklihood of being the most important spot to check out before
-      #   trying to fix something. These are ranked based on the possibility they represent ripple
-      #   effects where fixing one problem could potentially fix multiple other failures.
-      #
-      #   For example, if there's an exception in the file, start there. Broken code can't run. If a
-      #   test is broken (i.e. raising an exception), that's a special sort of failure that would be
-      #   misleading. It doesn't represent a proper failure, but rather a test that doesn't work.
-      WEIGHTS = {
-        error: 3,    # exceptions from source code have the highest liklihood of a ripple effect
-        broken: 2,   # broken tests won't have ripple effects but can't help if they can't run
-        failure: 1,  # failures are kind of the whole point, and they could have ripple effects
-        skipped: 0,  # skips aren't failures, but they shouldn't go ignored
-        painful: 0,  # slow tests aren't failures, but they shouldn't be ignored
-        slow: 0
-      }.freeze
-
       def initialize
         @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

@@ -5,14 +5,14 @@ module Minitest
     class Output
       # Builds the collection of tokens for a backtrace when an exception occurs
       class Backtrace
-        DEFAULT_LINE_COUNT = 5
+        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
 
@@ -21,18 +21,8 @@ module Minitest
           # 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
+          backtrace_locations.each do |location|
+            @tokens << backtrace_location_tokens(location)
           end
 
           @tokens
@@ -51,56 +41,74 @@ module Minitest
         # ...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
+        def backtrace_locations
+          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) }
+        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 project_root_dir
-          Dir.pwd
-        end
-
-        def project_entries
-          backtrace.project_entries.take(line_count)
-        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)
+        def most_recently_modified?(location)
           # 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
+          backtrace_locations.size > 1 && location == locations.freshest
         end
 
         def indentation_token
           [:default, ' ' * indentation]
         end
 
-        def path_token(line)
-          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
 
-          [:muted, path]
+          [style, location.send(path_format)]
         end
 
-        def file_and_line_number_tokens(backtrace_entry)
-          [[:default, backtrace_entry.file], [:muted, ':'], [:default, backtrace_entry.line_number]]
+        def file_and_line_number_tokens(location)
+          style = location.to_s.include?(Dir.pwd) ? :bold : :muted
+          [
+            [style, location.filename],
+            [:muted, ':'],
+            [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