rspec-rewind 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fa005ed6c1c90ab9f476de60e4ae3f34f09e98306cdc64794b9ff171e880d703
+  data.tar.gz: ac9ac1e102d7b52cbe88ed25d21829ee94714d39a13b68ceaa7caa5ba4008b61
+SHA512:
+  metadata.gz: 5cf553951d1d8de3b01c4dc81d9c17cb3b1add64b437e83f4289a906584ded67ce50f4d2664b596e2ad0f2f75251c8b71005587ac6f3df7d58f8999afd293d64
+  data.tar.gz: ad6e9e857fd293dcc1e30dc2653b449ab12a7d96c4f2c3a8d2c0164187cd7ec198bfe0056eb9d357936cb164d2a9f552c02f7151ab91e231ec15348f282b8437

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 0.1.0 (2026-02-07)
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,211 @@
+<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.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "rspec-rewind"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+`require "rspec/rewind"` installs an around hook automatically.
+
+```ruby
+# spec/spec_helper.rb
+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.retry_budget = 20
+  config.flaky_report_path = "tmp/rspec-rewind/flaky.jsonl"
+end
+```
+
+Basic per-example retry:
+
+```ruby
+it "eventually becomes consistent", rewind: 2 do
+  expect(fetch_remote_state).to eq("ready")
+end
+```
+
+## Per-Example Controls
+
+```ruby
+it "uses metadata overrides",
+   rewind: 3,
+   rewind_wait: 0.2,
+   rewind_retry_on: [Net::ReadTimeout, /502/],
+   rewind_skip_retry_on: [NoMethodError],
+   rewind_if: ->(exception, _example) { exception.message.include?("gateway") } do
+  expect(call_api).to eq(:ok)
+end
+```
+
+| Metadata key | Description |
+| --- | --- |
+| `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. |
+
+Matcher types for `retry_on` and `skip_retry_on`: `Module`, `Regexp`, or callable.
+
+## 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:
+
+```ruby
+RSpec::Rewind::Backoff.fixed(0.2)
+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
+
+```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
+end
+```
+
+### JSONL Flaky Report
+
+```ruby
+RSpec::Rewind.configure do |config|
+  config.flaky_report_path = "tmp/rspec-rewind/flaky.jsonl"
+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`
+
+## Compatibility
+
+- Ruby `>= 3.1`
+- RSpec Core `>= 3.12`, `< 4.0`
+
+## Development
+
+```bash
+bundle exec rspec
+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/attempt_runner.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rewind
+    class AttemptRunner
+      FATAL_EXCEPTIONS = [
+        NoMemoryError,
+        ScriptError,
+        SignalException,
+        SystemExit,
+        SecurityError
+      ].freeze
+
+      def run(run_target:, exception_source:)
+        started_at = monotonic_time
+
+        begin
+          run_target.run
+          duration = monotonic_time - started_at
+          [current_exception(exception_source), duration, false]
+        rescue Exception => e
+          raise if fatal_exception?(e)
+
+          duration = monotonic_time - started_at
+          [e, duration, true]
+        end
+      end
+
+      private
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def current_exception(exception_source)
+        return nil unless exception_source.respond_to?(:exception)
+
+        exception_source.exception
+      end
+
+      def fatal_exception?(exception)
+        FATAL_EXCEPTIONS.any? { |klass| exception.is_a?(klass) }
+      end
+    end
+  end
+end

data/lib/rspec/rewind/backoff.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rewind
+    module Backoff
+      module_function
+
+      def fixed(seconds)
+        value = normalize_numeric(seconds, 'seconds')
+        ->(**_) { value }
+      end
+
+      def linear(step:, max: nil)
+        step_value = normalize_numeric(step, 'step')
+        max_value = max.nil? ? nil : normalize_numeric(max, 'max')
+
+        lambda do |retry_number:, **_|
+          delay = step_value * retry_number.to_i
+          clamp(delay, max_value)
+        end
+      end
+
+      def exponential(base:, factor: 2.0, max: nil, jitter: 0.0)
+        base_value = normalize_numeric(base, 'base')
+        factor_value = normalize_numeric(factor, 'factor')
+        jitter_value = normalize_numeric(jitter, 'jitter')
+        max_value = max.nil? ? nil : normalize_numeric(max, 'max')
+
+        lambda do |retry_number:, **_|
+          exponent = [retry_number.to_i - 1, 0].max
+          delay = base_value * (factor_value**exponent)
+          delay = clamp(delay, max_value)
+
+          next delay if jitter_value.zero?
+
+          spread = delay * jitter_value
+          min_delay = [delay - spread, 0.0].max
+          max_delay = delay + spread
+          (Kernel.rand * (max_delay - min_delay)) + min_delay
+        end
+      end
+
+      def clamp(value, max)
+        return value unless max
+
+        [value, max].min
+      end
+      private_class_method :clamp
+
+      def normalize_numeric(value, name)
+        number = begin
+          Float(value)
+        rescue TypeError, ArgumentError
+          raise ArgumentError, "#{name} must be a numeric value"
+        end
+
+        raise ArgumentError, "#{name} must be >= 0" if number.negative?
+
+        number
+      end
+      private_class_method :normalize_numeric
+    end
+  end
+end

data/lib/rspec/rewind/configuration.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rewind
+    class Configuration
+      include MatcherValidation
+
+      attr_reader :default_retries, :backoff, :retry_on, :skip_retry_on, :retry_if, :retry_callback, :flaky_callback,
+                  :verbose, :display_retry_failure_messages, :clear_lets_on_failure, :retry_budget, :flaky_reporter
+
+      def initialize
+        self.default_retries = 0
+        self.backoff = Backoff.fixed(0)
+        self.retry_on = []
+        self.skip_retry_on = []
+        self.retry_if = nil
+        self.retry_callback = nil
+        self.flaky_callback = nil
+        self.verbose = false
+        self.display_retry_failure_messages = false
+        self.clear_lets_on_failure = true
+        self.retry_budget = nil
+        self.flaky_reporter = FlakyReporter.null
+      end
+
+      def default_retries=(value)
+        @default_retries = parse_non_negative_integer(value, source: 'default_retries')
+      end
+
+      def backoff=(value)
+        @backoff = normalize_backoff(value)
+      end
+
+      def retry_on=(values)
+        @retry_on = normalize_matchers(values, field: 'retry_on')
+      end
+
+      def skip_retry_on=(values)
+        @skip_retry_on = normalize_matchers(values, field: 'skip_retry_on')
+      end
+
+      def retry_if=(callable)
+        @retry_if = normalize_callable(callable, field: 'retry_if')
+      end
+
+      def retry_callback=(callable)
+        @retry_callback = normalize_callable(callable, field: 'retry_callback')
+      end
+
+      def flaky_callback=(callable)
+        @flaky_callback = normalize_callable(callable, field: 'flaky_callback')
+      end
+
+      def verbose=(value)
+        @verbose = normalize_boolean(value, field: 'verbose')
+      end
+
+      def display_retry_failure_messages=(value)
+        @display_retry_failure_messages = normalize_boolean(value, field: 'display_retry_failure_messages')
+      end
+
+      def clear_lets_on_failure=(value)
+        @clear_lets_on_failure = normalize_boolean(value, field: 'clear_lets_on_failure')
+      end
+
+      def retry_budget=(limit_or_budget)
+        @retry_budget =
+          if limit_or_budget.is_a?(RetryBudget)
+            limit_or_budget
+          else
+            RetryBudget.new(limit_or_budget)
+          end
+      end
+
+      def flaky_reporter=(reporter)
+        @flaky_reporter = reporter || FlakyReporter.null
+      end
+
+      def flaky_report_path=(path)
+        @flaky_reporter = path.nil? ? FlakyReporter.null : FlakyReporter.jsonl(path)
+      end
+
+      private
+
+      def parse_non_negative_integer(value, source:)
+        parsed = begin
+          Integer(value)
+        rescue TypeError, ArgumentError
+          raise ArgumentError, "#{source} must be a non-negative integer"
+        end
+
+        raise ArgumentError, "#{source} must be >= 0" if parsed.negative?
+
+        parsed
+      end
+
+      def normalize_backoff(value)
+        if value.is_a?(Numeric)
+          number = Float(value)
+          raise ArgumentError, 'backoff must be >= 0' if number.negative?
+
+          return number
+        end
+
+        return value if value.respond_to?(:call)
+
+        raise ArgumentError, 'backoff must be a non-negative numeric value or callable'
+      end
+
+      def normalize_callable(callable, field:)
+        return nil if callable.nil?
+
+        return callable if callable.respond_to?(:call)
+
+        raise ArgumentError, "#{field} must be nil or callable"
+      end
+
+      def normalize_boolean(value, field:)
+        return value if [true, false].include?(value)
+
+        raise ArgumentError, "#{field} must be true or false"
+      end
+    end
+  end
+end

data/lib/rspec/rewind/event.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rewind
+    EVENT_SCHEMA_VERSION = 1
+
+    Event = Struct.new(
+      :schema_version,
+      :status,
+      :retry_reason,
+      :example_id,
+      :description,
+      :location,
+      :attempt,
+      :retries,
+      :exception_class,
+      :exception_message,
+      :duration,
+      :sleep_seconds,
+      :timestamp,
+      keyword_init: true
+    )
+  end
+end

data/lib/rspec/rewind/example_context.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rewind
+    class ExampleContext
+      def initialize(example:)
+        @example = example
+      end
+
+      def source
+        return @example.example if @example.respond_to?(:example) && @example.example
+
+        @example
+      end
+
+      def metadata
+        return {} unless source.respond_to?(:metadata)
+
+        source.metadata || {}
+      end
+
+      def id
+        source.respond_to?(:id) ? source.id : 'unknown'
+      end
+    end
+  end
+end

data/lib/rspec/rewind/example_methods.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rewind
+    module ExampleMethods
+      def run_with_rewind(options = {})
+        normalized = normalize_options(options)
+
+        Runner.new(example: self, configuration: RSpec::Rewind.configuration).run(**normalized)
+      end
+
+      private
+
+      def normalize_options(options)
+        return {} if options.nil? || options.empty?
+
+        symbolized = options.transform_keys(&:to_sym)
+
+        {
+          retries: symbolized[:retries],
+          backoff: symbolized[:backoff],
+          wait: symbolized[:wait],
+          retry_on: symbolized[:retry_on],
+          skip_retry_on: symbolized[:skip_retry_on],
+          retry_if: symbolized[:retry_if]
+        }.compact
+      end
+    end
+  end
+end

data/lib/rspec/rewind/example_state_resetter.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rewind
+    class ExampleStateResetter
+      def initialize(configuration:)
+        @configuration = configuration
+      end
+
+      def reset(example_source)
+        clear_exception(example_source)
+        clear_execution_result(example_source)
+        clear_lets(example_source) if @configuration.clear_lets_on_failure
+      end
+
+      private
+
+      def clear_exception(example_source)
+        if example_source.respond_to?(:clear_exception)
+          example_source.clear_exception
+        elsif example_source.instance_variable_defined?(:@exception)
+          example_source.instance_variable_set(:@exception, nil)
+        end
+      end
+
+      def clear_execution_result(example_source)
+        return unless example_source.respond_to?(:execution_result)
+
+        result = example_source.execution_result
+        return unless result
+
+        set_if_writer(result, :status, nil)
+        set_if_writer(result, :exception, nil)
+        set_if_writer(result, :pending_message, nil)
+        set_if_writer(result, :run_time, nil)
+      end
+
+      def clear_lets(example_source)
+        return unless example_source.respond_to?(:example_group_instance)
+
+        group_instance = example_source.example_group_instance
+        return unless group_instance
+
+        if group_instance.respond_to?(:clear_lets)
+          group_instance.clear_lets
+        elsif group_instance.instance_variable_defined?(:@__memoized)
+          group_instance.instance_variable_set(:@__memoized, nil)
+        end
+      end
+
+      def set_if_writer(target, attribute, value)
+        writer = "#{attribute}="
+        target.public_send(writer, value) if target.respond_to?(writer)
+      end
+    end
+  end
+end

data/lib/rspec/rewind/flaky_reporter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+
+module RSpec
+  module Rewind
+    class FlakyReporter
+      class << self
+        def null
+          @null ||= NullReporter.new
+        end
+
+        def jsonl(path)
+          JsonlReporter.new(path)
+        end
+      end
+
+      class NullReporter
+        def record(_event); end
+      end
+
+      class JsonlReporter
+        def initialize(path)
+          @path = path
+          @mutex = Mutex.new
+        end
+
+        def record(event)
+          payload = {
+            schema_version: event.schema_version,
+            status: event.status,
+            retry_reason: event.retry_reason,
+            example_id: event.example_id,
+            description: event.description,
+            location: event.location,
+            attempt: event.attempt,
+            retries: event.retries,
+            exception_class: event.exception_class,
+            exception_message: event.exception_message,
+            duration: event.duration,
+            sleep_seconds: event.sleep_seconds,
+            timestamp: event.timestamp
+          }
+
+          @mutex.synchronize do
+            FileUtils.mkdir_p(File.dirname(@path))
+            File.open(@path, 'a') { |file| file.puts(JSON.generate(payload)) }
+          end
+        end
+      end
+    end
+  end
+end