minitest-heat 0.0.9 → 0.0.13

data/lib/minitest/heat/issue.rb

@@ -17,36 +17,68 @@ module Minitest
         painful: 3.0
       }.freeze
 
-      attr_reader :result, :location, :failure
-
-      def_delegators :@result, :passed?, :error?, :skipped?
-      def_delegators :@location, :backtrace, :test_definition_line, :test_failure_line
-
-      def initialize(result)
-        @result = result
+      attr_reader :assertions,
+                  :locations,
+                  :message,
+                  :test_class,
+                  :test_identifier,
+                  :execution_time,
+                  :passed,
+                  :error,
+                  :skipped
+
+      def_delegators :@locations, :backtrace, :test_definition_line, :test_failure_line
+
+      # Extracts the necessary data from result.
+      # @param result [Minitest::Result] the instance of Minitest::Result to examine
+      #
+      # @return [Issue] the instance of the issue to use for examining the result
+      def self.from_result(result)
+        # Not all results are failures, so we use the safe navigation operator
+        exception = result.failure&.exception
+
+        new(
+          assertions: result.assertions,
+          test_location: result.source_location,
+          test_class: result.klass,
+          test_identifier: result.name,
+          execution_time: result.time,
+          passed: result.passed?,
+          error: result.error?,
+          skipped: result.skipped?,
+          message: exception&.message,
+          backtrace: exception&.backtrace
+        )
+      end
+
+      # Creates an instance of Issue. In general, the `from_result` approach will be more convenient
+      #   for standard usage, but for lower-level purposes like testing, the initializer provides3
+      #   more fine-grained control
+      # @param assertions: 1 [Integer] the number of assertions in the result
+      # @param message: nil [String] exception if there is one
+      # @param backtrace: [] [Array<String>] the array of backtrace lines from an exception
+      # @param test_location: nil [Array<String, Integer>] the locations identifier for a test
+      # @param test_class: nil [String] the class name for the test result's containing class
+      # @param test_identifier: nil [String] the name of the test
+      # @param execution_time: nil [Float] the time it took to run the test
+      # @param passed: false [Boolean] true if the test explicitly passed, false otherwise
+      # @param error: false [Boolean] true if the test raised an exception
+      # @param skipped: false [Boolean] true if the test was skipped
+      #
+      # @return [type] [description]
+      def initialize(assertions: 1, test_location: ['Unrecognized Test File', 1], backtrace: [], execution_time: 0.0, message: nil, test_class: nil, test_identifier: nil, passed: false, error: false, skipped: false)
+        @message = message
 
-        @failure = result.failures.any? ? result.failures.first : nil
-        @location = Location.new(result.source_location, @failure&.backtrace)
-      end
+        @assertions = Integer(assertions)
+        @locations = Locations.new(test_location, backtrace)
 
-      # Returns the primary location of the issue with the present working directory removed from
-      #   the string for conciseness
-      #
-      # @return [String] the pathname for the file relative to the present working directory
-      def short_location
-        location.to_s.delete_prefix("#{Dir.pwd}/")
-      end
+        @test_class = test_class
+        @test_identifier = test_identifier
+        @execution_time = Float(execution_time)
 
-      # Converts an issue to the key attributes for recording a 'hit'
-      #
-      # @return [Array] the filename, failure line, and issue type for categorizing a 'hit' to
-      #   support generating the heat map
-      def to_hit
-        [
-          location.project_file.to_s,
-          Integer(location.project_failure_line),
-          type
-        ]
+        @passed = passed
+        @error = error
+        @skipped = skipped
       end
 
       # Classifies different issue types so they can be categorized, organized, and prioritized.
@@ -58,7 +90,7 @@ module Minitest
       #   painfully slow and should get more attention.
       #
       # @return [Symbol] issue type for classifying issues and reporting
-      def type
+      def type # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         if error? && in_test?
           :broken
         elsif error?
@@ -67,9 +99,9 @@ module Minitest
           :skipped
         elsif !passed?
           :failure
-        elsif painful?
+        elsif passed? && painful?
           :painful
-        elsif slow?
+        elsif passed? && slow?
           :slow
         else
           :success
@@ -81,93 +113,98 @@ module Minitest
       #
       # @return [Boolean] true if the test did not pass or if it was slow
       def hit?
-        !passed? || slow?
+        !passed? || slow? || painful?
+      end
+
+      # The number, in seconds, for a test to be considered "slow"
+      #
+      # @return [Float] number of seconds after which a test is considered slow
+      def slow_threshold
+        # Using a method here so that this can eventually be configurable such that the constant is
+        # only a fallback value if it's not specified anywhere else
+        SLOW_THRESHOLDS[:slow]
+      end
+
+      # The number, in seconds, for a test to be considered "painfully slow"
+      #
+      # @return [Float] number of seconds after which a test is considered painfully slow
+      def painfully_slow_threshold
+        # Using a method here so that this can eventually be configurable such that the constant is
+        # only a fallback value if it's not specified anywhere else
+        SLOW_THRESHOLDS[:painful]
       end
 
       # Determines if a test should be considered slow by comparing it to the low end definition of
       #   what is considered slow.
       #
-      # @return [Boolean] true if the test took longer to run than `SLOW_THRESHOLDS[:slow]`
+      # @return [Boolean] true if the test took longer to run than `slow_threshold`
       def slow?
-        time >= SLOW_THRESHOLDS[:slow]
+        execution_time >= slow_threshold && execution_time < painful_threshold
       end
 
       # Determines if a test should be considered painfully slow by comparing it to the high end
       #   definition of what is considered slow.
       #
-      # @return [Boolean] true if the test took longer to run than `SLOW_THRESHOLDS[:painful]`
+      # @return [Boolean] true if the test took longer to run than `painful_threshold`
       def painful?
-        time >= SLOW_THRESHOLDS[:painful]
+        execution_time >= painful_threshold
       end
 
       # Determines if the issue is an exception that was raised from directly within a test
       #   definition. In these cases, it's more likely to be a quick fix.
       #
-      # @return [Boolean] true if the final location of the stacktrace was a test file
+      # @return [Boolean] true if the final locations of the stacktrace was a test file
       def in_test?
-        location.broken_test?
+        locations.broken_test?
       end
 
       # Determines if the issue is an exception that was raised from directly within the project
       #   codebase.
       #
-      # @return [Boolean] true if the final location of the stacktrace was a file from the project
+      # @return [Boolean] true if the final locations of the stacktrace was a file from the project
       #   (as opposed to a dependency or Ruby library)
       def in_source?
-        location.proper_failure?
-      end
-
-      def test_class
-        result.klass
+        locations.proper_failure?
       end
 
-      def test_identifier
-        result.name
-      end
-
-      def test_name
-        test_identifier.delete_prefix('test_').gsub('_', ' ').capitalize
-      end
-
-      def exception
-        failure.exception
-      end
-
-      def time
-        result.time
+      # Was the result a pass? i.e. Skips aren't passes or failures. Slows are still passes. So this
+      #   is purely a measure of whether the test explicitly passed all assertions
+      #
+      # @return [Boolean] false for errors, failures, or skips, true for passes (including slows)
+      def passed?
+        passed
       end
 
-      def slowness
-        "#{time.round(2)}s"
+      # Was there an exception that triggered a failure?
+      #
+      # @return [Boolean] true if there's an exception
+      def error?
+        error
       end
 
-      def label
-        if error? && in_test?
-          # When the exception came out of the test itself, that's a different kind of exception
-          # that really only indicates there's a problem with the code in the test. It's kind of
-          # between an error and a test.
-          'Broken Test'
-        elsif error? || !passed?
-          failure.result_label
-        elsif painful?
-          'Passed but Very Slow'
-        elsif slow?
-          'Passed but Slow'
-        end
+      # Was the test skipped?
+      #
+      # @return [Boolean] true if the test was explicitly skipped, false otherwise
+      def skipped?
+        skipped
       end
 
+      # The more nuanced detail of the failure. If it's an error, digs into the exception. Otherwise
+      #   uses the message from the result
+      #
+      # @return [String] a more detailed explanation of the issue
       def summary
-        error? ? exception_parts[0] : exception.message
+        # When there's an exception, use the first line from the exception message. Otherwise,  the
+        #   message represents explanation for a test failure, and should be used in full
+        error? ? first_line_of_exception_message : message
       end
 
-      def freshest_file
-        backtrace.recently_modified.first
-      end
-
-      private
-
-      def exception_parts
-        exception.message.split("\n")
+      # Returns the first line of an exception message when the issue is from a proper exception
+      #   failure since exception messages can be long and cumbersome.
+      #
+      # @return [String] the first line of the exception message
+      def first_line_of_exception_message
+        message.split("\n")[0]
       end
     end
   end

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