tldr 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71122b11466d7a2682ace7dbba2258d2ead4a4aec723882b0c543bcbc3c12f39
-  data.tar.gz: efe76c0ab2ee09ba20921d56922630557ffb11704e3839a8a7322329b8fb5889
+  metadata.gz: 32f7b9dbcf9e09433eef762eaafe19804643aa543ac2c0a9599303ea2e960f25
+  data.tar.gz: 789c07fb2db1fad39b234976999b575a1bea27c4796a4d062a373df11d3716e5
 SHA512:
-  metadata.gz: 8a3dbacc10c845d976b89775ad762b5e37d2b6c2dbd657dc02422f7d356f98770b16ea485f242c7065ba688d8d69db078801735b41812f1f91a139bcd6d1ac31
-  data.tar.gz: ccc10568c6c506d7656fee1619f678dc32da38298d0ef33c7e2b613e849f9a323dc3105c49aea7ecf108bd705c92fd90dd6cab88fb57e69f0fb4a53e119144ab
+  metadata.gz: 7975ec24ae3f080ed564666c5319928964c970794a740a21253551be1be9b945374394b2f860cdd8737151f8e21fdb0d592c126895dd02b91dd21c899824226a
+  data.tar.gz: b11f3c52624b63a7aa44eadd4f17aa662d134648d61eb55eb7124e7956d0b28f20a04545552f9af8710330ffa98c94e85cec87dc80715a532522ccdeb15a8b42

data/CHANGELOG.md

@@ -1,4 +1,18 @@
-## [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]
+
+* Add `TLDR.dont_run_these_in_parallel!` method to allow tests to indicate that they
+must be run in isolation and not concurrently with any other tests
+* Add support for `around` hooks (similar to [minitest-around](https://github.com/splattael/minitest-around))
 
 ## [0.3.0]
 

data/README.md

@@ -1,6 +1,8 @@
 # TLDR - for people who don't have time for slow tests
 
-**tl;dr, this is a very nice test runner for Ruby that fails after 1.8 seconds**
+Okay, you might need to sit down for this:
+
+**tl;dr, TLDR is a Ruby test framework that stops running your tests after 1.8 seconds.**
 
 We initially meant this as a joke [while
 pairin'](https://www.youtube.com/live/bmi-SWeH4MA?si=p5g1j1FQZrbYEOCg&t=63), but
@@ -9,16 +11,28 @@ in addition to being funny, it was also a pretty good idea. So we fleshed out
 [Minitest-compatible](#minitest-compatibility), and downright pleasant test
 framework for Ruby.
 
+The "big idea" here is TLDR is designed for users to run the `tldr` command
+repeatedly as they work—as opposed to only running the tests for whatever is
+being worked on. Even if the suite run over the 1.8 second time limit. Because
+TLDR shuffles and runs in parallel and is guaranteed to take less than two
+seconds,
+**you'll actually wind up running _all_ of your tests quite often as you work**,
+catching any problems much earlier than if you had waited until the end of the
+day to push your work and let a continuous integration server run the full
+suite.
+
 Some stuff you might like:
 
 * A CLI that can run tests by line number(s) (e.g. `foo.rb:5 bar.rb:3:10`) and
 by names or patterns (e.g. `--name test_fail,test_error --name "/_\d/"`)
-* Everything is **parallel by default**, and seems pretty fast (you can disable with `--no-parallel`)
-* Surprisingly delightful color diff output when two things fail to equal one another, care of [@mcmire's super_diff gem](https://github.com/mcmire/super_diff)
+* Everything is **parallel by default**, and seems pretty darn fast; TLDR
+also provides [several escape hatches to sequester tests that aren't thread-safe](#parallel-by-default-is-nice-in-theory-but-half-my-tests-are-failing-wat)
+* Surprisingly delightful color diff output when two things fail to equal one
+another, care of [@mcmire's super_diff gem](https://github.com/mcmire/super_diff)
 * By default, the CLI will prepend your most-recently-edited test file to the
-front of your suite so its tests will run first. The tests you're working on are
-the most likely you care about running, so TLDR runs them first (see the
-`--prepend` option)
+front of your suite so its tests will run first. The test you worked on most recently
+is the one you most likely want to ensure runs, so TLDR runs it first (see the
+`--prepend` option for how to control this behavior)
 * And, of course, our signature feature: your test suite will never grow into
 a glacially slow, soul-sucking albatross around your neck, because **after 1.8
 seconds, it stops running your tests**, with a report on what it _was_ able to
@@ -50,7 +64,7 @@ end
 ```
 
 A TLDR subclass defines its tests with instance methods that begin with
-`_test`. They can define `setup` and/or `teardown` methods which will run before
+`test_`. They can define `setup` and/or `teardown` methods which will run before
 and after each test, respectively.
 
 If you place your tests in `test/**/*_test.rb` (and/or `test/**/test_*.rb`)
@@ -82,68 +96,9 @@ flags:
 $ tldr --name FooTest#test_foo -n test_bar,test_baz -n /_qux/
 ```
 
-(The above will translate to this array of name fiilters internally:
+(The above will translate to this array of name filters internally:
  `["FooTest#test_foo", "test_bar", "test_baz", "/_qux/"]`.)
 
-### Running tests without the CLI
-
-If you'd rather use TLDR by running Ruby files instead of the `tldr` CLI
-(similar to `require "minitest/autorun"`), here's how to do it!
-
-Given a file `test/some_test.rb`:
-
-```ruby
-require "tldr"
-TLDR::Run.at_exit! TLDR::Config.new(no_emoji: true)
-
-class SomeTest < TLDR
-  def test_truth
-    assert true
-  end
-end
-```
-
-You could run the test with:
-
-```
-$ 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
-pass any values you want to set on a [Config object](/lib/tldr/value/config.rb)
-and pass it to `at_exit!`.
-
-To avoid running multiple suites accidentally, if `TLDR::Run.at_exit!` is
-encountered multiple times, only the first hook will be registered. If the
-`tldr` CLI is running and encounters a call to `at_exit!`, it will be ignored.
-
-#### Setting up the load path
-
-When running TLDR from a Ruby script, one thing the framework can't help you with
-is setting up load paths for you.
-
-If you want to require code in `test/` or `lib/` without using
-`require_relative`, you'll need to add those directories to the load path. You
-can do this programmatically by prepending the path to `$LOAD_PATH`, like
-this:
-
-```ruby
-$LOAD_PATH.unshift "test"
-
-require "tldr"
-TLDR::Run.at_exit! TLDR::Config.new(no_emoji: true)
-
-require "helper"
-```
-
-Or by using Ruby's `-I` flag to include it:
-
-```
-$ ruby -Itest test/some_test.rb
-```
-
 ### Options
 
 Here is the full list of CLI options:
@@ -192,7 +147,8 @@ well as some [internal tests](/tests/dotfile_test.rb) demonstrating its behavior
 Tests you write with tldr are designed to be mostly-compatible with
 [Minitest](https://github.com/minitest/minitest) tests. Some notes:
 
-* `setup` and `teardown` hook methods should work as you expect
+* `setup` and `teardown` hook methods should work as you expect. (We even threw
+in [an `around` hook](https://github.com/splattael/minitest-around) as a bonus!)
 * All of Minitest's assertions (e.g. `assert`, `assert_equals`) are provided,
 with these caveats:
   * To retain the `expected, actual` argument ordering, `tldr` defines
@@ -201,7 +157,7 @@ with these caveats:
   * If you want to maximize compatibility and mix in `assert_includes` and the
   deprecated `assert_send`, just `include
   TLDR::Assertions::MinitestCompatibility` into the `TLDR` base class or
-  individual test classes
+  individual test classesJust set it
 
 ### Running TLDR with Rake
 
@@ -225,7 +181,92 @@ You could then run the task with:
 $ TLDR_OPTS="--no-parallel" bundle exec rake tldr
 ```
 
-### Parallel-by-default was a bold choice—also my tests are failing now, thanks
+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
+(similar to `require "minitest/autorun"`), here's how to do it!
+
+Given a file `test/some_test.rb`:
+
+```ruby
+require "tldr"
+TLDR::Run.at_exit! TLDR::Config.new(no_emoji: true)
+
+class SomeTest < TLDR
+  def test_truth
+    assert true
+  end
+end
+```
+
+You could run the test with:
+
+```
+$ 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_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!`.
+
+To avoid running multiple suites accidentally, if `TLDR::Run.at_exit!` is
+encountered multiple times, only the first hook will be registered. If the
+`tldr` CLI is running and encounters a call to `at_exit!`, it will be ignored.
+
+#### Setting up the load path
+
+When running TLDR from a Ruby script, one thing the framework can't help you with
+is setting up load paths for you.
+
+If you want to require code in `test/` or `lib/` without using
+`require_relative`, you'll need to add those directories to the load path. You
+can do this programmatically by prepending the path to `$LOAD_PATH`, like
+this:
+
+```ruby
+$LOAD_PATH.unshift "test"
+
+require "tldr"
+TLDR::Run.at_exit! TLDR::Config.new(no_emoji: true)
+
+require "helper"
+```
+
+Or by using Ruby's `-I` flag to include it:
+
+```
+$ ruby -Itest test/some_test.rb
+```
+
+## Questions you might be asking
+
+TLDR is very similar to Minitest in API, but different in enough ways that you
+probably have some questions.
+
+### Parallel-by-default is nice in theory but half my tests are failing. Wat?
 
 **Read this before you add `--no-parallel` because some tests are failing when
 you run `tldr`.**
@@ -234,17 +275,17 @@ The vast majority of test suites in the wild are not parallelized and the vast
 majority of _those_ will only parallelize by forking processes as opposed to
 using a thread pool. We wanted to encourage more people to save time (after all,
 you only get 1.8 seconds here) by making your test suite run as fast as it can,
-so your tests run in parallel by default.
+so your tests run in parallel threads by default.
 
 If you're writing new code and tests with TLDR and dutifully running `tldr`
 constantly for fast feedback, odds are that this will help you catch thread
-safety issues early—this is a good thing, because it gives you a chance to fix
-them! But maybe you're porting an existing test suite to TLDR and running in
-parallel for the first time, or maybe you need to test something that simply
-_can't_ be exercised in a thread-safe way. For those cases, TLDR's goal is to
-give you some tools to prevent you from giving up and adding `--no-parallel` to
-your entire test suite and **slowing everything down for the sake of a few
-tests**.
+safety issues early—this is a good thing, because it gives you a chance to
+address them before they're too hard to fix! But maybe you're porting an
+existing test suite to TLDR and running in parallel for the first time, or maybe
+you need to test something that simply _can't_ be exercised in a thread-safe
+way. For those cases, TLDR's goal is to give you some tools to prevent you from
+giving up and adding `--no-parallel` to your entire test suite and **slowing
+everything down for the sake of a few tests**.
 
 So, when you see a test that is failing when run in parallel with the rest of your
 suite, here is what we recommend doing, in priority order:
@@ -254,11 +295,17 @@ thread-safe.  Modern versions of Ruby provide a number of tools to make this
 easier than it used to be, and it may be as simple as making an instance
 variable thread-local
 2. If the problem is that a subset of your tests depend on the same resource,
-try using [TLDR.run_these_together!](/lib/tldr/run_these_together.rb) class to
+try using [TLDR.run_these_together!](lib/tldr/parallel_controls.rb) class to
 group the tests together. This will ensure that those tests run in the same
-thread in sequence (here's a a [simple
+thread in sequence (here's a [simple
 example](/tests/fixture/run_these_together.rb))
-3. Give up and make the whole suite `--no-parallel`. If you find that you need
+3. For tests that affect process-wide resources like setting the system clock or
+changing the process's working directory (i.e. `Dir.chdir`), you can sequester
+them to run sequentially _after_ all parallel tests in your suite have run with
+[TLDR.dont_run_these_in_parallel!](lib/tldr/parallel_controls.rb), which takes
+the same arguments as `run_these_together!`
+([example](/tests/fixture/dont_run_these_in_parallel.rb))
+4. Give up and make the whole suite `--no-parallel`. If you find that you need
 to resort to this, you might save some keystrokes by adding `parallel: false` in
 a [.tldr.yml](#setting-defaults-in-tldryml) file
 
@@ -267,11 +314,23 @@ your suite without slowing down the rest of your tests, so stay tuned!
 
 ### How will I run all my tests in CI without the time bomb going off?
 
-TLDR will run all your tests in CI without the time bomb going off.
+TLDR will run all your tests in CI without the time bomb going off. If
+`tldr` is run in a non-interactive shell and a `CI` environment variable is set
+(as it is on virtually every CI service), then the bomb will be defused.
+
+### Is there a plugin system?
+
+There is not.
+
+Currently, the only pluggable aspect of TLDR are reporters, which can be set
+with the `--reporter` command line option. It can be set to any fully-qualified
+class name that extends from
+[TLDR::Reporters::Base](/lib/tldr/reporters/base.rb).
 
 ### What about mocking?
 
-TLDR is laser-focused on running tests. Might we interest you in a refreshing
+TLDR is laser-focused on running tests, so it doesn't provide a built-in mocking
+facility. Might we interest you in a refreshing
 [mocktail](https://github.com/testdouble/mocktail), instead?
 
 ## Acknowledgements

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/parallel_controls.rb

@@ -0,0 +1,47 @@
+class TLDR
+  # If it's not safe to run a set of tests in parallel, you can force them to
+  # run in a group together (in a single worker) with `run_these_together!` in
+  # your test.
+  #
+  # This method takes an array of tuples, where the first element is the class
+  # (or its name as a string, if the class is not yet defined in the current
+  # file) and the second element is the method name. If the second element is
+  # nil, then all the tests on the class will be run together.
+  #
+  # Examples:
+  #   - `run_these_together!` will run all the tests defined on the current
+  #     class to be run in a group
+  #   - `run_these_together!([[ClassA, nil], ["ClassB", :test_1], [ClassB, :test_2]])`
+  #    will run all the tests defined on ClassA, and test_1 and test_2 from ClassB
+  #
+  GROUPED_TESTS = Concurrent::Array.new
+  def self.run_these_together! klass_method_tuples = [[self, nil]]
+    GROUPED_TESTS << TestGroup.new(klass_method_tuples)
+  end
+
+  # This is a similar API to run_these_together! but its effect is more drastic
+  # Rather than running the provided (class, method) tuples in a group within a
+  # thread as part of a parallel run, it will reserve all tests specified by
+  # all calls to `dont_run_these_in_parallel!` to be run after all parallel tests have
+  # finished.
+  #
+  # This has an important implication! If your test suite is over TLDR's time
+  # limit, it means that these tests will never be run outside of CI unless you
+  # run them manually.
+  #
+  # Like `run_these_together!`, `dont_run_these_in_parallel!` takes an array of
+  # tuples, where the first element is the class (or its fully-qualified name as
+  # a string) and the second element is `nil` (matching all the class's test
+  # methods) or else one of the methods on the class.
+  #
+  # Examples:
+  #   - `dont_run_these_in_parallel!` will run all the tests defined on the current
+  #     class after all parallel tests have finished
+  #   - `dont_run_these_in_parallel!([[ClassA, nil], ["ClassB", :test_1], [ClassB, :test_2]])`
+  #    will run all the tests defined on ClassA, and test_1 and test_2 from ClassB
+  #
+  THREAD_UNSAFE_TESTS = Concurrent::Array.new
+  def self.dont_run_these_in_parallel! klass_method_tuples = [[self, nil]]
+    THREAD_UNSAFE_TESTS << TestGroup.new(klass_method_tuples)
+  end
+end

data/lib/tldr/parallelizer.rb

@@ -2,35 +2,47 @@ class TLDR
   class Parallelizer
     def initialize
       @strategizer = Strategizer.new
-    end
-
-    def parallelize tests, parallel, &blk
-      return tests.map(&blk) if tests.size < 2 || !parallel
-      tldr_pool = Concurrent::ThreadPoolExecutor.new(
+      @thread_pool = Concurrent::ThreadPoolExecutor.new(
         name: "tldr",
         auto_terminate: true
       )
+    end
+
+    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,
+        (config.no_prepend ? [] : config.prepend_paths)
+      )
 
-      strategy = @strategizer.strategize tests, GROUPED_TESTS
+      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
 
-      strategy.tests_and_groups.map { |test_or_group|
+    private
+
+    def run_in_sequence tests, &blk
+      tests.map(&blk)
+    end
+
+    def run_in_parallel tests_and_groups, &blk
+      tests_and_groups.map { |test_or_group|
         tests_to_run = if test_or_group.group?
-          test_or_group.tests.select { |test| tests.include? test }
+          test_or_group.tests
         else
           [test_or_group]
         end
 
         unless tests_to_run.empty?
-          Concurrent::Promises.future_on(tldr_pool) {
+          Concurrent::Promises.future_on(@thread_pool) {
             tests_to_run.map(&blk)
           }
         end
       }.compact.flat_map(&:value)
     end
-
-    private
-
-    def substitute_tests_grouped_by_run_these_together! tests
-    end
   end
 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:
 
@@ -17,12 +17,17 @@ class TLDR
       end
 
       def after_test result
-        @out.print case result.type
+        output = case result.type
         when :success then @icons.success
         when :skip then @icons.skip
         when :failure then @icons.failure
         when :error then @icons.error
         end
+        if @config.verbose
+          @out.puts "#{output} #{result.type.capitalize} - #{describe(result.test, result.relevant_location)}"
+        else
+          @out.print output
+        end
       end
 
       def time_diff start, stop = Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond)

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
@@ -42,7 +42,16 @@ class TLDR
         runtime = time_it(start_time) do
           instance = test.klass.new
           instance.setup if instance.respond_to? :setup
-          instance.send(test.method)
+          if instance.respond_to? :around
+            did_run = false
+            instance.around {
+              did_run = true
+              instance.send(test.method)
+            }
+            raise Error, "#{test.klass}#around failed to yield or call the passed test block" unless did_run
+          else
+            instance.send(test.method)
+          end
           instance.teardown if instance.respond_to? :teardown
         rescue Skip, Failure, StandardError => e
         end

data/lib/tldr/strategizer.rb

@@ -1,6 +1,6 @@
 class TLDR
   class Strategizer
-    Strategy = Struct.new :tests, :tests_and_groups
+    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,10 +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 tests, grouped_tests
-      already_included_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)
 
-      Strategy.new tests, tests.map { |test|
+      grouped_tests = prepare_run_together_groups run_these_together_groups, thread_safe_tests, thread_unsafe_tests
+      already_included_groups = []
+      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
@@ -25,7 +28,37 @@ class TLDR
         else
           test
         end
-      }.compact
+      }.compact, thread_unsafe_tests
+    end
+
+    private
+
+    def partition_unsafe tests, thread_unsafe_test_groups
+      tests.partition { |test|
+        thread_unsafe_test_groups.any? { |group| group.tests.include? test }
+      }
+    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)
+
+      grouped_tests.each do |group|
+        group.tests = group.tests.select { |test|
+          thread_safe_tests.include?(test) && !thread_unsafe_tests.include?(test)
+        }
+      end
+
+      grouped_tests.reject { |group| group.tests.size < 2 }
     end
   end
 end

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.3.0"
+  VERSION = "0.5.0"
 end

data/lib/tldr.rb

@@ -4,10 +4,11 @@ require_relative "tldr/argv_parser"
 require_relative "tldr/assertions"
 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/run_these_together"
 require_relative "tldr/runner"
 require_relative "tldr/skippable"
 require_relative "tldr/sorbet_compatibility"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tldr
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Justin Searls
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-26 00:00:00.000000000 Z
+date: 2023-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: super_diff
@@ -60,14 +60,15 @@ files:
 - lib/tldr/assertions/minitest_compatibility.rb
 - lib/tldr/backtrace_filter.rb
 - 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
 - lib/tldr/reporters/base.rb
 - lib/tldr/reporters/default.rb
 - lib/tldr/reporters/icon_provider.rb
-- lib/tldr/run_these_together.rb
 - lib/tldr/runner.rb
 - lib/tldr/skippable.rb
 - lib/tldr/sorbet_compatibility.rb

data/lib/tldr/run_these_together.rb

@@ -1,23 +0,0 @@
-class TLDR
-  GROUPED_TESTS = Concurrent::Array.new
-
-  # If it's not safe to run a set of tests in parallel, you can force them to
-  # run in a group together (in a single worker) with `run_these_together!` in
-  # your test.
-  #
-  # This method takes an array of tuples, where the first element is the class
-  # (or its name as a string, if the class is not yet defined in the current
-  # file) and the second element is the method name. If the second element is
-  # nil, then all the tests on the class will be run together.
-  #
-  # Examples:
-  #   - `run_these_together!` will run all the tests defined on the current
-  #     class to be run in a group
-  #   - `run_these_together!([[ClassA, nil], ["ClassB", :test_1], [ClassB, :test_2]])`
-  #    will run all the tests defined on ClassA, and test_1 and test_2 from ClassB
-  #   (nil in the second position means "all the tests on this class")
-  #
-  def self.run_these_together! klass_method_tuples = [[self, nil]]
-    GROUPED_TESTS << TestGroup.new(klass_method_tuples)
-  end
-end