minitest-heat 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c760c15a45811d5773dee18e32aadc063ed61c3eb04447c637719d5d3d46178a
-  data.tar.gz: 90c345c56cbd2589719eef8a0264a5973f77a8104c91149f4e4ad2320067a49a
+  metadata.gz: 5a8979e12c498f8e4d98e6988356639ab3601b04f1ab38da7af6de1cc6ef8a16
+  data.tar.gz: b8e7a5ec05630043cd50ecfbfa4e42dcf0c53b2984b95cb971ff806c2e8863f8
 SHA512:
-  metadata.gz: 47be296804a2171023bfcdb5c4192376698349bd76c4c3a2991d9accd9f631b88d2ffb867d821f2479c41bd6fd2cf919af325ecde975f98ee4592277b3b09432
-  data.tar.gz: 79a180260e9a1d8c55d898883f13969f2576ceb6450dc9e080050e55674c73fc7979202a2c8a78542958491fce91fee2a3cb1b66fd2705edc4a8d432f5e28fcc
+  metadata.gz: 1df9dc10973d664bdcf0e1690e44c98907f1b59056e7948f16f5bc9d97a4a9b8d989dfebc73d0ad4a88ce35b1253614d340ebd941c451ce12b3be89dad58aabd
+  data.tar.gz: ff6a30b6e5e37f7efce044307a2f3265c1332654d62270571223392913d85566982bcf11add206eca60c58c58d3adf87e46010714591487a15af882ad7996def

data/.gitignore

@@ -6,3 +6,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+/rubocop_cache/

data/.rubocop.yml

@@ -0,0 +1,23 @@
+AllCops:
+  NewCops: enable
+  UseCache: true
+  CacheRootDirectory: './'
+  Exclude:
+    - 'bin/**/*'
+    - 'test/files/source.rb' # An example test file for reading source code
+
+# Let's aim for 80, but we don't need to be nagged if we judiciously go over.
+Layout/LineLength:
+  Enabled: false
+
+# One case statement in a single method isn't complex.
+Metrics/CyclomaticComplexity:
+  IgnoredMethods: ['case']
+
+# 10 is a good goal but a little draconian
+Metrics/MethodLength:
+  CountAsOne: ['array', 'hash', 'heredoc']
+  Max: 15
+
+Style/ClassAndModuleChildren:
+  Enabled: false

data/Gemfile

@@ -1,7 +1,9 @@
-source "https://rubygems.org"
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in minitest-heat.gemspec
 gemspec
 
-gem "rake", "~> 12.0"
-gem "minitest", "~> 5.0"
+gem 'minitest', '~> 5.0'
+gem 'rake', '~> 12.0'

data/Gemfile.lock

@@ -1,37 +1,66 @@
 PATH
   remote: .
   specs:
-    minitest-heat (0.0.5)
+    minitest-heat (0.0.6)
       minitest
 
 GEM
   remote: https://rubygems.org/
   specs:
+    ast (2.4.2)
+    awesome_print (1.9.2)
     coderay (1.1.3)
     dead_end (1.1.7)
     docile (1.4.0)
     method_source (1.0.0)
     minitest (5.14.4)
+    parallel (1.21.0)
+    parser (3.0.2.0)
+      ast (~> 2.4.1)
     pry (0.14.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
+    rainbow (3.0.0)
     rake (12.3.3)
+    regexp_parser (2.1.1)
+    rexml (3.2.5)
+    rubocop (1.22.1)
+      parallel (~> 1.10)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.12.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.12.0)
+      parser (>= 3.0.1.1)
+    rubocop-minitest (0.15.1)
+      rubocop (>= 0.90, < 2.0)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
+    ruby-progressbar (1.11.0)
     simplecov (0.21.2)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.3)
+    unicode-display_width (2.1.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  awesome_print
   dead_end
   minitest (~> 5.0)
   minitest-heat!
   pry
   rake (~> 12.0)
+  rubocop
+  rubocop-minitest
+  rubocop-rake
   simplecov
 
 BUNDLED WITH

data/README.md

@@ -1,8 +1,9 @@
 # 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.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/minitest/heat`. To experiment with that code, run `bin/console` for an interactive prompt.
+Minitest::Heat aims to surface context around test failures to help you more efficiently identify and prioritize fixing failed tests to help save time.
 
-TODO: Delete this and the text above, and describe your gem
+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.
 
 ## Installation
 
@@ -20,9 +21,17 @@ Or install it yourself as:
 
     $ gem install minitest-heat
 
+And add this line to your `test/test_helper.rb` file:
+
+```ruby
+require 'minitest/heat'
+```
+
 ## Usage
 
-TODO: Write usage instructions here
+**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.
 
 ## Development
 

data/Rakefile

@@ -1,10 +1,12 @@
-require "bundler/gem_tasks"
-require "rake/testtask"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
 end
 
-task :default => :test
+task default: :test

data/lib/minitest/heat/backtrace.rb

@@ -4,42 +4,6 @@ module Minitest
   module Heat
     # Wrapper for separating backtrace into component parts
     class Backtrace
-      Line = Struct.new(:path, :file, :number, :container, :mtime, keyword_init: true) do
-        def to_s
-          "#{location} in `#{container}`"
-        end
-
-        def pathname
-          Pathname("#{path}/#{file}")
-        end
-
-        def location
-          "#{pathname.to_s}:#{number}"
-        end
-
-        def short_pathname
-          pathname.delete_prefix(Dir.pwd)
-        end
-
-        def short_location
-          "#{pathname.basename.to_s}:#{number}"
-        end
-
-        def age_in_seconds
-          (Time.now - mtime).to_i
-        end
-      end
-
-      UNREADABLE_FILE_ATTRIBUTES = {
-        path: '(Unknown Path)',
-        file: '(Unknown File)',
-        number: '(Unknown Line Number)',
-        container: '(Unknown Method)',
-        mtime: '(Unknown Modification Time)'
-      }
-
-      UNREADABLE_LINE = Line.new(UNREADABLE_FILE_ATTRIBUTES)
-
       attr_reader :raw_backtrace
 
       def initialize(raw_backtrace)
@@ -51,74 +15,55 @@ module Minitest
       end
 
       def final_location
-        parsed_lines.first
+        parsed_entries.first
       end
 
       def final_project_location
-        project_lines.first
+        project_entries.first
       end
 
       def freshest_project_location
-        recently_modified_lines.first
+        recently_modified_entries.first
       end
 
       def final_source_code_location
-        source_code_lines.first
+        source_code_entries.first
       end
 
       def final_test_location
-        test_lines.first
+        test_entries.first
       end
 
-      def project_lines
-        @project_lines ||= parsed_lines.select { |line| line[:path].include?(Dir.pwd) }
+      def project_entries
+        @project_entries ||= parsed_entries.select { |entry| entry.path.to_s.include?(Dir.pwd) }
       end
 
-      def recently_modified_lines
-        @recently_modified_lines ||= project_lines.sort_by { |line| line[:mtime] }.reverse
+      def recently_modified_entries
+        @recently_modified_entries ||= project_entries.sort_by(&:mtime).reverse
       end
 
-      def test_lines
-        @tests_lines ||= project_lines.select { |line| test_file?(line) }
+      def test_entries
+        @tests_entries ||= project_entries.select { |entry| test_file?(entry) }
       end
 
-      def source_code_lines
-        @source_code_lines ||= project_lines - test_lines
+      def source_code_entries
+        @source_code_entries ||= project_entries - test_entries
       end
 
-      def parsed_lines
+      def parsed_entries
         return [] if raw_backtrace.nil?
 
-        @parsed_lines ||= raw_backtrace.map { |line| parse(line) }
+        @parsed_entries ||= raw_backtrace.map { |entry| Line.parse_backtrace(entry) }
       end
 
       private
 
-      def reduce_container(container)
-        container.delete_prefix('in `').delete_suffix("'")
-      end
-
-      def parse(line)
-        Line.new(line_attributes(line))
-      end
-
-      def line_attributes(line)
-        parts = line.split(':')
-        pathname = Pathname.new(parts[0])
-
-        {
-          path: pathname.dirname.to_s,
-          file: pathname.basename.to_s,
-          number: parts[1],
-          container: reduce_container(parts[2]),
-          mtime: pathname.exist? ? pathname.mtime : nil
-        }
-      rescue
-        UNREADABLE_FILE_ATTRIBUTES
+      def parse(entry)
+        Line.parse_backtrace(entry)
       end
 
-      def test_file?(line)
-        line[:file].end_with?('_test.rb') || line[:file].start_with?('test_')
+      def test_file?(entry)
+        entry.file.to_s.end_with?('_test.rb') || entry.file.to_s.start_with?('test_')
       end
     end
   end

data/lib/minitest/heat/hit.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+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
+    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
+      #   effects where fixing one problem could potentially fix multiple other failures.
+      #
+      #   For example, if there's an exception in the file, start there. Broken code can't run. If a
+      #   test is broken (i.e. raising an exception), that's a special sort of failure that would be
+      #   misleading. It doesn't represent a proper failure, but rather a test that doesn't work.
+      WEIGHTS = {
+        error: 3,    # exceptions from source code have the highest likelihood of a ripple effect
+        broken: 2,   # broken tests won't have ripple effects but can't help if they can't run
+        failure: 1,  # failures are kind of the whole point, and they could have ripple effects
+        skipped: 0,  # skips aren't failures, but they shouldn't go ignored
+        painful: 0,  # slow tests aren't failures, but they shouldn't be ignored
+        slow: 0
+      }.freeze
+
+      attr_reader :pathname, :issues
+
+      def initialize(pathname)
+        @pathname = Pathname(pathname)
+        @issues = {}
+      end
+
+      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 critical_issues?
+        issues[:error].any? || issues[:broken].any? || issues[:failure].any?
+      end
+
+      def issue_count
+        count = 0
+        Issue::TYPES.each do |issue_type|
+          count += issues.fetch(issue_type) { [] }.size
+        end
+        count
+      end
+
+      def weight
+        weight = 0
+        issues.each_pair do |type, values|
+          weight += values.size * WEIGHTS.fetch(type, 0)
+        end
+        weight
+      end
+
+      def count
+        count = 0
+        issues.each_pair do |_type, values|
+          count += values.size
+        end
+        count
+      end
+
+      def line_numbers
+        line_numbers = []
+        issues.each_pair do |_type, values|
+          line_numbers += values
+        end
+        line_numbers.uniq.sort
+      end
+    end
+  end
+end

data/lib/minitest/heat/issue.rb

@@ -8,24 +8,13 @@ module Minitest
     class Issue
       extend Forwardable
 
+      TYPES = %i[error broken failure skipped painful slow].freeze
+
+      # Long-term, these could be configurable so that people can determine their own thresholds of
+      # pain for slow tests
       SLOW_THRESHOLDS = {
         slow: 1.0,
         painful: 3.0
-      }
-
-      MARKERS = {
-        success:  '·',
-        slow:     '–',
-        painful:  '—',
-        broken:   'B',
-        error:    'E',
-        skipped:  'S',
-        failure:  'F',
-      }
-
-      SHARED_SYMBOLS = {
-        spacer: ' · ',
-        arrow: ' > '
       }.freeze
 
       attr_reader :result, :location, :failure
@@ -40,10 +29,18 @@ module Minitest
         @location = Location.new(result.source_location, @failure&.backtrace)
       end
 
+      # 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
 
+      # 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,
@@ -52,15 +49,16 @@ module Minitest
         ]
       end
 
-      def spacer
-        SHARED_SYMBOLS[:spacer]
-      end
-
-      def arrow
-        SHARED_SYMBOLS[:arrow]
-      end
-
-      def type # rubocop:disable Metrics/MethodLength
+      # Classifies different issue types so they can be categorized, organized, and prioritized.
+      #   Primarily helps add some nuance to issue types. For example, an exception that arises from
+      #   the project's source code is a genuine exception. But if the exception arose directly from
+      #   the test, then it's more likely that there's just a simple syntax issue in the test.
+      #   Similarly, the difference between a moderately slow test and a painfully slow test can be
+      #   significant. A test that takes half a second is slow, but a test that takes 10 seconds is
+      #   painfully slow and should get more attention.
+      #
+      # @return [Symbol] issue type for classifying issues and reporting
+      def type
         if error? && in_test?
           :broken
         elsif error?
@@ -78,22 +76,43 @@ module Minitest
         end
       end
 
+      # Determines if the issue is a proper 'hit' which is anything that doesn't pass or is slow.
+      #   (Because slow tests still pass and wouldn't otherwise be considered an issue.)
+      #
+      # @return [Boolean] true if the test did not pass or if it was slow
       def hit?
         !passed? || slow?
       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]`
       def slow?
         time >= SLOW_THRESHOLDS[:slow]
       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]`
       def painful?
         time >= SLOW_THRESHOLDS[:painful]
       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
       def in_test?
         location.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
+      #   (as opposed to a dependency or Ruby library)
       def in_source?
         location.proper_failure?
       end
@@ -127,20 +146,16 @@ module Minitest
           # 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.
-          'Test Error'
+          'Broken Test'
         elsif error? || !passed?
           failure.result_label
+        elsif painful?
+          'Passed but Very Slow'
         elsif slow?
           'Passed but Slow'
-        else
-
         end
       end
 
-      def marker
-        MARKERS.fetch(type.to_sym)
-      end
-
       def summary
         error? ? exception_parts[0] : exception.message
       end

data/lib/minitest/heat/line.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module Minitest
+  module Heat
+    # Represents a line of code from the project and provides convenient access to information about
+    #  the line for displaying in test results
+    class Line
+      attr_accessor :pathname, :number, :container
+      alias line_number number
+
+      def initialize(pathname:, number:, container: nil)
+        @pathname = Pathname(pathname)
+        @number = number.to_i
+        @container = container.to_s
+      end
+
+      # Convenient interface to read a line from a backtrace 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
+
+      def to_s
+        "#{location} in `#{container}`"
+      end
+
+      def path
+        pathname.exist? ? pathname.dirname : UNRECOGNIZED
+      end
+
+      def file
+        pathname.exist? ? pathname.basename : UNRECOGNIZED
+      end
+
+      def mtime
+        pathname.exist? ? pathname.mtime : UNKNOWN_MODIFICATION_TIME
+      end
+
+      def age_in_seconds
+        pathname.exist? ? seconds_ago : UNKNOWN_MODIFICATION_SECONDS
+      end
+
+      def location
+        "#{pathname}:#{number}"
+      end
+
+      def short_location
+        "#{file}:#{number}"
+      end
+
+      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
+
+      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