minitest-heat 0.0.9 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b06865dbf64c7b926b600aa635f27e00a0ac65cd08c25cc35ac2ee4de1768a0
-  data.tar.gz: 79ba518f1b7137992f35ac2489ac09c6d5687ae5a8c68e166995a63277e02f99
+  metadata.gz: 6c60c717971a6a1858de4337247b8bfd37f63a63f31a1783de4ecaaad8ca5a8c
+  data.tar.gz: c491cb526bd8a243810fe88da7d15679a6c5182b256a5187db4c457bcc9b7a7a
 SHA512:
-  metadata.gz: 3e5450a68e065e1573a21acba73537e2a003afdc098e7aab6eed2b41638c66a82d74a97faf3d94c9cb79c6279ebda7567dee4bd6a5bec75599e11c170c07e5dc
-  data.tar.gz: 8386cc9f07313cec0686e5efce192a9a7763b78a628ea0eb2b428890a7f5d43e30c472fe4dbcc65497fc2d908d7fc79457a5784890e583951b33dec964259cbf
+  metadata.gz: abf3a4c476c1041f75fedfa3eac1235f134bc99bbbf1c909e6e407e461380e9028079e3ad927180d7bec4f039c54247172c9a12bee579dec5eab53b444cf3f68
+  data.tar.gz: fb7d2373153fdaaf6fe8b3a6ec693baf3e04a8fa8dc5636f75d1b0afb45e5a7b25365f3dbe44b0aa3c53bb79b8ed7b0551c3798ceaa3477ce1d9e122159e116a

data/.rubocop.yml

@@ -2,6 +2,7 @@ AllCops:
   NewCops: enable
   UseCache: true
   CacheRootDirectory: './'
+  TargetRubyVersion: 2.5.9
   Exclude:
     - 'bin/**/*'
     - 'test/files/source.rb' # An example test file for reading source code

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    minitest-heat (0.0.9)
+    minitest-heat (0.0.10)
       minitest
 
 GEM

data/README.md

@@ -21,7 +21,7 @@ Or install it yourself as:
 
     $ gem install minitest-heat
 
-And add this line to your `test/test_helper.rb` file:
+And depending on your usage, you may need to require Minitest Heat in your test suite:
 
 ```ruby
 require 'minitest/heat'

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module Minitest
+  module Heat
+    class Backtrace
+      # Represents a line from a backtrace to provide more convenient access to information about
+      #   the relevant file and line number for displaying in test results
+      class Line
+        attr_accessor :pathname, :number, :container
+        alias line_number number
+
+        # Creates an instance of a line number reference
+        # @param pathname: [Pathname, String] the full pathname to the file
+        # @param number: [Integer, String] the line number in question
+        # @param container: nil [String] the containing method or block for the line of code
+        #
+        # @return [self]
+        def initialize(pathname:, number:, container: nil)
+          @pathname = Pathname(pathname)
+          @number = number.to_i
+          @container = container.to_s
+        end
+
+        # Parses a line from a backtrace in order to convert it to usable components
+        def self.parse_backtrace(raw_text)
+          raw_pathname, raw_line_number, raw_container = raw_text.split(':')
+          raw_container = raw_container.delete_prefix('in `').delete_suffix("'")
+
+          new(pathname: raw_pathname, number: raw_line_number, container: raw_container)
+        end
+
+        # Generates a formatted string describing the line of code similar to the original backtrace
+        #
+        # @return [String] a consistently-formatted, human-readable string about the line of code
+        def to_s
+          "#{location} in `#{container}`"
+        end
+
+        # A safe interface to getting a string representing the path portion of the file
+        #
+        # @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 : UNRECOGNIZED
+        end
+
+        # A safe interface for getting a string representing the filename portion of the file
+        #
+        # @return [String] either the filename portion of the file or '(Unrecognized File)'
+        #   if the offending file can't be found for some reason
+        def file
+          pathname.exist? ? pathname.basename : UNRECOGNIZED
+        end
+
+        # A safe interface to getting the last modified time for the file in question
+        #
+        # @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
+
+        # 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
+
+        # A convenient method for getting the full location identifier using the full pathname and
+        #   line number separated by a `:`
+        #
+        # @return [String] the full pathname and line number
+        def location
+          "#{pathname}:#{number}"
+        end
+
+        # A convenient method for getting the short location with `Dir.pwd` removed
+        #
+        # @return [String] the relative pathname and line number
+        def short_location
+          "#{file}:#{number}"
+        end
+
+        # A convenient method for getting the line of source code for the offending line number
+        #
+        # @return [String] the source code for the file/line number combination
+        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
+
+        # Determines if a given file follows the standard approaching to naming test files.
+        #
+        # @return [Boolean] true if the file name starts with `test_` or ends with `_test.rb`
+        def test_file?
+          file.to_s.start_with?('test_') || file.to_s.end_with?('_test.rb')
+        end
+
+        private
+
+        UNRECOGNIZED = '(Unrecognized File)'
+        UNKNOWN_MODIFICATION_TIME = Time.at(0)
+        UNKNOWN_MODIFICATION_SECONDS = -1
+
+        def seconds_ago
+          (Time.now - mtime).to_i
+        end
+      end
+    end
+  end
+end

data/lib/minitest/heat/backtrace.rb

@@ -1,69 +1,103 @@
 # frozen_string_literal: true
 
+require_relative 'backtrace/line'
+
 module Minitest
   module Heat
     # Wrapper for separating backtrace into component parts
     class Backtrace
       attr_reader :raw_backtrace
 
+      # Creates a more flexible backtrace data structure by parsing the lines of the backtrace to
+      #   extract individual elements for investigating the offending files and line numbers
+      # @param raw_backtrace [Array] the array of lines from the backtrace
+      #
+      # @return [self]
       def initialize(raw_backtrace)
-        @raw_backtrace = raw_backtrace
+        @raw_backtrace = Array(raw_backtrace)
       end
 
+      # Determines if the raw backtrace has values in it
+      #
+      # @return [Boolean] true if there's no backtrace or it's empty
       def empty?
-        raw_backtrace.nil? || raw_backtrace.empty?
+        raw_backtrace.empty?
       end
 
+      # The final location exposed in the backtrace. Could be a line from the project or from a
+      #   dependency or the Ruby core libraries
+      #
+      # @return [Line] the final location from the backtrace parsed as a Backtrace::Line
       def final_location
         parsed_entries.first
       end
 
+      # The final location from within the project exposed in the backtrace. Could be test files or
+      #   source code files
+      #
+      # @return [Line] the final project location from the backtrace parsed as a Backtrace::Line
       def final_project_location
         project_entries.first
       end
 
+      # The most recently modified location from within the project
+      #
+      # @return [Line] the most recently modified project location from the backtrace parsed as a
+      #   Backtrace::Line
       def freshest_project_location
         recently_modified_entries.first
       end
 
+      # The final location from within the project source code (i.e. excluding tests)
+      #
+      # @return [Line] the final source code location from the backtrace parsed as a Backtrace::Line
       def final_source_code_location
         source_code_entries.first
       end
 
+      # The final location from within the project's tests (i.e. excluding source code)
+      #
+      # @return [Line] the final test location from the backtrace parsed as a Backtrace::Line
       def final_test_location
         test_entries.first
       end
 
+      # All entries from the backtrace that are files within the project
+      #
+      # @return [Line] the backtrace lines from within the project parsed as Backtrace::Line's
       def project_entries
         @project_entries ||= parsed_entries.select { |entry| entry.path.to_s.include?(Dir.pwd) }
       end
 
+      # All entries from the backtrace within the project and sorted with the most recently modified
+      #   files at the beginning
+      #
+      # @return [Line] the sorted backtrace lines from the project parsed as Backtrace::Line's
       def recently_modified_entries
         @recently_modified_entries ||= project_entries.sort_by(&:mtime).reverse
       end
 
+      # All entries from the backtrace within the project tests
+      #
+      # @return [Line] the backtrace lines from within the project tests parsed as Backtrace::Line's
       def test_entries
-        @tests_entries ||= project_entries.select { |entry| test_file?(entry) }
+        @test_entries ||= project_entries.select(&:test_file?)
       end
 
+      # All source code entries from the backtrace (i.e. excluding tests)
+      #
+      # @return [Line] the backtrace lines from within the source code parsed as Backtrace::Line's
       def source_code_entries
         @source_code_entries ||= project_entries - test_entries
       end
 
+      # All lines of the backtrace converted to Backtrace::Line's
+      #
+      # @return [Line] the full set of backtrace lines parsed as Backtrace::Line instances
       def parsed_entries
         return [] if raw_backtrace.nil?
 
-        @parsed_entries ||= raw_backtrace.map { |entry| Line.parse_backtrace(entry) }
-      end
-
-      private
-
-      def parse(entry)
-        Line.parse_backtrace(entry)
-      end
-
-      def test_file?(entry)
-        entry.file.to_s.end_with?('_test.rb') || entry.file.to_s.start_with?('test_')
+        @parsed_entries ||= raw_backtrace.map { |entry| Backtrace::Line.parse_backtrace(entry) }
       end
     end
   end

data/lib/minitest/heat/hit.rb

@@ -5,7 +5,7 @@ require 'forwardable'
 module Minitest
   module Heat
     # Kind of like an issue, but instead of focusing on a failing test, it covers all issues for a
-    #   given file
+    #   given file to build a heat map of the affected files
     class Hit
       # 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
@@ -25,32 +25,31 @@ module Minitest
 
       attr_reader :pathname, :issues
 
+      # Creates an instance of a Hit for the given pathname. It must be the full pathname to
+      #   uniquely identify the file or we could run into collisions that muddy the water and
+      #   obscure which files had which errors on which line numbers
+      # @param pathname [Pathname,String] the full pathname to the file
+      #
+      # @return [self]
       def initialize(pathname)
         @pathname = Pathname(pathname)
         @issues = {}
       end
 
+      # Adds a record of a given issue type for the line number
+      # @param type [Symbol] one of Issue::TYPES
+      # @param line_number [Integer,String] the line number to record the issue on
+      #
+      # @return [type] [description]
       def log(type, line_number)
         @issues[type] ||= []
-        @issues[type] << line_number
-      end
-
-      def mtime
-        pathname.mtime
-      end
-
-      def age_in_seconds
-        (Time.now - mtime).to_i
-      end
-
-      def issue_count
-        count = 0
-        Issue::TYPES.each do |issue_type|
-          count += issues.fetch(issue_type) { [] }.size
-        end
-        count
+        @issues[type] << Integer(line_number)
       end
 
+      # Calcuates an approximate weight to serve as a proxy for which files are most likely to be
+      #   the most problematic across the various issue types
+      #
+      # @return [Integer] the problem weight for the file
       def weight
         weight = 0
         issues.each_pair do |type, values|
@@ -59,6 +58,9 @@ module Minitest
         weight
       end
 
+      # The total issue count for the file across all issue types. Includes duplicates if they exist
+      #
+      # @return [Integer] the sum of the counts for all line numbers for all issue types
       def count
         count = 0
         issues.each_pair do |_type, values|
@@ -67,6 +69,9 @@ module Minitest
         count
       end
 
+      # The full set of unique line numbers across all issue types
+      #
+      # @return [Array<Integer>] the full set of unique offending line numbers for the hit
       def line_numbers
         line_numbers = []
         issues.each_pair do |_type, values|

data/lib/minitest/heat/issue.rb

@@ -17,36 +17,68 @@ module Minitest
         painful: 3.0
       }.freeze
 
-      attr_reader :result, :location, :failure
+      attr_reader :assertions,
+                  :location,
+                  :message,
+                  :test_class,
+                  :test_identifier,
+                  :execution_time,
+                  :passed,
+                  :error,
+                  :skipped
 
-      def_delegators :@result, :passed?, :error?, :skipped?
       def_delegators :@location, :backtrace, :test_definition_line, :test_failure_line
 
-      def initialize(result)
-        @result = result
+      # 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,
+          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 location: nil [String] the location 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, location: ['unknown', 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)
+        @location = Location.new(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?
@@ -81,7 +113,7 @@ module Minitest
       #
       # @return [Boolean] true if the test did not pass or if it was slow
       def hit?
-        !passed? || slow?
+        !passed? || slow? || painful?
       end
 
       # Determines if a test should be considered slow by comparing it to the low end definition of
@@ -89,7 +121,7 @@ module Minitest
       #
       # @return [Boolean] true if the test took longer to run than `SLOW_THRESHOLDS[:slow]`
       def slow?
-        time >= SLOW_THRESHOLDS[:slow]
+        execution_time >= SLOW_THRESHOLDS[:slow] && execution_time < SLOW_THRESHOLDS[:painful]
       end
 
       # Determines if a test should be considered painfully slow by comparing it to the high end
@@ -97,7 +129,7 @@ module Minitest
       #
       # @return [Boolean] true if the test took longer to run than `SLOW_THRESHOLDS[:painful]`
       def painful?
-        time >= SLOW_THRESHOLDS[:painful]
+        execution_time >= SLOW_THRESHOLDS[:painful]
       end
 
       # Determines if the issue is an exception that was raised from directly within a test
@@ -117,57 +149,44 @@ module Minitest
         location.proper_failure?
       end
 
-      def test_class
-        result.klass
-      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
-      end
-
-      def freshest_file
-        backtrace.recently_modified.first
+        # 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
 
-      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