tldr 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e62dd10f12e7e2f2e2a691e0679207f4f3231b916b54b6fc51acbe51cc899918
-  data.tar.gz: 2d29248e49b135cc840e3ad249f067ee0a4b706a730889c806c3385f0791f54c
+  metadata.gz: d60d27a492477aa1034acf117993630307f595690f97d356da763fb352f4837e
+  data.tar.gz: 240ee628207bf5b79568fff7ef93b5e6174825b8a53748e2b453076d2d00db7a
 SHA512:
-  metadata.gz: 3a02db5e6c8c42a2d507a5b6ff99867060fd902bf94ef980546d052c535577db4174a6e3ab05e7146876ca4fc7f992030f40daf425a96c3d82e1439fd27b980c
-  data.tar.gz: d580e9a4176c182da622ff826e2d7df64e9ed52f71efe933a22f6dff32d4e8ed60953e5062fccd23f8a2e24db4f0ed26ecaa00144dd5261728fa8b804e8f5c5b
+  metadata.gz: 9e513372aedda6a808ee61e426fc3c738e1f7837fe3ccb55ec658153c15998b4eab9da976680f062d936c638e6fcdcbdcdfabec181137acc48ce6187b5d4aa69
+  data.tar.gz: 4fa415b7f6858e8a26766232a251542f28e7485ead112dd514d72fb55364ae54520ff1d3585dada05e8e56861295dfe458922f4038b1cdb67ee7ec1c4883f382

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## unreleased
 
+## [1.1.0]
+
+* Add `--exit-0-on-timeout` to allow the suite timeout to be used more as a budget constraint (e.g. "I know my full suite is going to take 30 seconds to run but I want to constantly run as many as I can in 500ms to get fast feedback")
+* Add `--exit-2-on-failure` flag to exit with status 2 for test failures (not just errors), useful for Claude Code hooks which only block on exit code 2
+
 ## [1.0.0]
 
 * **BREAKING** you know how the whole point of TLDR is that it aborts your test

data/README.md

@@ -1,16 +1,16 @@
-# TLDR - Ruby tests for people who prioritize fast feedback
+# TLDR - Testing for rubyists who want fast feedback
 
 TLDR is a suspiciously-delightful testing framework for Ruby.
 
 As a test library, TLDR is largely [API-compatible with Minitest](#minitest-compatibility). As a test runner, TLDR boasts a few features RSpec's CLI still doesn't have.
 
-The library, command line interface, and every decision in-between was prioritized to maximize productivity by promote fast feedback loops. Some highlights:
+The library, command line interface, and every decision in-between was prioritized to maximize productivity to promote fast feedback loops. Some highlights:
 
-* Numerous ways to run specific tests: by path (`foo_test.rb`), line number (`foo_test.rb:13`), name (`--name test_foo`), or regex pattern (`-n /_foo_/`)
+* Numerous ways to run specific tests: path (`foo_test.rb`), line number (`foo_test.rb:13`), name (`--name test_foo`), or regex pattern (`-n /_foo/`)
 * Parallel test execution by default, as well as [controls for serial execution of thread-unsafe tests](#parallel-by-default-is-nice-in-theory-but-half-my-tests-are-failing-wat)
 * Continuously run [after every file change](#running-tests-continuously-with---watch) with `--watch`
 * An optional timer to [enforce your tests never get slow](#enforcing-a-testing---timeout) with `--timeout`
-* A `--fail-fast` flag that aborts the run as soon as a failure is encountered
+* A `--fail-fast` flag that aborts the run [as soon as a failure is encountered](#failing-fast-and-first)
 * Running your most-recently-edited test before all the others (see `--prepend`)
 * Delightful diffs when assertions fail, care of [super_diff](https://github.com/splitwise/super_diff)
 
@@ -18,9 +18,9 @@ We hope you'll give it a try!
 
 ## Getting started
 
-You can either read the rest of this README and learn about TLDR passively, or you can just clone this [TLDR demo repo](https://github/searls/tldr_demo) and work through its README as you play with its tests and run them with various options.
+You can either read the rest of this README and learn about TLDR passively, or you can just clone this [TLDR demo repo](https://github.com/searls/tldr_demo) and work through its README as you play with its tests and run them with various options.
 
-**JUST IN CASE YOU'RE ALREADY SKIMMING THIS**, I said stop reading and [clone this interactive repo](https://github/searls/tldr_demo) if you're a hands-on learner.
+**JUST IN CASE YOU'RE ALREADY SKIMMING THIS**, I said stop reading and [clone this interactive repo](https://github.com/searls/tldr_demo) if you're a hands-on learner.
 
 ### Install
 
@@ -61,15 +61,17 @@ Usage: tldr [options] some_tests/**/*.rb some/path.rb:13 ...
         --[no-]warnings              Print Ruby warnings (Default: true)
     -v, --verbose                    Print stack traces for errors
         --yes-i-know                 Suppress TLDR report when suite runs beyond any configured --timeout
+        --exit-0-on-timeout          Exit with status code 0 when suite times out instead of 3
+        --exit-2-on-failure          Exit with status code 2 (normally for errors) for both failures and errors
         --print-interrupted-test-backtraces
                                      Print stack traces of tests interrupted after a timeout
 ```
 
 ### Setting defaults in .tldr.yml
 
-The `tldr` CLI will look for a `.tldr.yml` that can set the same set of options supported by the CLI file in the root of your project. You can specify a custom YAML location with `--config some/path.yml` if you need to.
+The `tldr` CLI will look for a `.tldr.yml` file in the root of your project that can set all the same options supported by the CLI. You can specify a custom YAML location with `--config some/path.yml` if you want it to live someplace else.
 
-Any options found in the dotfile will override TLDR's defaults, but can still be overridden by the `tldr` CLI or a `TLDR::Config` object passed to [TLDR::Run.at_exit!](#running-tests-without-the-cli).
+Any options found in the dotfile will override TLDR's defaults, but can still be overridden by the `tldr` CLI or a `TLDR::Config` object when running tests programmatically.
 
 Here's an [example project](/example/c) that specifies a `.tldr.yml` file as well as some [internal tests](/tests/dotfile_test.rb) demonstrating its behavior.
 
@@ -77,7 +79,7 @@ Here's an [example project](/example/c) that specifies a `.tldr.yml` file as wel
 
 If you've ever seen a [Minitest](https://github.com/minitest/minitest?tab=readme-ov-file#synopsis-) test, then you already know how to write TLDR tests. Rather than document how to write tests, this section just highlights the ways TLDR tests differ from Minitest tests.
 
-First, instead of inheriting from `Minitest::Test`, your test classes must subclass `TLDR` instead:
+First, instead of inheriting from `Minitest::Test`, TLDR test classes should descend from (wait for it) the `TLDR` base class:
 
 ```ruby
 class MyTest < TLDR
@@ -87,7 +89,7 @@ class MyTest < TLDR
 end
 ```
 
-Second, if your tests depend on a test helper, so long as you name it `test/helper.rb`, it will automatically be required by TLDR, so you don't need to add `require "helper"` at the top of each test. If you want to name the helper something else, you can do so with the `--helper` option:
+Second, if your tests depend on a test helper, it will be automatically loaded by TLDR _if_ you name it `test/helper.rb`. That means you don't need to add `require "helper"` to the top of every test. If you want to name the helper something else, you can do so with the `--helper` option:
 
 ```
 tldr --helper test/test_helper.rb
@@ -98,13 +100,13 @@ Third, TLDR offers fewer features:
 * No built-in mock library ([use mocktail](https://justin.searls.co/posts/a-real-world-mocktail-example-test/), maybe!)
 * No "spec" API
 * No benchmark tool
-* No test bisect script
+* No bisect script
 
-And that's it! You now know how to write TLDR tests.
+And that's it! You officially know how to write TLDR tests.
 
 ## Running your tests
 
-Because TLDR ships with a CLI, it offers a _lot_ of ways to run your tests.
+Because TLDR ships with a CLI, it offers a veritable _plethora_ of ways to run your tests.
 
 ### Running your tests
 
@@ -120,7 +122,7 @@ This assumes your tests are stored in `test/`. It will also add `lib/` to Ruby's
 
 TLDR ships with a minimal [rake task](lib/tldr/rake.rb) that simply shells out to the `tldr` CLI by default. If you want to run TLDR with Rake, you can configure the task by setting flags on an env var named `TLDR_OPTS` or in a [.tldr.yml file](#setting-defaults-in-tldryml).
 
-All your Rakefile needs is `require "tldr/rake` and you can run the task individually like this:
+All your Rakefile needs is `require "tldr/rake"` and you can run the task individually like this:
 
 ```
 $ rake tldr
@@ -138,9 +140,9 @@ require "tldr/rake"
 task default: ["tldr", "standard:fix"]
 ```
 
-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).
+One situation where you'd want to invoke TLDR with Rake is when you have multiple test suites that you want to be able to easily 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 task, you can instantiate `TLDR::Task` like this, which allows you to configure [TLDR::Config](/lib/tldr/value/config.rb) in code:
+To create a custom TLDR Rake task, you can instantiate `TLDR::Task` like this, which allows you to define its [TLDR::Config](/lib/tldr/value/config.rb) configuration in code:
 
 ```ruby
 require "tldr/rake"
@@ -258,6 +260,35 @@ timeout: 0.01
 
 And if you're running with the timeout enabled this way, you can still disable it for any given test run by adding the `--no-timeout` flag.
 
+#### Consider timeouts as a success with exit code 0
+
+By default, when TLDR times out it exits with status code 3 to indicate the test suite was aborted. However, if you know that your full test suite is slower than whatever duration you consider to be "fast enough for fast feedback", you can use the `--exit-0-on-timeout` flag and simply use the timeout to enforce whatever feedback loop budget you set with `--timeout`.
+
+For example:
+
+```
+# Get feedback within 400ms but don't consider a timeout a failure
+tldr --timeout 0.4 --exit-0-on-timeout
+```
+
+This is particularly useful for:
+- [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) where you want fast feedback without failing the command
+- [Git pre-commit hooks](https://git-scm.com/docs/githooks#_pre_commit) where you want quick test results without blocking commits
+- Development workflows where timeouts are informational rather than failures
+- Any situation where you want a time budget without hard failures
+
+## Using TLDR as a Claude Code hook
+
+In AI agent-based coding workflows, it's common to [configure hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) that will block the agent from proceeding whenever tests or linters fail. With Claude Code specifically, a hook will only block if it exits with status code 2. As a result, you can use `--exit-2-on-failure` so that assertion failures will block the agent from continuing.
+
+So you might configure a Claude Code hook with a 250ms budget by setting timeouts to exit code 0 and failures to exit code 2:
+
+```
+# Get feedback within 250ms, don't block the agent on timeouts, but do block it on assertion failures
+tldr --timeout 0.25 --exit-0-on-timeout --exit-2-on-failure
+```
+
+
 ## Questions you might be asking
 
 TLDR is very similar to Minitest in API, but different in enough ways that you

data/lib/tldr/argv_parser.rb

@@ -106,6 +106,14 @@ class TLDR
           options[:yes_i_know] = true
         end
 
+        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 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

data/lib/tldr/runner.rb

@@ -40,7 +40,13 @@ class TLDR
           @run_aborted.make_true
           @wip.each(&:capture_backtrace_at_exit)
           reporter.after_tldr(plan.tests, @wip.dup, @results.dup) if reporter.respond_to?(:after_tldr)
-          exit!(3)
+
+          # 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(config.timeout)
@@ -62,7 +68,7 @@ class TLDR
 
       unless @run_aborted.true?
         reporter.after_suite(results) if reporter.respond_to?(:after_suite)
-        exit(exit_code(results))
+        exit(exit_code(results, config))
       end
     end
 
@@ -119,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

data/lib/tldr/value/config.rb

@@ -22,6 +22,8 @@ class TLDR
     yes_i_know: "--yes-i-know",
     print_interrupted_test_backtraces: "--print-interrupted-test-backtraces",
     i_am_being_watched: "--i-am-being-watched",
+    exit_0_on_timeout: "--exit-0-on-timeout",
+    exit_2_on_failure: "--exit-2-on-failure",
     paths: nil
   }.freeze
 
@@ -32,7 +34,7 @@ class TLDR
     :exclude_paths, :helper_paths, :no_helper, :prepend_paths, :no_prepend,
     :load_paths, :base_path, :config_path, :reporter, :emoji, :warnings,
     :verbose, :yes_i_know, :print_interrupted_test_backtraces,
-    :i_am_being_watched, :paths,
+    :i_am_being_watched, :exit_0_on_timeout, :exit_2_on_failure, :paths,
     # Internal properties
     :config_intended_for_merge_only, :seed_set_intentionally, :cli_defaults
   ].freeze
@@ -79,7 +81,9 @@ class TLDR
         verbose: false,
         yes_i_know: false,
         print_interrupted_test_backtraces: false,
-        i_am_being_watched: false
+        i_am_being_watched: false,
+        exit_0_on_timeout: false,
+        exit_2_on_failure: false
       }
 
       if cli_defaults
@@ -118,7 +122,7 @@ class TLDR
       end
 
       # Booleans
-      [:watch, :fail_fast, :parallel, :no_helper, :no_prepend, :emoji, :warnings, :verbose, :yes_i_know, :print_interrupted_test_backtraces, :i_am_being_watched].each do |key|
+      [:watch, :fail_fast, :parallel, :no_helper, :no_prepend, :emoji, :warnings, :verbose, :yes_i_know, :print_interrupted_test_backtraces, :i_am_being_watched, :exit_0_on_timeout, :exit_2_on_failure].each do |key|
         merged_args[key] = defaults[key] if merged_args[key].nil?
       end
 

data/lib/tldr/value/test.rb

@@ -10,7 +10,7 @@ class TLDR
 
     # Test exact match starting line condition first to save us a potential re-parsing to look up end_line
     def covers_line? l
-      line == l || (l >= line && l <= end_line)
+      line == l || l.between?(line, end_line)
     end
 
     def group?

data/lib/tldr/version.rb

@@ -1,3 +1,3 @@
 class TLDR
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tldr
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Justin Searls
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-03 00:00:00.000000000 Z
+date: 2025-07-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: super_diff
@@ -130,7 +130,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.27
+rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
 summary: TLDR will run your tests, but only for 1.8 seconds.