minitest-heat 0.0.11 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a2dd8d434e13e9719addb1a2afa9f25c751ca6e5712c752244afb1823ac4740
-  data.tar.gz: 722f33b1145d79510f9007b54663198972c1ce4461a7a79c14a7bfdeb190721e
+  metadata.gz: 887dc01f3a08341f1e88cb24b539d0843cdce81fdb49246fbce8af875ff00d3f
+  data.tar.gz: 875d197ab5c65c2cb85b192201375be653ba30da2fc91896b4a3e61702cacefd
 SHA512:
-  metadata.gz: 955b848541141572e94aeff4b02586253f70db8e313af111e54b91c3e8a64c7c44c0f0f90c672f699f9296dc5f691ea04c7852eb948f6ab680173b8261512eee
-  data.tar.gz: 9c3085267bea53a6734a085c982fd8348442715036ccf2b636de9c997f3dc14662e25a709faab1b4425ffb46ceeb109f43672336fadf0bca7c4e0cbbccd0463c
+  metadata.gz: 6ef73c9df5b91b5950cc444f6ea7a18ccd867bda4fbdb015b8d713eaebe91b925a2cfb48b596a43a0d36af023dcb04f5c8ec0803602ab27bf709372fe6f9b0f3
+  data.tar.gz: d338944e9d32e8ec326cce9dbe861c5b8bec408bb455e4e984d45567ef9d9c5af9154f4475c2862ddc43778c95d8e58f12beef8757aa37f6b76d91da1b17a4c5

data/Gemfile.lock

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

data/README.md

@@ -1,12 +1,41 @@
-# Minitest::Heat
-**Important:** As of September 13, 2021, Minitest::Heat is an early work-in-progress. It's usable, but it can still ocasionally be buggy as it takes shape.
+# 🔥 Minitest::Heat 🔥
+Minitest::Heat helps you identify problems faster so you can more efficiently resolve test failures. It does this through a few different methods.
 
-Minitest::Heat aims to surface context around test failures to help you more efficiently identify and prioritize fixing failed tests to help save time.
+It collects failures and inspects backtraces to identify patterns and provide a heat map summary of the files and line numbers that most frequently appear to be the causes of issues.
 
-For some early insight about priorities and how it works, this [Twitter thread](https://twitter.com/garrettdimon/status/1432703746526560266) is currently the best place to start.
+![Example Heat Map Displayed by Minitest Heat](https://raw.githubusercontent.com/garrettdimon/minitest-heat/main/examples/map.png)
 
-## Installation
+It suppresses less critical issues like skips or slows when there are legitimate failures. It won't display information about slow tests unless all tests are passing (meaning no errors, failures, or skips)
+
+It presents failures differently depending on the context of failure. For instance, it treats exceptions differently based on whether they arose directly from a test or from source code. It also treats extremely slow tests differently from moderately slow tests.
+
+Markers get some nuance so that slow tests receive different markers than standard passing tests, and exception-triggered failures get different markers for source-code triggered exceptions (E) and test-triggered exceptions ('B' for 'Broken Test').
+
+![Example Markers Displayed by Minitest Heat](https://raw.githubusercontent.com/garrettdimon/minitest-heat/main/examples/markers.png)
+
+It also formats the failure details and backtraces to make them more scannable by emphasizing the project-relates lines from the backtrace.
+
+It intelligently recognizes when an exception was raised from a test defintion vs. when an exception is genuinely triggered from the source code in order to help focus on fixing deeper exceptions first.
+
+![Example Exceptions Displayed by Minitest Heat](https://raw.githubusercontent.com/garrettdimon/minitest-heat/main/examples/exceptions.png)
+
+Failures are displayed ina  fairly predictable manner but formatted to show the source code from the test so you can see the assertion that failed in addition to the summary of values that didn't satisfy the assertion.
+
+![Example Failures Displayed by Minitest Heat](https://raw.githubusercontent.com/garrettdimon/minitest-heat/main/examples/failures.png)
+
+Skipped tests are displayed in a simple manner as well so that it's easy to see the source of the skipped test as well as the reason it was skipped.
+
+![Example Skips Displayed by Minitest Heat](https://raw.githubusercontent.com/garrettdimon/minitest-heat/main/examples/skips.png)
+
+Slow tests get slightly more informative labels to indicate that they did pass, but they could use performance improvements. Tests that are particularly slow are called out with a little more emphasis so it's easier to focus on really slow tests first as they frequently represent the most potential for performance gains.
 
+![Example Slows Displayed by Minitest Heat](https://raw.githubusercontent.com/garrettdimon/minitest-heat/main/examples/slows.png)
+
+It also always displays the most significant issues at the bottom of the list in order to reduce the need to scroll up through the test failures. As you fix issues, the list becomes shorter, and the less significant issues will make there way to the bottom and be visible without scrolling.
+
+For some additional insight about priorities and how it works, this [Twitter thread](https://twitter.com/garrettdimon/status/1432703746526560266) is currently the best place to start.
+
+## Installation
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -27,27 +56,33 @@ And depending on your usage, you may need to require Minitest Heat in your test
 require 'minitest/heat'
 ```
 
-## Usage
-
-**Important:** In its current state, `Minitest::Heat` replaces any other reporter plugins you may have. Long-term, it should play nicer with other reporters, but during the initial heavy development cycle, it's been easier to have a high confidence that other reporters aren't the source of unexpected behavior.
-
-Otherwise, once it's bundled and added to your `test_helper`, it shold "just work" whenever you run your test suite.
+## Configuration
+Minitest Heat doesn't currently offer a significant set of configuration options, but it will eventually support customizing the thresholds for "Slow" and "Painfully Slow". By default, it considers anything over 1.0s to be 'slow' and anything over 3.0s to be 'painfully slow'.
 
 ## Development
-
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-## Contributing
+### Forcing Test Failures
+In order to easily see how Minitest Heat handles different combinations of different types of failures, the following environment variables can be used to force failures.
+
+```bash
+IMPLODE=true           # Every possible type of failure, skip, and slow is generated
+FORCE_EXCEPTIONS=true  # Only exception-triggered failures
+FORCE_FAILURES=true    # Only standard assertion failures
+FORCE_SKIPS=true       # No errors, just the skipped tests
+FORCE_SLOWS=true       # No errors or skipped tests, just slow tests
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/minitest-heat. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/minitest-heat/blob/master/CODE_OF_CONDUCT.md).
+So to see the full context of a test suite, `IMPLODE=true bundle exec rake` will work its magic.
 
+## Contributing
+Bug reports and pull requests are welcome on GitHub at https://github.com/garrettdimon/minitest-heat. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/minitest-heat/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## Code of Conduct
-
 Everyone interacting in the Minitest::Heat project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/minitest-heat/blob/master/CODE_OF_CONDUCT.md).

data/lib/minitest/heat/backtrace.rb

@@ -26,7 +26,7 @@ module Minitest
 
       # All lines of the backtrace converted to Backtrace::LineParser's
       #
-      # @return [Line] the full set of backtrace lines parsed as Backtrace::LineParser instances
+      # @return [Array<Location>] the full set of backtrace lines parsed as Location instances
       def locations
         return [] if raw_backtrace.nil?
 
@@ -36,28 +36,28 @@ module Minitest
       # 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::LineParser's
+      # @return [Array<Location>] the sorted backtrace lines from the project
       def recently_modified_locations
         @recently_modified_locations ||= project_locations.sort_by(&:mtime).reverse
       end
 
       # All entries from the backtrace that are files within the project
       #
-      # @return [Line] the backtrace lines from within the project parsed as Backtrace::LineParser's
+      # @return [Array<Location>] the backtrace lines from within the project
       def project_locations
         @project_locations ||= locations.select(&:project_file?)
       end
 
       # All entries from the backtrace within the project tests
       #
-      # @return [Line] the backtrace lines from within the project tests parsed as Backtrace::LineParser's
+      # @return [Array<Location>] the backtrace lines from within the tests
       def test_locations
         @test_locations ||= project_locations.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::LineParser's
+      # @return [Array<Location>] the backtrace lines from within the source code
       def source_code_locations
         @source_code_locations ||= project_locations.select(&:source_code_file?)
       end

data/lib/minitest/heat/issue.rb

@@ -99,9 +99,9 @@ module Minitest
           :skipped
         elsif !passed?
           :failure
-        elsif painful?
+        elsif passed? && painful?
           :painful
-        elsif slow?
+        elsif passed? && slow?
           :slow
         else
           :success
@@ -116,20 +116,38 @@ module Minitest
         !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?
-        execution_time >= SLOW_THRESHOLDS[:slow] && execution_time < SLOW_THRESHOLDS[:painful]
+        execution_time >= slow_threshold && execution_time < painfully_slow_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 `painfully_slow_threshold`
       def painful?
-        execution_time >= SLOW_THRESHOLDS[:painful]
+        execution_time >= painfully_slow_threshold
       end
 
       # Determines if the issue is an exception that was raised from directly within a test

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

@@ -3,7 +3,7 @@
 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
@@ -17,31 +17,47 @@ module Minitest
         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_locations.each do |location|
-            @tokens << backtrace_location_tokens(location)
-          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?
+        # 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
 
@@ -65,8 +81,17 @@ module Minitest
           backtrace_locations.all?(&:project_file?)
         end
 
+        # 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, and the current line is the freshest
+          # 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
 

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

@@ -14,28 +14,16 @@ module Minitest
 
         def tokens
           case issue.type
-          when :error then error_tokens
-          when :broken then broken_tokens
-          when :failure then failure_tokens
-          when :skipped then skipped_tokens
-          when :painful then painful_tokens
-          when :slow then slow_tokens
+          when :error, :broken  then exception_tokens
+          when :failure         then failure_tokens
+          when :skipped         then skipped_tokens
+          when :painful, :slow  then slow_tokens
           end
         end
 
         private
 
-        def error_tokens
-          [
-            headline_tokens,
-            test_location_tokens,
-            summary_tokens,
-            *backtrace_tokens,
-            newline_tokens
-          ]
-        end
-
-        def broken_tokens
+        def exception_tokens
           [
             headline_tokens,
             test_location_tokens,
@@ -62,14 +50,6 @@ module Minitest
           ]
         end
 
-        def painful_tokens
-          [
-            headline_tokens,
-            slowness_summary_tokens,
-            newline_tokens
-          ]
-        end
-
         def slow_tokens
           [
             headline_tokens,
@@ -79,9 +59,14 @@ module Minitest
         end
 
         def headline_tokens
-          [[issue.type, label(issue)], spacer_token, [:default, test_name(issue)]]
+          [label_token(issue), spacer_token, [:default, test_name(issue)]]
         end
 
+        # Creates a display-friendly version of the test name with underscores removed and the
+        #   first letter capitalized regardless of the formatt used for the test definition
+        # @param issue [Issue] the issue to use to generate the test name
+        #
+        # @return [String] the cleaned up version of the test name
         def test_name(issue)
           test_prefix = 'test_'
           identifier = issue.test_identifier
@@ -93,35 +78,14 @@ module Minitest
           end
         end
 
-        def label(issue) # rubocop:disable Metrics
-          if issue.error? && issue.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 issue.error?
-            'Error'
-          elsif issue.skipped?
-            'Skipped'
-          elsif issue.painful?
-            'Passed but Very Slow'
-          elsif issue.slow?
-            'Passed but Slow'
-          elsif !issue.passed?
-            'Failure'
-          else
-            'Success'
-          end
+        def label_token(issue)
+          [issue.type, issue_label(issue.type)]
         end
 
         def test_name_and_class_tokens
           [[:default, issue.test_class], *test_location_tokens]
         end
 
-        def backtrace_tokens
-          @backtrace_tokens ||= ::Minitest::Heat::Output::Backtrace.new(locations).tokens
-        end
-
         def test_location_tokens
           [
             [:default, locations.test_definition.relative_filename],
@@ -180,6 +144,27 @@ module Minitest
         def arrow_token
           Output::TOKENS[:muted_arrow]
         end
+
+        def backtrace_tokens
+          @backtrace_tokens ||= ::Minitest::Heat::Output::Backtrace.new(locations).tokens
+        end
+
+        # The string to use to describe the failure type when displaying results/
+        # @param issue_type [Symbol] the symbol representing the issue's failure type
+        #
+        # @return [String] the display-friendly string describing the failure reason
+        def issue_label(issue_type)
+          case issue_type
+          when :error   then 'Error'
+          when :broken  then 'Broken Test'
+          when :failure then 'Failure'
+          when :skipped then 'Skipped'
+          when :slow    then 'Passed but Slow'
+          when :painful then 'Passed but Very Slow'
+          when :passed  then 'Success'
+          else 'Unknown'
+          end
+        end
       end
     end
   end

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

@@ -14,24 +14,34 @@ module Minitest
 
         def tokens
           results.heat_map.file_hits.each do |hit|
-            # If there's legitimate failures or errors, skips and slows aren't relevant
+            # Focus on the relevant issues based on most significant problems. i.e. If there are
+            # legitimate failures or errors, skips and slows aren't relevant
             next unless relevant_issue_types?(hit)
 
+            # Add a new line
             @tokens << [[:muted, ""]]
+
+            # Build the summary line for the file
             @tokens << file_summary_tokens(hit)
 
-            repeats = repeated_line_numbers(hit)
-            next unless repeats.any?
+            # Get the set of line numbers that appear more than once
+            repeated_line_numbers = find_repeated_line_numbers_in(hit)
 
-            repeats.each do |line_number|
-              @tokens << [[:muted, "  Issues on Line #{line_number} initially triggered from these locations:"]]
+            # Only display more details if the same line number shows up more than once
+            next unless repeated_line_numbers.any?
 
+            repeated_line_numbers.each do |line_number|
+              # Get the backtraces for the given line numbers
               traces = hit.lines[line_number.to_s]
-              sorted_traces = traces.sort_by { |trace| trace.locations.last.line_number }
 
-              sorted_traces.each do |trace|
-                @tokens << origination_location_token(trace)
-              end
+              # If there aren't any traces there's no way to provide additional details
+              break unless traces.any?
+
+              # A short summary explaining the details that will follow
+              @tokens << [[:default, "  Line #{line_number}"], [:muted, ' issues triggered from:']]
+
+              # The last relevant location for each error's backtrace
+              @tokens += origination_sources(traces)
             end
           end
 
@@ -40,16 +50,28 @@ module Minitest
 
         private
 
+        def origination_sources(traces)
+          # 1. Only pull the traces that have proper locations
+          # 2. Sort the traces by the most recent line number so they're displayed in numeric order
+          # 3. Get the final relevant location from the trace
+          traces.
+            select  { |trace| trace.locations.any? }.
+            sort_by { |trace| trace.locations.last.line_number }.
+            map     { |trace| origination_location_token(trace) }
+        end
+
         def file_summary_tokens(hit)
           pathname_tokens = pathname(hit)
-          line_number_list_tokens = sorted_line_number_list(hit)
+          line_number_list_tokens = line_number_tokens_for_hit(hit)
 
           [*pathname_tokens, *line_number_list_tokens]
         end
 
         def origination_location_token(trace)
           # The earliest project line from the backtrace—this is probabyl wholly incorrect in terms
-          # of what would be the most helpful line to display, but it's a start.
+          # of what would be the most helpful line to display, but it's a start. Otherwise, the
+          # logic will need to compare all traces for the issue and find the unique origination
+          # lines
           location = trace.locations.last
 
           [
@@ -58,7 +80,7 @@ module Minitest
             [:muted, ':'],
             [:default, location.line_number],
             [:muted, " in #{location.container}"],
-            [:muted, " #{Output::SYMBOLS[:arrow]} `location.source_code.line.strip`"],
+            [:muted, " #{Output::SYMBOLS[:arrow]} `#{location.source_code.line.strip}`"],
           ]
         end
 
@@ -75,16 +97,18 @@ module Minitest
         end
 
         def relevant_issue_types?(hit)
+          # The intersection of which issue types are relevant based on the context and which issues
+          # matc those issue types
           intersection_issue_types = relevant_issue_types & hit.issues.keys
 
           intersection_issue_types.any?
         end
 
-        def repeated_line_numbers(hit)
+        def find_repeated_line_numbers_in(hit)
           repeated_line_numbers = []
 
           hit.lines.each_pair do |line_number, traces|
-            # If there aren't multiple traces for a line number, it's not a repeat, right?
+            # If there aren't multiple traces for a line number, it's not a repeat
             next unless traces.size > 1
 
             repeated_line_numbers << Integer(line_number)
@@ -93,10 +117,6 @@ module Minitest
           repeated_line_numbers.sort
         end
 
-        def repeated_line_numbers?(hit)
-          repeated_line_numbers(hit).any?
-        end
-
         def pathname(hit)
           directory = hit.pathname.dirname.to_s.delete_prefix("#{Dir.pwd}/")
           filename = hit.pathname.basename.to_s
@@ -108,6 +128,11 @@ module Minitest
           ]
         end
 
+        # Gets the list of line numbers for a given hit location (i.e. file) so they can be
+        #   displayed after the file name to show which lines were problematic
+        # @param hit [Hit] the instance to extract line numbers from
+        #
+        # @return [Array<Symbol,String>] [description]
         def line_number_tokens_for_hit(hit)
           line_number_tokens = []
 
@@ -116,34 +141,50 @@ module Minitest
             line_numbers_for_issue_type = hit.issues.fetch(issue_type) { [] }
 
             # Build the list of tokens representing styled line numbers
-            line_numbers_for_issue_type.each do |line_number|
-              line_number_tokens << line_number_token(issue_type, line_number)
+            line_numbers_for_issue_type.uniq.sort.each do |line_number|
+              frequency = line_numbers_for_issue_type.count(line_number)
+
+              line_number_tokens += line_number_token(issue_type, line_number, frequency)
             end
           end
 
           line_number_tokens.compact
         end
 
-        def line_number_token(style, line_number)
-          [style, "#{line_number} "]
-        end
-
-        # Generates the line number tokens styled based on their error type
+        # Builds a token representing a styled line number
         #
-        # @param [Hit] hit the instance of the hit file details to build the heat map entry
+        # @param style [Symbol] the relevant display style for the issue
+        # @param line_number [Integer] the affected line number
         #
-        # @return [Array] the arrays representing the line number tokens to display next to a file
-        #   name in the heat map
-        def sorted_line_number_list(hit)
-          # Sort the collected group of line number hits so they're in order
-          line_number_tokens_for_hit(hit).sort do |a, b|
-            # Ensure the line numbers are integers for sorting (otherwise '100' comes before '12')
-            first_line_number = Integer(a[1].strip)
-            second_line_number = Integer(b[1].strip)
-
-            first_line_number <=> second_line_number
+        # @return [Array<Symbol,Integer>] array token representing the line number and issue type
+        def line_number_token(style, line_number, frequency)
+          if frequency > 1
+            [
+              [style, "#{line_number}"],
+              [:muted, "✕#{frequency} "]
+            ]
+          else
+            [[style, "#{line_number} "]]
           end
         end
+
+        # # Sorts line number tokens so that line numbers are displayed in order regardless of their
+        # #   underlying issue type
+        # #
+        # # @param hit [Hit] the instance of the hit file details to build the heat map entry
+        # #
+        # # @return [Array] the arrays representing the line number tokens to display next to a file
+        # #   name in the heat map. ex [[:error, 12], [:falure, 13]]
+        # def sorted_line_number_list(hit)
+        #   # Sort the collected group of line number hits so they're in order
+        #   line_number_tokens_for_hit(hit).sort do |a, b|
+        #     # Ensure the line numbers are integers for sorting (otherwise '100' comes before '12')
+        #     first_line_number = Integer(a[1].strip)
+        #     second_line_number = Integer(b[1].strip)
+
+        #     first_line_number <=> second_line_number
+        #   end
+        # end
       end
     end
   end

data/lib/minitest/heat/output.rb

@@ -48,13 +48,20 @@ module Minitest
         newline
 
         # Issues start with the least critical and go up to the most critical so that the most
-        #   pressing issues are displayed at the bottom of the report in order to reduce scrolling.
-        #   This way, as you fix issues, the list gets shorter, and eventually the least critical
-        #   issues will be displayed without scrolling once more problematic issues are resolved.
+        # pressing issues are displayed at the bottom of the report in order to reduce scrolling.
+        #
+        # This way, as you fix issues, the list gets shorter, and eventually the least critical
+        # issues will be displayed without scrolling once more problematic issues are resolved.
         %i[slows painfuls skips failures brokens errors].each do |issue_category|
+          # Only show categories for the most pressing issues after the suite runs, otherwise,
+          # suppress them until the more critical issues are resolved.
           next unless show?(issue_category, results)
 
-          results.send(issue_category).each { |issue| issue_details(issue) }
+          issues = results.send(issue_category)
+
+          issues
+            .sort_by { |issue| issue.locations.most_relevant.to_a }
+            .each { |issue| issue_details(issue) }
         end
       rescue StandardError => e
         message = "Sorry, but Minitest Heat couldn't display the details of any failures."
@@ -64,7 +71,7 @@ module Minitest
       def issue_details(issue)
         print_tokens Minitest::Heat::Output::Issue.new(issue).tokens
       rescue StandardError => e
-        message = "Sorry, but Minitest Heat couldn't display output for a failure."
+        message = "Sorry, but Minitest Heat couldn't display output for a specific failure."
         exception_guidance(message, e)
       end
 
@@ -89,6 +96,15 @@ module Minitest
         exception_guidance(message, e)
       end
 
+      private
+
+      # Displays some guidance related to exceptions generated by Minitest Heat in order to help
+      #   people get back on track (and ideally submit issues)
+      # @param message [String] a slightly more specific explanation of which part of minitest-heat
+      #   caused the failure
+      # @param exception [Exception] the exception that caused the problem
+      #
+      # @return [void] displays the guidance to the console
       def exception_guidance(message, exception)
         newline
         puts "#{message} Disabling Minitest Heat can get you back on track until the problem can be fixed."
@@ -100,8 +116,6 @@ module Minitest
         newline
       end
 
-      private
-
       def no_problems?(results)
         !results.problems?
       end

data/lib/minitest/heat/results.rb

@@ -30,8 +30,20 @@ module Minitest
         # For heat map purposes, only the project backtrace lines are interesting
         pathname, line_number = issue.locations.project.to_a
 
-        # Backtrace is only relevant for exception-generating issues, not slows, skips, or failures
-        backtrace = issue.error? ? issue.locations.backtrace.project_locations : []
+        # A backtrace is only relevant for exception-generating issues (i.e. errors), not slows or skips
+        # However, while assertion failures won't have a backtrace, there can still be repeated line
+        # numbers if the tests reference a shared method with an assertion in it. So in those cases,
+        # the backtrace is simply the test definition
+        backtrace = if issue.error?
+          # With errors, we have a backtrace
+          issue.locations.backtrace.project_locations
+        else
+          # With failures, the test definition is the most granular backtrace equivalent
+          location = issue.locations.test_definition
+          location.raw_container = issue.test_identifier
+
+          [location]
+        end
 
         @heat_map.add(pathname, line_number, issue.type, backtrace: backtrace)
       end

data/lib/minitest/heat/version.rb

@@ -2,6 +2,6 @@
 
 module Minitest
   module Heat
-    VERSION = '0.0.11'
+    VERSION = '1.0.0'
   end
 end

data/lib/minitest/heat_reporter.rb

@@ -96,7 +96,7 @@ module Minitest
       # The list of individual issues and their associated details
       output.issues_list(results)
 
-      # Display a short summary of the total issue counts fore ach category as well as performance
+      # Display a short summary of the total issue counts for each category as well as performance
       # details for the test suite as a whole
       output.compact_summary(results, timer)
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: minitest-heat
 version: !ruby/object:Gem::Version
-  version: 0.0.11
+  version: 1.0.0
 platform: ruby
 authors:
 - Garrett Dimon
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-11-15 00:00:00.000000000 Z
+date: 2021-12-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -141,6 +141,12 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- examples/exceptions.png
+- examples/failures.png
+- examples/map.png
+- examples/markers.png
+- examples/skips.png
+- examples/slows.png
 - lib/minitest/heat.rb
 - lib/minitest/heat/backtrace.rb
 - lib/minitest/heat/backtrace/line_parser.rb