rspec-rewind 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa005ed6c1c90ab9f476de60e4ae3f34f09e98306cdc64794b9ff171e880d703
-  data.tar.gz: ac9ac1e102d7b52cbe88ed25d21829ee94714d39a13b68ceaa7caa5ba4008b61
+  metadata.gz: df7affb556767810fad03faf4d94602e90e3f38af615e04742064acf7c1a95a9
+  data.tar.gz: 5d176192d59025af23f2509be6e2161bca3195c05215f7f4008ecc3e69bb187a
 SHA512:
-  metadata.gz: 5cf553951d1d8de3b01c4dc81d9c17cb3b1add64b437e83f4289a906584ded67ce50f4d2664b596e2ad0f2f75251c8b71005587ac6f3df7d58f8999afd293d64
-  data.tar.gz: ad6e9e857fd293dcc1e30dc2653b449ab12a7d96c4f2c3a8d2c0164187cd7ec198bfe0056eb9d357936cb164d2a9f552c02f7151ab91e231ec15348f282b8437
+  metadata.gz: 3ab4033f522b2bdd412113befc6a36470f2ea9847ac0b3c6a1e16c6aec8a4db6114b5fe712638be9ab6e0b52bb707b305c70214caf6a4e7c1a9fb4e7295a984c
+  data.tar.gz: 582d1716789ab6e374b682a9dc5b153e2815b57bddbcf6a018944c57acc65de1bfc4571c7beb55e623bcadc4051e9c908a37b5de8b4acb31b7748eb44b651f42

data/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+
+- Added `rspec/rewind/core` for loading the API without auto-installing the RSpec hook.
+- Added `RSPEC_REWIND_AUTO_INSTALL` and `RSPEC_REWIND_DISABLE` controls.
+- Added retry lifecycle hooks: `before_retry`, `after_retry`, and `not_retried_callback`.
+- Added retry summary and flaky-threshold controls: `display_retry_summary`, `fail_on_flaky`, and `max_flaky_examples`.
+- Added retry limits and dry-run controls: `max_retries`, `max_elapsed_time`, `max_total_sleep`, and `dry_run`.
+- Added process-aware retry budgets with `RSpec::Rewind::FileRetryBudget`.
+- Added richer retry events with decision reasons, matcher details, failure fingerprints, timing, sleep, budget, and selected metadata fields.
+- Added `not_retried` and `reset_failed` event reporting, plus `reset_failure_policy`.
+- Added advanced policy controls for `retry_if_mode`, `retry_on_default`, and metadata append/override modes.
+- Added injectable jitter RNG support for exponential backoff.
+
+### Changed
+
+- Retry event payloads are immutable.
+- Runner configuration is snapshotted per example so later configuration changes do not affect in-flight retries.
+- Flaky reporter path and reporter objects stay synchronized, and reporters are flushed and closed at suite end.
+
+### Fixed
+
+- Clamp retry sleep before sleeping when `max_total_sleep` is configured.
+- Prevent `not_retried_callback` errors from masking the original suite result.
+- Keep reporter lifecycle failures from interrupting suite shutdown unless strict callbacks are enabled.
+- Revalidate existing retry matchers when strict matcher validation is enabled.
+- Validate exponential backoff jitter RNG output and keep jittered delays within the configured maximum.
+
 ## 0.1.0 (2026-02-07)
 
-- Initial release.
+- Initial release.

data/README.md

@@ -1,41 +1,15 @@
-<h1 align="center">rspec-rewind</h1>
-
-<p align="center">
-  Deterministic retry orchestration for flaky RSpec examples.
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/ruby-%3E%3D%203.1-ruby.svg" alt="Ruby Version">
-  <img src="https://img.shields.io/badge/rspec--core-%3E%3D%203.12%2C%20%3C%204.0-brightgreen.svg" alt="RSpec Core Version">
-  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">
-  <a href="https://badge.fury.io/rb/rspec-rewind"><img src="https://badge.fury.io/rb/rspec-rewind.svg" alt="Gem Version" height="18"></a>
-  <a href="https://github.com/ydah/rspec-rewind/actions/workflows/main.yml">
-    <img src="https://github.com/ydah/rspec-rewind/actions/workflows/main.yml/badge.svg" alt="CI Status">
-  </a>
-</p>
-
-<p align="center">
-  <a href="#installation">Installation</a> •
-  <a href="#quick-start">Quick Start</a> •
-  <a href="#per-example-controls">Per-Example Controls</a> •
-  <a href="#configuration">Configuration</a> •
-  <a href="#observability">Observability</a> •
-  <a href="#compatibility">Compatibility</a>
-</p>
-
-`rspec-rewind` is a modern retry gem for RSpec, inspired by [`rspec-retry`](https://github.com/NoRedInk/rspec-retry), with deterministic control and flaky-test observability for CI-heavy projects.
-
-## Why rspec-rewind
-
-- `retries` always means "extra attempts" (not total attempts).
-- Retry filtering with `retry_on`, `skip_retry_on`, and `retry_if`.
-- Configurable delay via fixed, linear, exponential, or custom backoff.
-- Suite-level retry budget to prevent hidden retry inflation.
-- Flaky detection hooks and optional JSONL reporting.
+# rspec-rewind
 
-## Installation
+Deterministic retry orchestration for flaky RSpec examples.
+
+[![Gem Version](https://badge.fury.io/rb/rspec-rewind.svg)](https://badge.fury.io/rb/rspec-rewind)
+[![CI](https://github.com/ydah/rspec-rewind/actions/workflows/main.yml/badge.svg)](https://github.com/ydah/rspec-rewind/actions/workflows/main.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
 
-Add to your Gemfile:
+`rspec-rewind` retries RSpec examples with explicit retry counts, exception filters,
+backoff strategies, retry budgets, and flaky-test reporting.
+
+## Installation
 
 ```ruby
 gem "rspec-rewind"
@@ -47,9 +21,10 @@ Then run:
 bundle install
 ```
 
-## Quick Start
+## Usage
 
-`require "rspec/rewind"` installs an around hook automatically.
+Require `rspec/rewind` from your RSpec setup file. This installs the around hook
+automatically.
 
 ```ruby
 # spec/spec_helper.rb
@@ -57,15 +32,16 @@ require "rspec/rewind"
 
 RSpec::Rewind.configure do |config|
   config.default_retries = 1
-  config.backoff = RSpec::Rewind::Backoff.exponential(base: 0.1, factor: 2.0, max: 1.0, jitter: 0.2)
   config.retry_on = [Net::ReadTimeout, Errno::ECONNRESET]
   config.skip_retry_on = [NoMethodError]
+  config.backoff = RSpec::Rewind::Backoff.exponential(base: 0.1, factor: 2.0, max: 1.0)
   config.retry_budget = 20
   config.flaky_report_path = "tmp/rspec-rewind/flaky.jsonl"
 end
 ```
 
-Basic per-example retry:
+Retry counts are extra attempts. `rewind: 2` can run the example up to three
+times total.
 
 ```ruby
 it "eventually becomes consistent", rewind: 2 do
@@ -76,7 +52,7 @@ end
 ## Per-Example Controls
 
 ```ruby
-it "uses metadata overrides",
+it "retries transient API failures",
    rewind: 3,
    rewind_wait: 0.2,
    rewind_retry_on: [Net::ReadTimeout, /502/],
@@ -86,37 +62,19 @@ it "uses metadata overrides",
 end
 ```
 
-| Metadata key | Description |
+| Key | Meaning |
 | --- | --- |
-| `rewind` | Retry count override. `true` = use default, `false` = disable retries for that example/group. |
-| `rewind_wait` | Fixed sleep before next attempt. |
-| `rewind_backoff` | Backoff strategy (numeric or callable). |
-| `rewind_retry_on` | Extra allow-list matchers. |
-| `rewind_skip_retry_on` | Extra deny-list matchers (checked first). |
-| `rewind_if` | Predicate `(exception)` or `(exception, example)` returning truthy/falsey. |
+| `rewind` | Extra retry count. `true` uses the configured default; `false` disables retries. |
+| `rewind_wait` | Fixed delay before the next attempt. |
+| `rewind_backoff` | Numeric or callable backoff strategy. |
+| `rewind_retry_on` | Additional retry allow-list matchers. |
+| `rewind_skip_retry_on` | Additional retry deny-list matchers. Checked before allow-list matchers. |
+| `rewind_if` | Predicate that decides whether the failure should retry. |
 
-Matcher types for `retry_on` and `skip_retry_on`: `Module`, `Regexp`, or callable.
+`retry_on` and `skip_retry_on` matchers can be exception classes, regexps, or
+callables.
 
-## Configuration
-
-```ruby
-RSpec::Rewind.configure do |config|
-  config.default_retries = 0
-  config.backoff = RSpec::Rewind::Backoff.fixed(0)
-  config.retry_on = []
-  config.skip_retry_on = []
-  config.retry_if = nil
-  config.retry_callback = nil
-  config.flaky_callback = nil
-  config.retry_budget = nil
-  config.flaky_report_path = nil
-  config.verbose = false
-  config.display_retry_failure_messages = false
-  config.clear_lets_on_failure = true
-end
-```
-
-Backoff helpers:
+## Backoff
 
 ```ruby
 RSpec::Rewind::Backoff.fixed(0.2)
@@ -124,39 +82,18 @@ RSpec::Rewind::Backoff.linear(step: 0.1, max: 1.0)
 RSpec::Rewind::Backoff.exponential(base: 0.1, factor: 2.0, max: 2.0, jitter: 0.2)
 ```
 
-Environment override:
-
-```bash
-RSPEC_REWIND_RETRIES=2 bundle exec rspec
-```
-
-`RSPEC_REWIND_RETRIES` has highest priority over defaults and metadata.
-
-## Retry Decision Order
-
-1. Stop if no exception happened.
-2. Stop if exception matches any `skip_retry_on`.
-3. If `retry_on` is set, stop unless exception matches at least one matcher.
-4. If `retry_if` exists, retry only when predicate returns truthy.
-5. Stop if retry budget is exhausted.
-
 ## Observability
 
-### Retry and Flaky Callbacks
+Use callbacks when you want to send retry events to logs or metrics.
 
 ```ruby
 RSpec::Rewind.configure do |config|
-  config.retry_callback = ->(event) do
-    puts "[retry] #{event.example_id} attempt=#{event.attempt}/#{event.retries}"
-  end
-
-  config.flaky_callback = ->(event) do
-    puts "[flaky] #{event.description} (attempt #{event.attempt})"
-  end
+  config.retry_callback = ->(event) { warn "[retry] #{event.example_id} attempt=#{event.attempt}" }
+  config.flaky_callback = ->(event) { warn "[flaky] #{event.example_id}" }
 end
 ```
 
-### JSONL Flaky Report
+Set `flaky_report_path` to write flaky examples as JSONL:
 
 ```ruby
 RSpec::Rewind.configure do |config|
@@ -164,21 +101,14 @@ RSpec::Rewind.configure do |config|
 end
 ```
 
-Each flaky JSONL row includes:
-
-- `schema_version`
-- `status` (`flaky`)
-- `retry_reason`
-- `example_id`
-- `description`
-- `location`
-- `attempt`
-- `retries`
-- `exception_class`
-- `exception_message`
-- `duration`
-- `sleep_seconds`
-- `timestamp`
+## Environment
+
+```bash
+RSPEC_REWIND_RETRIES=2 bundle exec rspec
+RSPEC_REWIND_DISABLE=1 bundle exec rspec
+```
+
+`RSPEC_REWIND_RETRIES` takes priority over configured defaults and metadata.
 
 ## Compatibility
 
@@ -188,24 +118,12 @@ Each flaky JSONL row includes:
 ## Development
 
 ```bash
-bundle exec rspec
+bundle install
+bundle exec rake spec
+bundle exec rake rubocop
 bundle exec rake rbs
 ```
 
-CI validates:
-
-- Specs across Ruby 3.1, 3.2, 3.3, 3.4, 4.0, and head
-- Minimum compatibility with RSpec 3.12 (`BUNDLE_GEMFILE=gemfiles/rspec_3_12.gemfile`)
-- Type signatures (`rake rbs`)
-- Coverage threshold (`COVERAGE=1 rspec`)
-- Gem packaging (`rake build`)
-- Dependency security audit (`bundler-audit`)
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub:
-https://github.com/ydah/rspec-rewind
-
 ## License
 
 Released under the [MIT License](LICENSE.txt).

data/lib/rspec/rewind/api.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rewind
+    PUBLIC_API = [
+      Backoff,
+      Configuration,
+      Event,
+      FileRetryBudget,
+      FlakyReporter,
+      RetryBudget,
+      RetryDecision,
+      RetryPolicy,
+      Runner
+    ].freeze
+
+    INTERNAL_API = [
+      AttemptRunner,
+      ExampleContext,
+      ExampleMethods,
+      ExampleStateResetter,
+      FailureFingerprint,
+      FlakyTransition,
+      RetryCountResolver,
+      RetryDelayResolver,
+      RetryEventBuilder,
+      RetryGate,
+      RetryLoop,
+      RetryNotifier,
+      RetryTransition,
+      RunnerComponentFactory,
+      RunnerComponents,
+      RunnerLogger,
+      RSpecAdapter
+    ].freeze
+  end
+end

data/lib/rspec/rewind/attempt_runner.rb

@@ -11,6 +11,10 @@ module RSpec
         SecurityError
       ].freeze
 
+      def initialize(clock: nil)
+        @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      end
+
       def run(run_target:, exception_source:)
         started_at = monotonic_time
 
@@ -18,7 +22,8 @@ module RSpec
           run_target.run
           duration = monotonic_time - started_at
           [current_exception(exception_source), duration, false]
-        rescue Exception => e
+        # RSpec expectation failures inherit from Exception, so fatal exceptions are filtered explicitly.
+        rescue Exception => e # rubocop:disable Lint/RescueException
           raise if fatal_exception?(e)
 
           duration = monotonic_time - started_at
@@ -29,7 +34,7 @@ module RSpec
       private
 
       def monotonic_time
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @clock.call
       end
 
       def current_exception(exception_source)

data/lib/rspec/rewind/backoff.rb

@@ -20,11 +20,13 @@ module RSpec
         end
       end
 
-      def exponential(base:, factor: 2.0, max: nil, jitter: 0.0)
+      def exponential(base:, factor: 2.0, max: nil, jitter: 0.0, rng: Kernel, min_factor: 0.0)
         base_value = normalize_numeric(base, 'base')
         factor_value = normalize_numeric(factor, 'factor')
+        min_factor_value = normalize_numeric(min_factor, 'min_factor')
         jitter_value = normalize_numeric(jitter, 'jitter')
         max_value = max.nil? ? nil : normalize_numeric(max, 'max')
+        raise ArgumentError, "factor must be >= #{min_factor_value}" if factor_value < min_factor_value
 
         lambda do |retry_number:, **_|
           exponent = [retry_number.to_i - 1, 0].max
@@ -36,7 +38,7 @@ module RSpec
           spread = delay * jitter_value
           min_delay = [delay - spread, 0.0].max
           max_delay = delay + spread
-          (Kernel.rand * (max_delay - min_delay)) + min_delay
+          clamp((random_value(rng) * (max_delay - min_delay)) + min_delay, max_value)
         end
       end
 
@@ -59,6 +61,28 @@ module RSpec
         number
       end
       private_class_method :normalize_numeric
+
+      def random_value(rng)
+        raw =
+          if rng.respond_to?(:rand)
+            rng.rand
+          elsif rng.respond_to?(:call)
+            rng.call
+          else
+            raise ArgumentError, 'rng must respond to #rand or #call'
+          end
+
+        value = begin
+          Float(raw)
+        rescue TypeError, ArgumentError
+          raise ArgumentError, 'rng must return a numeric value'
+        end
+
+        raise ArgumentError, 'rng must return a value between 0 and 1' unless value.between?(0.0, 1.0)
+
+        value
+      end
+      private_class_method :random_value
     end
   end
 end