tldr 0.10.1 → 1.1.0

data/lib/tldr/argv_parser.rb

@@ -5,21 +5,41 @@ class TLDR
     PATTERN_FRIENDLY_SPLITTER = /,(?=(?:[^\/]*\/[^\/]*\/)*[^\/]*$)/
 
     def parse args, options = {cli_defaults: true}
+      og_args = args.dup
       OptionParser.new do |opts|
         opts.banner = "Usage: tldr [options] some_tests/**/*.rb some/path.rb:13 ..."
 
-        opts.on CONFLAGS[:fail_fast], "Stop running tests as soon as one fails" do |fail_fast|
-          options[:fail_fast] = fail_fast
+        opts.on "-t", "--[no-]timeout [TIMEOUT]", "Timeout (in seconds) before timer aborts the run (Default: #{Config::DEFAULT_TIMEOUT})" do |timeout|
+          options[:timeout] = if timeout == false
+            # --no-timeout
+            -1
+          elsif timeout.nil?
+            # --timeout
+            Config::DEFAULT_TIMEOUT
+          else
+            # --timeout 42.3
+            handle_unparsable_optional_value(og_args, "timeout", timeout) do
+              Float(timeout)
+            end
+          end
         end
 
-        opts.on "-s", "#{CONFLAGS[:seed]} SEED", Integer, "Seed for randomization" do |seed|
-          options[:seed] = seed
+        opts.on CONFLAGS[:watch], "Run your tests continuously on file save (requires 'fswatch' to be installed)" do
+          options[:watch] = true
+        end
+
+        opts.on CONFLAGS[:fail_fast], "Stop running tests as soon as one fails" do |fail_fast|
+          options[:fail_fast] = fail_fast
         end
 
         opts.on CONFLAGS[:parallel], "Parallelize tests (Default: true)" do |parallel|
           options[:parallel] = parallel
         end
 
+        opts.on "-s", "#{CONFLAGS[:seed]} SEED", Integer, "Random seed for test order (setting --seed disables parallelization by default)" do |seed|
+          options[:seed] = seed
+        end
+
         opts.on "-n", "#{CONFLAGS[:names]} PATTERN", "One or more names or /patterns/ of tests to run (like: foo_test, /test_foo.*/, Foo#foo_test)" do |name|
           options[:names] ||= []
           options[:names] += name.split(PATTERN_FRIENDLY_SPLITTER)
@@ -58,54 +78,90 @@ class TLDR
           options[:load_paths] += load_path
         end
 
-        opts.on "-r", "#{CONFLAGS[:reporter]} REPORTER", String, "Set a custom reporter class (Default: \"TLDR::Reporters::Default\")" do |reporter|
-          options[:reporter] = Kernel.const_get(reporter)
-        end
-
         opts.on "#{CONFLAGS[:base_path]} PATH", String, "Change the working directory for all relative paths (Default: current working directory)" do |path|
           options[:base_path] = path
         end
 
-        opts.on CONFLAGS[:no_dotfile], "Disable loading .tldr.yml dotfile" do
-          options[:no_dotfile] = true
+        opts.on "-c", "#{CONFLAGS[:config_path]} PATH", String, "The YAML configuration file to load (Default: '.tldr.yml')" do |config_path|
+          options[:config_path] = config_path
         end
 
-        opts.on CONFLAGS[:no_emoji], "Disable emoji in the output" do
-          options[:no_emoji] = true
-        end
-
-        opts.on "-v", CONFLAGS[:verbose], "Print stack traces for errors" do |verbose|
-          options[:verbose] = verbose
+        opts.on "-r", "#{CONFLAGS[:reporter]} REPORTER", String, "Set a custom reporter class (Default: \"TLDR::Reporters::Default\")" do |reporter|
+          options[:reporter] = reporter
         end
 
-        opts.on CONFLAGS[:print_interrupted_test_backtraces], "Print stack traces for interrupted tests" do |print_interrupted_test_backtraces|
-          options[:print_interrupted_test_backtraces] = print_interrupted_test_backtraces
+        opts.on CONFLAGS[:emoji], "Enable emoji output for the default reporter (Default: false)" do |emoji|
+          options[:emoji] = emoji
         end
 
         opts.on CONFLAGS[:warnings], "Print Ruby warnings (Default: true)" do |warnings|
           options[:warnings] = warnings
         end
 
-        opts.on CONFLAGS[:watch], "Run your tests continuously on file save (requires 'fswatch' to be installed)" do
-          options[:watch] = true
+        opts.on "-v", CONFLAGS[:verbose], "Print stack traces for errors" do |verbose|
+          options[:verbose] = verbose
         end
 
-        opts.on CONFLAGS[:yes_i_know], "Suppress TLDR report when suite runs over 1.8s" do
+        opts.on CONFLAGS[:yes_i_know], "Suppress TLDR report when suite runs beyond any configured --timeout" do
           options[:yes_i_know] = true
         end
 
-        opts.on CONFLAGS[:i_am_being_watched], "[INTERNAL] Signals to tldr it is being invoked under --watch mode" do
-          options[:i_am_being_watched] = true
+        opts.on CONFLAGS[:exit_0_on_timeout], "Exit with status code 0 when suite times out instead of 3" do
+          options[:exit_0_on_timeout] = true
         end
 
-        opts.on "--comment COMMENT", String, "[INTERNAL] No-op; used for multi-line execution instructions" do
-          # See "--comment" in lib/tldr/reporters/default.rb for an example of how this is used internally
+        opts.on CONFLAGS[:exit_2_on_failure], "Exit with status code 2 (normally for errors) for both failures and errors" do
+          options[:exit_2_on_failure] = true
+        end
+
+        opts.on CONFLAGS[:print_interrupted_test_backtraces], "Print stack traces of tests interrupted after a timeout" do |print_interrupted_test_backtraces|
+          options[:print_interrupted_test_backtraces] = print_interrupted_test_backtraces
+        end
+
+        unless ARGV.include?("--help") || ARGV.include?("--h")
+          opts.on CONFLAGS[:i_am_being_watched], "[INTERNAL] Signals to tldr it is being invoked under --watch mode" do
+            options[:i_am_being_watched] = true
+          end
+
+          opts.on "--comment COMMENT", String, "[INTERNAL] No-op; used for multi-line execution instructions" do
+            # See "--comment" in lib/tldr/reporters/default.rb for an example of how this is used internally
+          end
         end
       end.parse!(args)
 
       options[:paths] = args if args.any?
+      options[:config_path] = case options[:config_path]
+      when nil then Config::DEFAULT_YAML_PATH
+      when false then nil
+      else options[:config_path]
+      end
 
       Config.new(**options)
     end
+
+    private
+
+    def handle_unparsable_optional_value(og_args, option_name, value, &blk)
+      yield
+    rescue ArgumentError
+      args = og_args.dup
+      if (option_index = args.index("--#{option_name}"))
+        args.insert(option_index + 1, "--")
+        warn <<~MSG
+          TLDR exited in error!
+
+          We couldn't parse #{value.inspect} as a valid #{option_name} value
+
+          Did you mean to set --#{option_name} as the last option and without an explicit value?
+
+          If so, you need to append ' -- ' before any paths, like:
+
+            tldr #{args.join(" ")}
+        MSG
+        exit 1
+      else
+        raise
+      end
+    end
   end
 end

data/lib/tldr/argv_reconstructor.rb

@@ -0,0 +1,107 @@
+class TLDR
+  class ArgvReconstructor
+    def reconstruct config, exclude:, ensure_args:, exclude_dotfile_matches:
+      argv = to_cli_argv(
+        config,
+        CONFLAGS.keys - exclude - [
+          (:seed unless config.seed_set_intentionally),
+          :watch,
+          :i_am_being_watched
+        ],
+        exclude_dotfile_matches:
+      )
+
+      ensure_args.each do |arg|
+        argv << arg unless argv.include?(arg)
+      end
+
+      argv.join(" ")
+    end
+
+    def reconstruct_single_path_args config, path, exclude_dotfile_matches:
+      argv = to_cli_argv(config, CONFLAGS.keys - [
+        :seed, :parallel, :names, :fail_fast, :paths, :prepend_paths,
+        :no_prepend, :exclude_paths, :watch, :i_am_being_watched
+      ], exclude_dotfile_matches:)
+
+      (argv + [stringify(:paths, path)]).join(" ")
+    end
+
+    private
+
+    def to_cli_argv config, options = CONFLAGS.keys, exclude_dotfile_matches:
+      defaults = Config.build_defaults(cli_defaults: true)
+      defaults = defaults.merge(config.dotfile_args(config.config_path)) if exclude_dotfile_matches
+      options.map { |key|
+        flag = CONFLAGS[key]
+
+        # Special cases
+        if key == :prepend_paths
+          if config.prepend_paths.map { |s| stringify(key, s) }.sort == config.paths.map { |s| stringify(:paths, s) }.sort
+            # Don't print prepended tests if they're the same as the test paths
+            next
+          elsif config.no_prepend
+            # Don't print prepended tests if they're disabled
+            next
+          end
+        elsif key == :helper_paths && config.no_helper
+          # Don't print the helper if it's disabled
+          next
+        elsif key == :parallel
+          val = if !config.seed_set_intentionally && !config.parallel
+            "--no-parallel"
+          elsif !config.seed.nil? && config.seed_set_intentionally && config.parallel
+            "--parallel"
+          end
+          next val
+        elsif key == :timeout
+          if config[:timeout] < 0
+            next
+          elsif config[:timeout] == Config::DEFAULT_TIMEOUT
+            next "--timeout"
+          elsif config[:timeout] != Config::DEFAULT_TIMEOUT
+            next "--timeout #{config[:timeout]}"
+          else
+            next
+          end
+        elsif key == :config_path
+          case config[:config_path]
+          when nil then next "--no-config"
+          when Config::DEFAULT_YAML_PATH then next
+          else next "--config #{config[:config_path]}"
+          end
+        end
+
+        if defaults[key] == config[key] && (key != :seed || !config.seed_set_intentionally)
+          next
+        elsif CONFLAGS[key]&.start_with?("--[no-]")
+          case config[key]
+          when false then CONFLAGS[key].gsub(/[\[\]]/, "")
+          when nil || true then CONFLAGS[key].gsub("[no-]", "")
+          else "#{CONFLAGS[key].gsub("[no-]", "")} #{stringify(key, config[key])}"
+          end
+        elsif config[key].is_a?(Array)
+          config[key].map { |value| [flag, stringify(key, value)] }
+        elsif config[key].is_a?(TrueClass) || config[key].is_a?(FalseClass)
+          flag if config[key]
+        elsif config[key].is_a?(Class)
+          [flag, config[key].name]
+        elsif !config[key].nil?
+          [flag, stringify(key, config[key])]
+        end
+      }.flatten.compact
+    end
+
+    def stringify key, val
+      if PATH_FLAGS.include?(key) && val.start_with?(Dir.pwd)
+        val = val[Dir.pwd.length + 1..]
+      end
+
+      if val.nil? || val.is_a?(Integer)
+        val
+      else
+        "\"#{val}\""
+      end
+    end
+  end
+end

data/lib/tldr/assertions.rb

@@ -9,7 +9,6 @@
 
 require "pp"
 require "super_diff"
-require_relative "assertions/minitest_compatibility"
 
 class TLDR
   module Assertions
@@ -109,7 +108,7 @@ class TLDR
       refute_in_delta expected, actual, expected * epsilon, msg
     end
 
-    def assert_include? expected, actual, message = nil
+    def assert_includes actual, expected, message = nil
       message = Assertions.msg(message) {
         "Expected #{Assertions.h(actual)} to include #{Assertions.h(expected)}"
       }
@@ -117,7 +116,7 @@ class TLDR
       assert actual.include?(expected), message
     end
 
-    def refute_include? expected, actual, message = nil
+    def refute_includes actual, expected, message = nil
       message = Assertions.msg(message) {
         "Expected #{Assertions.h(actual)} to not include #{Assertions.h(expected)}"
       }

data/lib/tldr/autorun.rb

@@ -0,0 +1,2 @@
+require "tldr"
+TLDR::Run.at_exit!(TLDR::ArgvParser.new.parse(ARGV))

data/lib/tldr/minitest_compatibility.rb

@@ -0,0 +1,35 @@
+# These methods are provided to support drop-in compatibility with Minitest. You
+# can use them by mixing them into your test or into the `TLDR` base class
+# itself:
+#
+#   class YourTest < TLDR
+#     include TLDR::MinitestCompatibility
+#
+#     def test_something
+#       # …
+#     end
+#   end
+#
+# The implementation of these methods is extremely similar or identical to those
+# found in minitest itself, which is Copyright © Ryan Davis, seattle.rb and
+# distributed under the MIT License
+class TLDR
+  module MinitestCompatibility
+    def capture_io &blk
+      Assertions.capture_io(&blk)
+    end
+
+    def mu_pp obj
+      s = obj.inspect.encode(Encoding.default_external)
+
+      if String === obj && (obj.encoding != Encoding.default_external ||
+                            !obj.valid_encoding?)
+        enc = "# encoding: #{obj.encoding}"
+        val = "#    valid: #{obj.valid_encoding?}"
+        "#{enc}\n#{val}\n#{s}"
+      else
+        s
+      end
+    end
+  end
+end

data/lib/tldr/reporters/default.rb

@@ -3,7 +3,7 @@ class TLDR
     class Default < Base
       def initialize config, out = $stdout, err = $stderr
         super
-        @icons = @config.no_emoji ? IconProvider::Base.new : IconProvider::Emoji.new
+        @icons = @config.emoji ? IconProvider::Emoji.new : IconProvider::Base.new
       end
 
       def before_suite tests
@@ -11,9 +11,9 @@ class TLDR
         @suite_start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond)
         @out.print <<~MSG
           Command: #{tldr_command} #{@config.to_full_args}
-          #{@icons.seed} #{CONFLAGS[:seed]} #{@config.seed}
+          #{@icons.rpad(:seed)}#{CONFLAGS[:seed]} #{@config.seed}
 
-          #{@icons.run} Running:
+          #{@icons.rpad(:run)}Running:
 
         MSG
       end
@@ -39,22 +39,22 @@ class TLDR
         @err.print "\n\n"
 
         if @config.yes_i_know
-          @err.print "🚨 TLDR after completing #{test_results.size} of #{planned_tests.size} tests! Print full summary by omitting --yes-i-know"
+          @err.print "#{@icons.rpad(:alarm)}TLDR after completing #{test_results.size} of #{planned_tests.size} tests! Print full summary by omitting --yes-i-know"
         else
           wrap_in_horizontal_rule do
             @err.print [
               "too long; didn't run!",
-              "#{@icons.run} Completed #{test_results.size} of #{planned_tests.size} tests (#{((test_results.size.to_f / planned_tests.size) * 100).round}%) before running out of time.",
+              "#{@icons.rpad(:run)}Completed #{test_results.size} of #{planned_tests.size} tests (#{((test_results.size.to_f / planned_tests.size) * 100).round}%) before running out of time.",
               (<<~WIP.chomp if wip_tests.any?),
-                #{@icons.wip} #{plural(wip_tests.size, "test was", "tests were")} cancelled in progress:
+                #{@icons.rpad(:wip)}#{plural(wip_tests.size, "test was", "tests were")} cancelled in progress:
                 #{wip_tests.map { |wip_test| "  #{time_diff(wip_test.start_time, stop_time)}ms - #{describe(wip_test.test)}#{print_wip_backtrace(wip_test, indent: "    ") if @config.print_interrupted_test_backtraces}" }.join("\n")}
               WIP
               (<<~SLOW.chomp if test_results.any?),
-                #{@icons.slow} Your #{[10, test_results.size].min} slowest completed tests:
+                #{@icons.rpad(:slow)}Your #{[10, test_results.size].min} slowest completed tests:
                 #{test_results.sort_by(&:runtime).last(10).reverse.map { |result| "  #{result.runtime}ms - #{describe(result.test)}" }.join("\n")}
               SLOW
               describe_tests_that_didnt_finish(planned_tests, test_results),
-              "🙈 Suppress this summary with --yes-i-know"
+              "#{@icons.rpad(:not_run)}Suppress this summary with --yes-i-know"
             ].compact.join("\n\n")
           end
         end
@@ -69,8 +69,8 @@ class TLDR
         wrap_in_horizontal_rule do
           @err.print [
             "Failing fast after #{describe(last_result.test, last_result.relevant_location)} #{last_result.error? ? "errored" : "failed"}.",
-            ("#{@icons.wip} #{plural(wip_tests.size, "test was", "tests were")} cancelled in progress." if wip_tests.any?),
-            ("#{@icons.not_run} #{plural(unrun_tests.size, "test was", "tests were")} not run at all." if unrun_tests.any?),
+            ("#{@icons.rpad(:wip)}#{plural(wip_tests.size, "test was", "tests were")} cancelled in progress." if wip_tests.any?),
+            ("#{@icons.rpad(:not_run)} #{plural(unrun_tests.size, "test was", "tests were")} not run at all." if unrun_tests.any?),
             describe_tests_that_didnt_finish(planned_tests, test_results)
           ].compact.join("\n\n")
         end
@@ -165,7 +165,7 @@ class TLDR
           ("--comment \"Also include #{plural(failed.size, "test")} that failed:\"" if failed_locators.any?)
         ].compact + failed_locators
         <<~MSG
-          #{@icons.rock_on} Run the #{plural(unrun.size, "test")} that didn't finish:
+          #{@icons.rpad(:rock_on)}Run the #{plural(unrun.size, "test")} that didn't finish:
             #{tldr_command} #{@config.to_full_args(exclude: [:paths], exclude_dotfile_matches: true)} #{suggested_locators.join(" \\\n    ")}
         MSG
       end

data/lib/tldr/reporters/icon_provider.rb

@@ -47,6 +47,15 @@ module IconProvider
     def seed
       ""
     end
+
+    def rpad(icon_name)
+      icon = send(icon_name)
+      if icon.nil? || icon.size == 0
+        icon
+      else
+        "#{icon} "
+      end
+    end
   end
 
   class Emoji < Base

data/lib/tldr/runner.rb

@@ -9,23 +9,48 @@ class TLDR
       @run_aborted = Concurrent::AtomicBoolean.new(false)
     end
 
+    def instantiate_reporter config
+      begin
+        reporter_class = Kernel.const_get(config.reporter)
+      rescue NameError
+        raise Error, "Unknown reporter '#{config.reporter}' (are you sure it was loaded by your test or helper?)"
+      end
+      if reporter_class.is_a?(Class)
+        if reporter_class.instance_method(:initialize).parameters.any? { |type, _| [:req, :opt, :rest].include?(type) }
+          reporter_class.new(config)
+        else
+          reporter_class.new
+        end
+      else
+        raise Error, "Reporter '#{config.reporter}' expected to be a class, but was a #{reporter_class.class}"
+      end
+    end
+
     def run config, plan
       @wip.clear
       @results.clear
-      reporter = config.reporter.new(config)
-      reporter.before_suite(plan.tests)
+      reporter = instantiate_reporter(config)
+      reporter.before_suite(plan.tests) if reporter.respond_to?(:before_suite)
 
       time_bomb = Thread.new {
+        next if config.timeout < 0
+
         explode = proc do
-          next if ENV["CI"] && !$stderr.tty?
           next if @run_aborted.true?
           @run_aborted.make_true
           @wip.each(&:capture_backtrace_at_exit)
-          reporter.after_tldr(plan.tests, @wip.dup, @results.dup)
-          exit!(3)
+          reporter.after_tldr(plan.tests, @wip.dup, @results.dup) if reporter.respond_to?(:after_tldr)
+
+          # If there are failures/errors, use their exit code regardless of exit_0_on_timeout
+          if @results.any? { |result| result.error? || result.failure? }
+            exit!(exit_code(@results, config))
+          else
+            exit!(config.exit_0_on_timeout ? 0 : 3)
+          end
         end
 
-        sleep(1.8)
+        sleep(config.timeout)
+
         # Don't hard-kill the runner if user is debugging, it'll
         # screw up their terminal slash be a bad time
         if IRB.CurrentContext
@@ -42,8 +67,8 @@ class TLDR
       end
 
       unless @run_aborted.true?
-        reporter.after_suite(results)
-        exit(exit_code(results))
+        reporter.after_suite(results) if reporter.respond_to?(:after_suite)
+        exit(exit_code(results, config))
       end
     end
 
@@ -74,7 +99,7 @@ class TLDR
         next if @run_aborted.true?
         @results << result
         @wip.delete(wip_test)
-        reporter.after_test(result)
+        reporter.after_test(result) if reporter.respond_to?(:after_test)
         fail_fast(reporter, plan, result) if result.failing? && config.fail_fast
       end
     end
@@ -83,7 +108,7 @@ class TLDR
       unless @run_aborted.true?
         @run_aborted.make_true
         abort = proc do
-          reporter.after_fail_fast(plan.tests, @wip.dup, @results.dup, fast_failed_result)
+          reporter.after_fail_fast(plan.tests, @wip.dup, @results.dup, fast_failed_result) if reporter.respond_to?(:after_fail_fast)
           exit!(exit_code([fast_failed_result]))
         end
 
@@ -100,11 +125,11 @@ class TLDR
       ((Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond) - start) / 1000.0).round
     end
 
-    def exit_code results
+    def exit_code results, config
       if results.any? { |result| result.error? }
         2
       elsif results.any? { |result| result.failure? }
-        1
+        config.exit_2_on_failure ? 2 : 1
       else
         0
       end