tldr 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91190a0094836b21df8aaeccb57684848ada68707a4c52241ebd74437fb514c4
-  data.tar.gz: a6cc8f1573bdb317f6fd5f337a9670bbeef95f735bdc1003774f4bca0a7b294b
+  metadata.gz: 32f7b9dbcf9e09433eef762eaafe19804643aa543ac2c0a9599303ea2e960f25
+  data.tar.gz: 789c07fb2db1fad39b234976999b575a1bea27c4796a4d062a373df11d3716e5
 SHA512:
-  metadata.gz: 93b9fdf0d61dcaba8c3c6dff464700ca260bbdef433eaf799e33130baf5ef63d0e7dec1c6dc3558e5d0f1bc580b53fbacc31c466da1f4a9803533470bb1b5ec5
-  data.tar.gz: f2a8de04ed3e9b84c277db21f111177849138c1b1b692a43d96492b0707c0e9a8c255c26a9991d899ed27312a04ebe13887a6db7d4417a4878b4e2cfc542acc4
+  metadata.gz: 7975ec24ae3f080ed564666c5319928964c970794a740a21253551be1be9b945374394b2f860cdd8737151f8e21fdb0d592c126895dd02b91dd21c899824226a
+  data.tar.gz: b11f3c52624b63a7aa44eadd4f17aa662d134648d61eb55eb7124e7956d0b28f20a04545552f9af8710330ffa98c94e85cec87dc80715a532522ccdeb15a8b42

data/CHANGELOG.md

@@ -1,4 +1,12 @@
-## [Unreleased]
+## [0.5.0]
+
+* Define your own Rake tasks with `TLDR::Task` and pass in a custom configuration
+* Any tests with `--prepend` AND marked thread-unsafe with `dont_run_these_in_parallel`
+will be run BEFORE the parallel tests start running. This way if you're working
+on a non-parallelizable test, running `tldr` will automatically run it first
+thing
+* Stop printing `--seed` in run commands, since it can be confusing to discover
+that will disable `--parallel`. Instead, print the seed option beneath
 
 ## [0.4.0]
 

data/README.md

@@ -181,6 +181,27 @@ You could then run the task with:
 $ TLDR_OPTS="--no-parallel" bundle exec rake tldr
 ```
 
+One reason you'd want to invoke TLDR with Rake is because you have multiple
+test suites that you want to be able to conveniently run separately ([this
+talk](https://blog.testdouble.com/talks/2014-05-25-breaking-up-with-your-test-suite/)
+discussed a few reasons why this can be useful).
+
+To create a custom TLDR Rake test, just instantiate `TLDR::Task` like this:
+
+```ruby
+require "tldr/rake"
+
+TLDR::Task.new(name: :safe_tests, config: TLDR::Config.new(
+  paths: FileList["safe/**/*_test.rb"],
+  helper: "safe/helper.rb",
+  load_paths: ["lib", "safe"]
+))
+```
+
+The above will create a second Rake task named `safe_tests` running a different
+set of tests than the default `tldr` task. Here's [an
+example](/example/b/Rakefile).
+
 ### Running tests without the CLI
 
 If you'd rather use TLDR by running Ruby files instead of the `tldr` CLI
@@ -207,7 +228,7 @@ $ ruby test/some_test.rb
 
 To maximize control and to avoid running code accidentally (and _unlike_ the
 `tldr` CLI), running `at_exit!` will not set default values to the `paths`,
-`helper`, `load_paths`, and `prepend_tests` config properties. You'll have to
+`helper`, `load_paths`, and `prepend_paths` config properties. You'll have to
 pass any values you want to set on a [Config object](/lib/tldr/value/config.rb)
 and pass it to `at_exit!`.
 

data/lib/tldr/argv_parser.rb

@@ -4,11 +4,7 @@ class TLDR
   class ArgvParser
     PATTERN_FRIENDLY_SPLITTER = /,(?=(?:[^\/]*\/[^\/]*\/)*[^\/]*$)/
 
-    def parse(args)
-      options = {
-        cli_mode: true
-      }
-
+    def parse(args, options = {cli_defaults: true})
       OptionParser.new do |opts|
         opts.banner = "Usage: tldr [options] some_tests/**/*.rb some/path.rb:13 ..."
 
@@ -47,9 +43,9 @@ class TLDR
           options[:no_helper] = true
         end
 
-        opts.on "#{CONFLAGS[:prepend_tests]} PATH", Array, "Prepend one or more paths to run before the rest (Default: most recently modified test)" do |prepend|
-          options[:prepend_tests] ||= []
-          options[:prepend_tests] += prepend
+        opts.on "#{CONFLAGS[:prepend_paths]} PATH", Array, "Prepend one or more paths to run before the rest (Default: most recently modified test)" do |prepend|
+          options[:prepend_paths] ||= []
+          options[:prepend_paths] += prepend
         end
 
         opts.on CONFLAGS[:no_prepend], "Don't prepend any tests before the rest of the suite" do

data/lib/tldr/parallelizer.rb

@@ -8,12 +8,18 @@ class TLDR
       )
     end
 
-    def parallelize all_tests, parallel, &blk
-      return run_in_sequence(all_tests, &blk) if all_tests.size < 2 || !parallel
+    def parallelize all_tests, config, &blk
+      return run_in_sequence(all_tests, &blk) if all_tests.size < 2 || !config.parallel
 
-      strategy = @strategizer.strategize all_tests, GROUPED_TESTS, THREAD_UNSAFE_TESTS
+      strategy = @strategizer.strategize(
+        all_tests,
+        GROUPED_TESTS,
+        THREAD_UNSAFE_TESTS,
+        (config.no_prepend ? [] : config.prepend_paths)
+      )
 
-      run_in_parallel(strategy.parallel_tests_and_groups, &blk) +
+      run_in_sequence(strategy.prepend_thread_unsafe_tests, &blk) +
+        run_in_parallel(strategy.parallel_tests_and_groups, &blk) +
         run_in_sequence(strategy.thread_unsafe_tests, &blk)
     end
 

data/lib/tldr/path_util.rb

@@ -0,0 +1,41 @@
+class TLDR
+  module PathUtil
+    def self.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
+
+    # 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 self.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 self.locations_include_test? locations, test
+      locations.any? { |location|
+        location.file == test.file && (location.line.nil? || test.covers_line?(location.line))
+      }
+    end
+  end
+end

data/lib/tldr/planner.rb

@@ -3,7 +3,7 @@ require "pathname"
 class TLDR
   class Planner
     def plan config
-      search_locations = expand_search_locations config.paths
+      search_locations = PathUtil.expand_search_locations config.paths
 
       prepend_load_paths config
       require_test_helper config
@@ -32,21 +32,6 @@ class TLDR
 
     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|
@@ -57,9 +42,9 @@ class TLDR
 
     def prepend tests, config
       return tests if config.no_prepend
-      prepended_locations = expand_search_locations expand_globs config.prepend_tests
+      prepended_locations = PathUtil.expand_search_locations PathUtil.expand_globs config.prepend_paths
       prepended, rest = tests.partition { |test|
-        locations_include_test? prepended_locations, test
+        PathUtil.locations_include_test? prepended_locations, test
       }
       prepended + rest
     end
@@ -69,11 +54,11 @@ class TLDR
     end
 
     def exclude_by_path tests, exclude_paths
-      excluded_locations = expand_search_locations expand_globs exclude_paths
+      excluded_locations = PathUtil.expand_search_locations PathUtil.expand_globs exclude_paths
       return tests if excluded_locations.empty?
 
       tests.reject { |test|
-        locations_include_test? excluded_locations, test
+        PathUtil.locations_include_test? excluded_locations, test
       }
     end
 
@@ -94,7 +79,7 @@ class TLDR
       return tests if line_specific_locations.empty?
 
       tests.select { |test|
-        locations_include_test? line_specific_locations, test
+        PathUtil.locations_include_test? line_specific_locations, test
       }
     end
 
@@ -133,29 +118,6 @@ class TLDR
       }
     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 =~ /^\/(.*)\/$/

data/lib/tldr/rake.rb

@@ -1,4 +1,41 @@
-desc "Run tests with TLDR (use TLDR_OPTS or .tldr.yml to configure)"
-task :tldr do
-  fail unless system "#{"bundle exec " if defined?(Bundler)}tldr #{ENV["TLDR_OPTS"]}"
+require "rake"
+require "shellwords"
+
+require "tldr"
+
+class TLDR
+  class Task
+    include Rake::DSL
+
+    def initialize(name: "tldr", config: Config.new)
+      define name, config
+    end
+
+    private
+
+    def define name, task_config
+      desc "Run #{name} tests (use TLDR_OPTS or .tldr.yml to configure)"
+      task name do
+        cli_args = build_cli_args(task_config)
+        fail unless system "#{"bundle exec " if defined?(Bundler)}tldr #{cli_args}"
+      end
+    end
+
+    def build_cli_args task_config
+      config = if ENV["TLDR_OPTS"]
+        env_argv = Shellwords.shellwords(ENV["TLDR_OPTS"])
+        opts_config = ArgvParser.new.parse(env_argv, {
+          config_intended_for_merge_only: true
+        })
+        task_config.merge(opts_config)
+      else
+        task_config
+      end
+
+      config.to_full_args
+    end
+  end
 end
+
+# Create the default tldr task for users
+TLDR::Task.new

data/lib/tldr/reporters/default.rb

@@ -9,7 +9,7 @@ class TLDR
       def before_suite tests
         @suite_start_time = Process.clock_gettime Process::CLOCK_MONOTONIC, :microsecond
         @out.print <<~MSG
-          Command: #{tldr_command} #{@config.to_full_args}
+          Command: #{tldr_command} #{@config.to_full_args}#{"\n#{@icons.seed} #{CONFLAGS[:seed]} #{@config.seed}" unless @config.seed_set_intentionally}
 
           #{@icons.run} Running:
 

data/lib/tldr/reporters/icon_provider.rb

@@ -43,6 +43,10 @@ module IconProvider
     def rock_on
       ""
     end
+
+    def seed
+      ""
+    end
   end
 
   class Emoji < Base
@@ -89,5 +93,9 @@ module IconProvider
     def rock_on
       "🤘"
     end
+
+    def seed
+      "🌱"
+    end
   end
 end

data/lib/tldr/runner.rb

@@ -34,7 +34,7 @@ class TLDR
         end
       }
 
-      results = @parallelizer.parallelize(plan.tests, config.parallel) { |test|
+      results = @parallelizer.parallelize(plan.tests, config) { |test|
         e = nil
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond)
         wip_test = WIPTest.new test, start_time

data/lib/tldr/strategizer.rb

@@ -1,6 +1,6 @@
 class TLDR
   class Strategizer
-    Strategy = Struct.new :parallel_tests_and_groups, :thread_unsafe_tests
+    Strategy = Struct.new :prepend_thread_unsafe_tests, :parallel_tests_and_groups, :thread_unsafe_tests
 
     # Combine all discovered test methods with any methods grouped by run_these_together!
     #
@@ -8,13 +8,13 @@ class TLDR
     #   - Map over tests to build out groups in order to retain shuffle order
     #     (group will run in position of first test in the group)
     #   - If a test is in multiple groups, only run it once
-    def strategize all_tests, run_these_together_groups, thread_unsafe_test_groups
+    def strategize all_tests, run_these_together_groups, thread_unsafe_test_groups, prepend_paths
       thread_unsafe_tests, thread_safe_tests = partition_unsafe(all_tests, thread_unsafe_test_groups)
+      prepend_thread_unsafe_tests, thread_unsafe_tests = partition_prepend(thread_unsafe_tests, prepend_paths)
 
       grouped_tests = prepare_run_together_groups run_these_together_groups, thread_safe_tests, thread_unsafe_tests
       already_included_groups = []
-
-      Strategy.new thread_safe_tests.map { |test|
+      Strategy.new prepend_thread_unsafe_tests, thread_safe_tests.map { |test|
         if (group = grouped_tests.find { |group| group.tests.include? test })
           if already_included_groups.include? group
             next
@@ -39,6 +39,16 @@ class TLDR
       }
     end
 
+    # Sadly duplicative with Planner.rb, necessitating the extraction of PathUtil
+    # Suboptimal, but we do indeed need to do this work in two places ¯\_(ツ)_/¯
+    def partition_prepend thread_unsafe_tests, prepend_paths
+      locations = PathUtil.expand_search_locations PathUtil.expand_globs prepend_paths
+
+      thread_unsafe_tests.partition { |test|
+        PathUtil.locations_include_test? locations, test
+      }
+    end
+
     def prepare_run_together_groups run_these_together_groups, thread_safe_tests, thread_unsafe_tests
       grouped_tests = run_these_together_groups.map(&:dup)
 

data/lib/tldr/value/config.rb

@@ -10,7 +10,7 @@ class TLDR
     names: "--name",
     fail_fast: "--fail-fast",
     no_emoji: "--no-emoji",
-    prepend_tests: "--prepend",
+    prepend_paths: "--prepend",
     no_prepend: "--no-prepend",
     exclude_paths: "--exclude-path",
     exclude_names: "--exclude-name",
@@ -19,25 +19,35 @@ class TLDR
     paths: nil
   }.freeze
 
-  PATH_FLAGS = [:paths, :helper, :load_paths, :prepend_tests, :exclude_paths].freeze
+  PATH_FLAGS = [:paths, :helper, :load_paths, :prepend_paths, :exclude_paths].freeze
   MOST_RECENTLY_MODIFIED_TAG = "MOST_RECENTLY_MODIFIED".freeze
 
   Config = Struct.new :paths, :seed, :no_helper, :verbose, :reporter,
     :helper, :load_paths, :parallel, :names, :fail_fast, :no_emoji,
-    :prepend_tests, :no_prepend, :exclude_paths, :exclude_names, :base_path,
+    :prepend_paths, :no_prepend, :exclude_paths, :exclude_names, :base_path,
     :no_dotfile,
-    :seed_set_intentionally, :cli_mode, keyword_init: true do
+    # Internal properties
+    :config_intended_for_merge_only, :seed_set_intentionally, :cli_defaults,
+    keyword_init: true do
     def initialize(**args)
-      change_working_directory_because_i_am_bad_and_i_should_feel_bad!(args[:base_path])
-      args = merge_dotfile_args(args) unless args[:no_dotfile]
+      unless args[:config_intended_for_merge_only]
+        change_working_directory_because_i_am_bad_and_i_should_feel_bad!(args[:base_path])
+        args = merge_dotfile_args(args) unless args[:no_dotfile]
+      end
+      args = undefault_parallel_if_seed_set(args)
+      unless args[:config_intended_for_merge_only]
+        args = merge_defaults(args)
+      end
 
-      super(**merge_defaults(args))
+      super(**args)
     end
 
-    # Must be set when the Config is first initialized
-    undef_method :cli_mode=, :no_dotfile=, :base_path=
+    # These are for internal tracking and resolved at initialization-time
+    undef_method :config_intended_for_merge_only=, :seed_set_intentionally=,
+      # These must be set when the Config is first initialized
+      :cli_defaults=, :no_dotfile=, :base_path=
 
-    def self.build_defaults(cli_mode = false)
+    def self.build_defaults cli_defaults: true
       common = {
         seed: rand(10_000),
         no_helper: false,
@@ -53,36 +63,36 @@ class TLDR
         base_path: nil
       }
 
-      if cli_mode
+      if cli_defaults
         common.merge(
           paths: Dir["test/**/*_test.rb", "test/**/test_*.rb"],
           helper: "test/helper.rb",
           load_paths: ["test"],
-          prepend_tests: [MOST_RECENTLY_MODIFIED_TAG]
+          prepend_paths: [MOST_RECENTLY_MODIFIED_TAG]
         )
       else
         common.merge(
           paths: [],
           helper: nil,
           load_paths: [],
-          prepend_tests: []
+          prepend_paths: []
         )
       end
     end
 
-    def merge_defaults(user_args)
-      merged_args = user_args.dup
-      defaults = Config.build_defaults(merged_args[:cli_mode])
-      merged_args[:seed_set_intentionally] = !merged_args[:seed].nil?
+    def undefault_parallel_if_seed_set args
+      args.merge(
+        seed_set_intentionally: !args[:seed].nil?,
+        parallel: (args[:parallel].nil? ? args[:seed].nil? : args[:parallel])
+      )
+    end
 
-      # Special cases
-      if merged_args[:parallel].nil?
-        # Disable parallelization if seed is set
-        merged_args[:parallel] = merged_args[:seed].nil?
-      end
+    def merge_defaults user_args
+      merged_args = user_args.dup
+      defaults = Config.build_defaults(cli_defaults: merged_args[:cli_defaults])
 
       # Arrays
-      [:paths, :load_paths, :names, :prepend_tests, :exclude_paths, :exclude_names].each do |key|
+      [:paths, :load_paths, :names, :prepend_paths, :exclude_paths, :exclude_names].each do |key|
         merged_args[key] = defaults[key] if merged_args[key].nil? || merged_args[key].empty?
       end
 
@@ -99,13 +109,21 @@ class TLDR
       merged_args
     end
 
+    def merge other
+      this_config = to_h
+      kwargs = this_config.merge(
+        other.to_h.compact.except(:config_intended_for_merge_only)
+      )
+      Config.new(**kwargs)
+    end
+
     # We needed this hook (to be called by the planner), because we can't know
     # the default prepend location until we have all the resolved test paths,
     # so we have to mutate it after the fact.
     def update_after_gathering_tests! tests
-      return unless prepend_tests.include?(MOST_RECENTLY_MODIFIED_TAG)
+      return unless prepend_paths.include?(MOST_RECENTLY_MODIFIED_TAG)
 
-      self.prepend_tests = prepend_tests.map { |path|
+      self.prepend_paths = prepend_paths.map { |path|
         if path == MOST_RECENTLY_MODIFIED_TAG
           most_recently_modified_test_file tests
         else
@@ -115,12 +133,17 @@ class TLDR
     end
 
     def to_full_args(exclude: [])
-      to_cli_argv(CONFLAGS.keys - exclude).join(" ")
+      to_cli_argv(
+        CONFLAGS.keys -
+        exclude - [
+          (:seed unless seed_set_intentionally)
+        ]
+      ).join(" ")
     end
 
     def to_single_path_args(path)
       argv = to_cli_argv(CONFLAGS.keys - [
-        :seed, :parallel, :names, :fail_fast, :paths, :prepend_tests,
+        :seed, :parallel, :names, :fail_fast, :paths, :prepend_paths,
         :no_prepend, :exclude_paths
       ])
 
@@ -129,14 +152,14 @@ class TLDR
 
     private
 
-    def to_cli_argv(options = CONFLAGS.keys)
-      defaults = Config.build_defaults(cli_mode)
+    def to_cli_argv options = CONFLAGS.keys
+      defaults = Config.build_defaults(cli_defaults: true)
       options.map { |key|
         flag = CONFLAGS[key]
 
         # Special cases
-        if key == :prepend_tests
-          if prepend_tests.map { |s| stringify(key, s) }.sort == paths.map { |s| stringify(:paths, s) }.sort
+        if key == :prepend_paths
+          if prepend_paths.map { |s| stringify(key, s) }.sort == paths.map { |s| stringify(:paths, s) }.sort
             # Don't print prepended tests if they're the same as the test paths
             next
           elsif no_prepend

data/lib/tldr/version.rb

@@ -1,3 +1,3 @@
 class TLDR
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/tldr.rb

@@ -6,6 +6,7 @@ require_relative "tldr/backtrace_filter"
 require_relative "tldr/error"
 require_relative "tldr/parallel_controls"
 require_relative "tldr/parallelizer"
+require_relative "tldr/path_util"
 require_relative "tldr/planner"
 require_relative "tldr/reporters"
 require_relative "tldr/runner"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tldr
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Justin Searls
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-27 00:00:00.000000000 Z
+date: 2023-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: super_diff
@@ -62,6 +62,7 @@ files:
 - lib/tldr/error.rb
 - lib/tldr/parallel_controls.rb
 - lib/tldr/parallelizer.rb
+- lib/tldr/path_util.rb
 - lib/tldr/planner.rb
 - lib/tldr/rake.rb
 - lib/tldr/reporters.rb
@@ -105,7 +106,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.17
+rubygems_version: 3.4.6
 signing_key:
 specification_version: 4
 summary: TLDR will run your tests, but only for 1.8 seconds.