tldr 0.1.0

data/lib/tldr/assertions.rb

@@ -0,0 +1,365 @@
+# While all the methods in this file were written for TLDR, they were designed
+# to maximize compatibility with minitest's assertions API and messages here:
+#
+#   https://github.com/minitest/minitest/blob/master/lib/minitest/assertions.rb
+#
+# As a result, many implementations are extremely similar to those found in
+# minitest. Any such implementations are Copyright © Ryan Davis, seattle.rb and
+# distributed under the MIT License
+
+require "pp"
+require "super_diff"
+require_relative "assertions/minitest_compatibility"
+
+class TLDR
+  module Assertions
+    def self.h obj
+      obj.pretty_inspect.chomp
+    end
+
+    def self.msg message = nil, &default
+      proc {
+        message = message.call if Proc === message
+        [message.to_s, default.call].reject(&:empty?).join("\n")
+      }
+    end
+
+    def self.diff expected, actual
+      SuperDiff::EqualityMatchers::Main.call(expected:, actual:)
+    end
+
+    def self.capture_io
+      captured_stdout, captured_stderr = StringIO.new, StringIO.new
+
+      original_stdout, original_stderr = $stdout, $stderr
+      $stdout, $stderr = captured_stdout, captured_stderr
+
+      yield
+
+      [captured_stdout.string, captured_stderr.string]
+    ensure
+      $stdout = original_stdout
+      $stderr = original_stderr
+    end
+
+    def assert bool, message = nil
+      message ||= "Expected #{Assertions.h(bool)} to be truthy"
+
+      if bool
+        true
+      else
+        message = message.call if Proc === message
+        fail Failure, message
+      end
+    end
+
+    def refute test, message = nil
+      message ||= Assertions.msg(message) { "Expected #{Assertions.h(test)} to not be truthy" }
+      assert !test, message
+    end
+
+    def assert_empty obj, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(obj)} to be empty"
+      }
+
+      assert_respond_to obj, :empty?
+      assert obj.empty?, message
+    end
+
+    def refute_empty obj, message = nil
+      message = Assertions.msg(message) { "Expected #{Assertions.h(obj)} to not be empty" }
+      assert_respond_to obj, :empty?
+      refute obj.empty?, message
+    end
+
+    def assert_equal expected, actual, message = nil
+      message = Assertions.msg(message) { Assertions.diff expected, actual }
+      assert expected == actual, message
+    end
+
+    def refute_equal expected, actual, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(actual)} to not be equal to #{Assertions.h(expected)}"
+      }
+      refute expected == actual, message
+    end
+
+    def assert_in_delta expected, actual, delta, message = nil
+      difference = (expected - actual).abs
+      message = Assertions.msg(message) {
+        "Expected |#{expected} - #{actual}| (#{difference}) to be within #{delta}"
+      }
+      assert delta >= difference, message
+    end
+
+    def refute_in_delta expected, actual, delta = 0.001, message = nil
+      difference = (expected - actual).abs
+      message = Assertions.msg(message) {
+        "Expected |#{expected} - #{actual}| (#{difference}) to not be within #{delta}"
+      }
+      refute delta >= difference, message
+    end
+
+    def assert_in_epsilon expected, actual, epsilon = 0.001, message = nil
+      assert_in_delta expected, actual, [expected.abs, actual.abs].min * epsilon, message
+    end
+
+    def refute_in_epsilon expected, actual, epsilon = 0.001, msg = nil
+      refute_in_delta expected, actual, expected * epsilon, msg
+    end
+
+    def assert_include? expected, actual, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(actual)} to include #{Assertions.h(expected)}"
+      }
+      assert_respond_to actual, :include?
+      assert actual.include?(expected), message
+    end
+
+    def refute_include? expected, actual, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(actual)} to not include #{Assertions.h(expected)}"
+      }
+      assert_respond_to actual, :include?
+      refute actual.include?(expected), message
+    end
+
+    def assert_instance_of expected, actual, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(actual)} to be an instance of #{expected}, not #{actual.class}"
+      }
+      assert actual.instance_of?(expected), message
+    end
+
+    def refute_instance_of expected, actual, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(actual)} to not be an instance of #{expected}"
+      }
+      refute actual.instance_of?(expected), message
+    end
+
+    def assert_kind_of expected, actual, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(actual)} to be a kind of #{expected}, not #{actual.class}"
+      }
+      assert actual.kind_of?(expected), message # standard:disable Style/ClassCheck
+    end
+
+    def refute_kind_of expected, actual, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(actual)} to not be a kind of #{expected}"
+      }
+      refute actual.kind_of?(expected), message # standard:disable Style/ClassCheck
+    end
+
+    def assert_match matcher, actual, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(actual)} to match #{Assertions.h(matcher)}"
+      }
+      assert_respond_to matcher, :=~
+      matcher = Regexp.new Regexp.escape matcher if String === matcher
+      assert matcher =~ actual, message
+      Regexp.last_match
+    end
+
+    def refute_match matcher, actual, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(actual)} to not match #{Assertions.h(matcher)}"
+      }
+      assert_respond_to matcher, :=~
+      refute matcher =~ actual, message
+    end
+
+    def assert_nil obj, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(obj)} to be nil"
+      }
+
+      assert obj.nil?, message
+    end
+
+    def refute_nil obj, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(obj)} to not be nil"
+      }
+
+      refute obj.nil?, message
+    end
+
+    def assert_operator left_operand, operator, right_operand, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(left_operand)} to be #{operator} #{Assertions.h(right_operand)}"
+      }
+      assert left_operand.__send__(operator, right_operand), message
+    end
+
+    def refute_operator left_operand, operator, right_operand, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(left_operand)} to not be #{operator} #{Assertions.h(right_operand)}"
+      }
+      refute left_operand.__send__(operator, right_operand), message
+    end
+
+    def assert_output expected_stdout, expected_stderr, message = nil, &block
+      assert_block "assert_output requires a block to capture output" unless block
+
+      actual_stdout, actual_stderr = Assertions.capture_io(&block)
+
+      if Regexp === expected_stderr
+        assert_match expected_stderr, actual_stderr, "In stderr"
+      elsif !expected_stderr.nil?
+        assert_equal expected_stderr, actual_stderr, "In stderr"
+      end
+
+      if Regexp === expected_stdout
+        assert_match expected_stdout, actual_stdout, "In stdout"
+      elsif !expected_stdout.nil?
+        assert_equal expected_stdout, actual_stdout, "In stdout"
+      end
+    end
+
+    def assert_path_exists path, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(path)} to exist"
+      }
+
+      assert File.exist?(path), message
+    end
+
+    def refute_path_exists path, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(path)} to not exist"
+      }
+
+      refute File.exist?(path), message
+    end
+
+    def assert_pattern message = nil
+      assert false, "assert_pattern requires a block to capture errors" unless block_given?
+
+      begin
+        yield
+      rescue NoMatchingPatternError => e
+        assert false, Assertions.msg(message) { "Expected pattern match: #{e.message}" }
+      end
+    end
+
+    def refute_pattern message = nil
+      assert false, "assert_pattern requires a block to capture errors" unless block_given?
+
+      begin
+        yield
+        refute true, Assertions.msg(message) { "Expected pattern not to match, but NoMatchingPatternError was raised" }
+      rescue NoMatchingPatternError
+      end
+    end
+
+    def assert_predicate obj, method, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(obj)} to be #{method}"
+      }
+
+      assert obj.send(method), message
+    end
+
+    def refute_predicate obj, method, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(obj)} to not be #{method}"
+      }
+
+      refute obj.send(method), message
+    end
+
+    def assert_raises *exp
+      assert false, "assert_raises requires a block to capture errors" unless block_given?
+
+      message = exp.pop if String === exp.last
+      exp << StandardError if exp.empty?
+
+      begin
+        yield
+      rescue Failure, Skip
+        raise
+      rescue *exp => e
+        return e
+      rescue SignalException, SystemExit
+        raise
+      rescue Exception => e # standard:disable Lint/RescueException
+        assert false, Assertions.msg(message) {
+          [
+            "#{Assertions.h(exp)} exception expected, not",
+            "Class: <#{e.class}>",
+            "Message: <#{e.message.inspect}>",
+            "---Backtrace---",
+            TLDR.filter_backtrace(e.backtrace).join("\n"),
+            "---------------"
+          ].compact.join "\n"
+        }
+      end
+
+      exp = exp.first if exp.size == 1
+
+      assert false, "#{message}#{Assertions.h(exp)} expected but nothing was raised"
+    end
+
+    def assert_respond_to obj, method, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(obj)} (#{obj.class}) to respond to #{Assertions.h(method)}"
+      }
+
+      assert obj.respond_to?(method), message
+    end
+
+    def refute_respond_to obj, method, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(obj)} (#{obj.class}) to not respond to #{Assertions.h(method)}"
+      }
+
+      refute obj.respond_to?(method), message
+    end
+
+    def assert_same expected, actual, message = nil
+      message = Assertions.msg(message) {
+        <<~MSG
+          Expected objects to be the same, but weren't
+          Expected: #{Assertions.h(expected)} (oid=#{expected.object_id})
+          Actual: #{Assertions.h(actual)} (oid=#{actual.object_id})
+        MSG
+      }
+      assert expected.equal?(actual), message
+    end
+
+    def refute_same expected, actual, message = nil
+      message = Assertions.msg(message) {
+        "Expected #{Assertions.h(expected)} (oid=#{expected.object_id}) to not be the same as #{Assertions.h(actual)} (oid=#{actual.object_id})"
+      }
+      refute expected.equal?(actual), message
+    end
+
+    def assert_silent
+      assert_output "", "" do
+        yield
+      end
+    end
+
+    def assert_throws expected, message = nil
+      punchline = nil
+      caught = true
+      value = catch(expected) do
+        begin
+          yield
+        rescue ArgumentError => e
+          raise e unless e.message.include?("uncaught throw")
+          punchline = ", not #{e.message.split(" ").last}"
+        end
+        caught = false
+      end
+
+      assert caught, Assertions.msg(message) {
+        "Expected #{Assertions.h(expected)} to have been thrown#{punchline}"
+      }
+      value
+    end
+  end
+end

data/lib/tldr/backtrace_filter.rb

@@ -0,0 +1,44 @@
+class TLDR
+  class BacktraceFilter
+    BASE_PATH = __dir__.freeze
+    SORBET_RUNTIME_PATTERN = %r{sorbet-runtime.*[/\\]lib[/\\]types[/\\]private[/\\]}
+    CONCURRENT_RUBY_PATTERN = %r{concurrent-ruby.*[/\\]lib[/\\]concurrent-ruby[/\\]concurrent[/\\]}
+
+    def filter backtrace
+      return ["No backtrace"] unless backtrace
+      return backtrace.dup if $DEBUG
+
+      trim_leading_frames(backtrace) ||
+        trim_internal_frames(backtrace) ||
+        backtrace.dup
+    end
+
+    private
+
+    def trim_leading_frames backtrace
+      if (trimmed = backtrace.take_while { |frame| meaningful? frame }).any?
+        trimmed
+      end
+    end
+
+    def trim_internal_frames backtrace
+      if (trimmed = backtrace.select { |frame| meaningful? frame }).any?
+        trimmed
+      end
+    end
+
+    def meaningful? frame
+      !internal? frame
+    end
+
+    def internal? frame
+      frame.start_with?(BASE_PATH) ||
+        frame.match?(SORBET_RUNTIME_PATTERN) ||
+        frame.match?(CONCURRENT_RUBY_PATTERN)
+    end
+  end
+
+  def self.filter_backtrace backtrace
+    BacktraceFilter.new.filter backtrace
+  end
+end

data/lib/tldr/error.rb

@@ -0,0 +1,7 @@
+class TLDR
+  class Error < StandardError; end
+
+  class Failure < Exception; end # standard:disable Lint/InheritException
+
+  class Skip < StandardError; end
+end

data/lib/tldr/planner.rb

@@ -0,0 +1,170 @@
+require "pathname"
+
+class TLDR
+  class Planner
+    def plan config
+      search_locations = expand_search_locations config.paths
+
+      prepend_load_paths config
+      require_test_helper config
+      require_tests search_locations
+
+      tests = gather_tests
+      config.update_after_gathering_tests! tests
+
+      Plan.new prepend(
+        shuffle(
+          exclude_by_path(
+            exclude_by_name(
+              filter_by_line(
+                filter_by_name(tests, config.names),
+                search_locations
+              ),
+              config.exclude_names
+            ),
+            config.exclude_paths
+          ),
+          config.seed
+        ),
+        config
+      )
+    end
+
+    private
+
+    def expand_search_locations path_strings
+      path_strings.flat_map { |path_string|
+        File.directory?(path_string) ? Dir["#{path_string}/**/*.rb"] : path_string
+      }.flat_map { |path_string|
+        absolute_path = File.expand_path(path_string.gsub(/:.*$/, ""), Dir.pwd)
+        line_numbers = path_string.scan(/:(\d+)/).flatten.map(&:to_i)
+
+        if line_numbers.any?
+          line_numbers.map { |line_number| Location.new absolute_path, line_number }
+        else
+          [Location.new(absolute_path, nil)]
+        end
+      }.uniq
+    end
+
+    def gather_tests
+      gather_descendants(TLDR).flat_map { |subklass|
+        subklass.instance_methods.grep(/^test_/).sort.map { |method|
+          file, line = SorbetCompatibility.unwrap_method(subklass.instance_method(method)).source_location
+          Test.new subklass, method, file, line
+        }
+      }
+    end
+
+    def prepend tests, config
+      return tests if config.no_prepend
+      prepended_locations = expand_search_locations expand_globs config.prepend_tests
+      prepended, rest = tests.partition { |test|
+        locations_include_test? prepended_locations, test
+      }
+      prepended + rest
+    end
+
+    def shuffle tests, seed
+      tests.shuffle(random: Random.new(seed))
+    end
+
+    def exclude_by_path tests, exclude_paths
+      excluded_locations = expand_search_locations expand_globs exclude_paths
+      return tests if excluded_locations.empty?
+
+      tests.reject { |test|
+        locations_include_test? excluded_locations, test
+      }
+    end
+
+    def exclude_by_name tests, exclude_names
+      return tests if exclude_names.empty?
+
+      name_excludes = expand_names_with_patterns exclude_names
+
+      tests.reject { |test|
+        name_excludes.any? { |filter|
+          filter === test.method.to_s || filter === "#{test.klass}##{test.method}"
+        }
+      }
+    end
+
+    def filter_by_line tests, search_locations
+      line_specific_locations = search_locations.reject { |location| location.line.nil? }
+      return tests if line_specific_locations.empty?
+
+      tests.select { |test|
+        locations_include_test? line_specific_locations, test
+      }
+    end
+
+    def filter_by_name tests, names
+      return tests if names.empty?
+
+      name_filters = expand_names_with_patterns names
+
+      tests.select { |test|
+        name_filters.any? { |filter|
+          filter === test.method.to_s || filter === "#{test.klass}##{test.method}"
+        }
+      }
+    end
+
+    def prepend_load_paths config
+      config.load_paths.each do |load_path|
+        $LOAD_PATH.unshift File.expand_path(load_path, Dir.pwd)
+      end
+    end
+
+    def require_test_helper config
+      return if config.no_helper || config.helper.nil? || !File.exist?(config.helper)
+      require File.expand_path(config.helper, Dir.pwd)
+    end
+
+    def require_tests search_locations
+      search_locations.each do |location|
+        require location.file
+      end
+    end
+
+    def gather_descendants root_klass
+      root_klass.subclasses + root_klass.subclasses.flat_map { |subklass|
+        gather_descendants subklass
+      }
+    end
+
+    def locations_include_test? locations, test
+      locations.any? { |location|
+        location.file == test.file && (location.line.nil? || test.covers_line?(location.line))
+      }
+    end
+
+    # Because search paths to TLDR can include line numbers (e.g. a.rb:4), we
+    # can't just pass everything to Dir.glob. Instead, we have to check whether
+    # a user-provided search path looks like a glob, and if so, expand it
+    #
+    # Globby characters specified here:
+    # https://ruby-doc.org/3.2.2/Dir.html#method-c-glob
+    def expand_globs search_paths
+      search_paths.flat_map { |search_path|
+        if search_path.match?(/[*?\[\]{}]/)
+          raise Error, "Can't combine globs and line numbers in: #{search_path}" if search_path.match?(/:(\d+)$/)
+          Dir[search_path]
+        else
+          search_path
+        end
+      }
+    end
+
+    def expand_names_with_patterns names
+      names.map { |name|
+        if name.is_a?(String) && name =~ /^\/(.*)\/$/
+          Regexp.new $1
+        else
+          name
+        end
+      }
+    end
+  end
+end

data/lib/tldr/reporters/base.rb

@@ -0,0 +1,36 @@
+class TLDR
+  module Reporters
+    class Base
+      def initialize(config, out = $stdout, err = $stderr)
+        out.sync = true
+        err.sync = true
+
+        @config = config
+        @out = out
+        @err = err
+      end
+
+      # Will be called before any tests are run
+      def before_suite tests
+      end
+
+      # Will be called after each test, unless the run has already been aborted
+      def after_test test_result
+      end
+
+      # Will be called after all tests have run, unless the run was aborted
+      #
+      # Exactly ONE of `after_suite`, `after_tldr`, or `after_fail_fast` will be called
+      def after_suite test_results
+      end
+
+      # Called after the suite-wide time limit expires and the run is aborted
+      def after_tldr planned_tests, wip_tests, test_results
+      end
+
+      # Called after the first test fails when --fail-fast is enabled, aborting the run
+      def after_fail_fast planned_tests, wip_tests, test_results, last_result
+      end
+    end
+  end
+end