minitest-heat 0.0.10 → 0.0.14

data/lib/minitest/heat/location.rb

@@ -2,197 +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_definition_location, :backtrace
+      attr_accessor :raw_pathname, :raw_line_number, :raw_container
 
-      def initialize(test_definition_location, backtrace = [])
-        @test_definition_location = TestDefinition.new(*test_definition_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 final file in the backtrace is the same as the test location file
-      def broken_test?
-        !test_file.nil? && test_file == final_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 final location of the stacktrace regardless of whether it's from within the project
+      # 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 final_file
-        Pathname(final_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 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.
+      # 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 [String] the relative path to the file from the project root
-      def most_relevant_file
-        Pathname(most_relevant_location.pathname)
+      # @return [Pathname] a pathname instance for the relevant file
+      def pathname
+        Pathname(raw_pathname)
+      rescue ArgumentError
+        Pathname(Dir.pwd)
       end
 
-      # The final location from the stacktrace that is a test file
+      # A safe interface to getting a string representing the path portion of the file
       #
-      # @return [String, nil] the relative path to the file from the project root
-      def test_file
-        Pathname(final_test_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 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 if final_source_code_location.nil?
+      def absolute_path
+        pathname.exist? ? "#{path}/" : UNRECOGNIZED
+      end
 
-        Pathname(final_source_code_location.pathname)
+      def relative_path
+        pathname.exist? ? absolute_path.delete_prefix("#{project_root_dir}/") : UNRECOGNIZED
       end
 
-      # The final location of the stacktrace from within the project (source code or test code)
+      # A safe interface for getting a string representing the filename portion of the file
       #
-      # @return [String] the relative path to the file from the project root
-      def project_file
-        return nil if project_location.nil?
-
-        Pathname(project_location.pathname)
+      # @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
 
+      def absolute_filename
+        pathname.exist? ? pathname.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 relative_filename
+        pathname.exist? ? pathname.to_s.delete_prefix("#{project_root_dir}/") : UNRECOGNIZED
       end
 
-      # The line number of the `most_relevant_file` where the failure originated
+      # Line number identifying the specific line in the file
       #
-      # @return [Integer] line number
-      def most_relevant_failure_line
-        most_relevant_location.line_number
+      # @return [Integer] line number for the file
+      #
+      def line_number
+        Integer(raw_line_number)
+      rescue ArgumentError
+        1
       end
 
-      # The line number of the `test_file` where the test is defined
+      # The containing method or block details for the location
       #
-      # @return [Integer] line number
-      def test_definition_line
-        test_definition_location.line_number
+      # @return [String] the containing method of the line of code
+      def container
+        raw_container.nil? ? '(Unknown Container)' : String(raw_container)
       end
 
-      # The line number from within the `test_file` test definition where the failure occurred
+      # 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
+      #
+      # @param [Integer] max_line_count: 1 the maximum number of lines to return from the source
       #
-      # @return [Integer] line number
-      def test_failure_line
-        final_test_location.line_number
+      # @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 `source_code_file` where the failure originated
+      # Determines if a given file is from the project directory
       #
-      # @return [Integer] line number
-      def source_code_failure_line
-        final_source_code_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 of the `project_file` where the failure originated
+      # Determines if a given file follows the standard approaching to naming test files.
       #
-      # @return [Integer] line number
-      def project_failure_line
-        if !broken_test? && !source_code_file.nil?
-          source_code_failure_line
-        else
-          test_failure_line
-        end
+      # @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.parsed_entries.any? ? backtrace.final_location : test_definition_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
-        [
-          final_source_code_location,
-          final_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
 
-      # Returns the final test location based on the backtrace if present. Otherwise falls back to
-      #   the test location which represents the test definition.
+      # A safe interface to getting the number of seconds since the file was modified
       #
-      # @return [Location] the final location from the test files
-      def final_test_location
-        backtrace.final_test_location || test_definition_location
+      # @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
 
-      # Returns the final source code location based on the backtrace
-      #
-      # @return [Location] the final location from the source code files
-      def final_source_code_location
-        backtrace.final_source_code_location
+      private
+
+      def project_root_dir
+        Dir.pwd
       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_location
-        backtrace.final_project_location || test_definition_location
+      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

@@ -18,10 +18,9 @@ module Minitest
       # @param type [Symbol] the type of issue that was encountered (i.e. :failure, :error, etc.)
       #
       # @return [void]
-      def add(filename, line_number, type)
-        @hits[filename] ||= Hit.new(filename)
-
-        @hits[filename].log(type.to_sym, line_number)
+      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

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

@@ -3,115 +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 = backtrace_line_tokens(backtrace_entry)
-
-            # If it's the most recently modified file in the trace, add the token for that
-            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 backtrace_line_tokens(backtrace_entry)
+        def backtrace_location_tokens(location)
           [
             indentation_token,
-            path_token(backtrace_entry),
-            *file_and_line_number_tokens(backtrace_entry),
-            source_code_line_token(backtrace_entry.source_code)
-          ]
-        end
-
-        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)
+            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 containining_element_token(location)
+          return nil if !location.project_file? || location.container.nil? || location.container.empty?
+
+          [:muted, " in #{location.container}"]
         end
 
-        def file_freshness(_line)
+        def most_recently_modified_token(location)
+          return nil unless most_recently_modified?(location)
+
           [:default, " #{Output::SYMBOLS[:middot]} Most Recently Modified File"]
         end
 
@@ -126,10 +148,6 @@ module Minitest
         def indentation
           DEFAULT_INDENTATION_SPACES
         end
-
-        def style_for(path)
-          path.to_s.include?(Dir.pwd) ? :default : :muted
-        end
       end
     end
   end