rspec-rewind 0.1.0

data/lib/rspec/rewind/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rewind
+    VERSION = '0.1.0'
+  end
+end

data/lib/rspec/rewind.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'rspec/core'
+require 'time'
+
+require_relative 'rewind/version'
+require_relative 'rewind/backoff'
+require_relative 'rewind/retry_budget'
+require_relative 'rewind/flaky_reporter'
+require_relative 'rewind/matcher_validation'
+require_relative 'rewind/configuration'
+require_relative 'rewind/example_context'
+require_relative 'rewind/event'
+require_relative 'rewind/retry_count_resolver'
+require_relative 'rewind/retry_delay_resolver'
+require_relative 'rewind/retry_event_builder'
+require_relative 'rewind/retry_notifier'
+require_relative 'rewind/flaky_transition'
+require_relative 'rewind/attempt_runner'
+require_relative 'rewind/retry_transition'
+require_relative 'rewind/retry_gate'
+require_relative 'rewind/retry_loop'
+require_relative 'rewind/runner_logger'
+require_relative 'rewind/runner_components'
+require_relative 'rewind/example_state_resetter'
+require_relative 'rewind/retry_policy'
+require_relative 'rewind/retry_decision'
+require_relative 'rewind/runner'
+require_relative 'rewind/example_methods'
+
+module RSpec
+  module Rewind
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+
+      def install!
+        return if @installed
+
+        ::RSpec::Core::Example.include(ExampleMethods)
+        ::RSpec::Core::Example::Procsy.include(ExampleMethods) if defined?(::RSpec::Core::Example::Procsy)
+
+        ::RSpec.configure do |config|
+          config.around(:each) do |example|
+            if example.metadata[:rewind] == false
+              example.run
+            else
+              example.run_with_rewind
+            end
+          end
+        end
+
+        @installed = true
+      end
+    end
+  end
+end
+
+RSpec::Rewind.install!

data/lib/rspec-rewind.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'rspec/rewind'

data/rspec-rewind.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'lib/rspec/rewind/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'rspec-rewind'
+  spec.version = RSpec::Rewind::VERSION
+  spec.authors = ['Yudai Takada']
+  spec.email = ['t.yudai92@gmail.com']
+
+  spec.summary = 'Modern retry orchestration for flaky RSpec examples'
+  spec.description = <<~DESC
+    rspec-rewind provides deterministic retry policies, exception filters,
+    configurable backoff strategies, and flaky test observability for RSpec.
+  DESC
+  spec.homepage = 'https://github.com/ydah/rspec-rewind'
+  spec.license = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.1')
+
+  spec.metadata = {
+    'homepage_uri' => spec.homepage,
+    'source_code_uri' => spec.homepage,
+    'changelog_uri' => "#{spec.homepage}/blob/main/CHANGELOG.md",
+    'rubygems_mfa_required' => 'true'
+  }
+
+  spec.files = Dir.chdir(__dir__) do
+    code_and_signatures = Dir.glob('{lib,sig}/**/*', File::FNM_DOTMATCH).reject do |path|
+      path.include?('/.') || File.directory?(path)
+    end
+
+    code_and_signatures + %w[CHANGELOG.md LICENSE.txt README.md rspec-rewind.gemspec]
+  end
+
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'rspec-core', '>= 3.12', '< 4.0'
+end

data/sig/rspec/rewind.rbs

@@ -0,0 +1,211 @@
+module RSpec
+  module Rewind
+    VERSION: String
+    EVENT_SCHEMA_VERSION: Integer
+
+    class << self
+      def configuration: () -> Configuration
+      def configure: () { (Configuration) -> void } -> void
+      def reset_configuration!: () -> Configuration
+      def install!: () -> bool?
+    end
+
+    module Backoff
+      def self.fixed: (Numeric seconds) -> untyped
+      def self.linear: (step: Numeric, ?max: Numeric?) -> untyped
+      def self.exponential: (base: Numeric, ?factor: Numeric, ?max: Numeric?, ?jitter: Numeric) -> untyped
+    end
+
+    class Configuration
+      attr_reader default_retries: Integer
+      attr_reader backoff: Numeric | untyped
+      attr_reader retry_on: Array[untyped]
+      attr_reader skip_retry_on: Array[untyped]
+      attr_reader retry_if: untyped?
+      attr_reader retry_callback: untyped?
+      attr_reader flaky_callback: untyped?
+      attr_reader verbose: bool
+      attr_reader display_retry_failure_messages: bool
+      attr_reader clear_lets_on_failure: bool
+      attr_reader retry_budget: RetryBudget
+      attr_reader flaky_reporter: FlakyReporter::NullReporter | FlakyReporter::JsonlReporter | untyped
+
+      def initialize: () -> void
+      def default_retries=: (untyped) -> Integer
+      def backoff=: (untyped) -> Numeric | untyped
+      def retry_on=: (untyped) -> Array[untyped]
+      def skip_retry_on=: (untyped) -> Array[untyped]
+      def retry_if=: (untyped?) -> untyped?
+      def retry_callback=: (untyped?) -> untyped?
+      def flaky_callback=: (untyped?) -> untyped?
+      def verbose=: (bool) -> bool
+      def display_retry_failure_messages=: (bool) -> bool
+      def clear_lets_on_failure=: (bool) -> bool
+      def retry_budget=: (RetryBudget | untyped) -> RetryBudget
+      def flaky_reporter=: (FlakyReporter::NullReporter | FlakyReporter::JsonlReporter | untyped?) -> FlakyReporter::NullReporter | FlakyReporter::JsonlReporter | untyped
+      def flaky_report_path=: (String?) -> FlakyReporter::NullReporter | FlakyReporter::JsonlReporter
+    end
+
+    class RetryBudget
+      attr_reader limit: Integer?
+      attr_reader used: Integer
+
+      def initialize: (untyped) -> void
+      def consume!: () -> bool
+      def remaining: () -> Integer | Float
+      def unlimited?: () -> bool
+    end
+
+    class FlakyReporter
+      def self.null: () -> NullReporter
+      def self.jsonl: (String path) -> JsonlReporter
+
+      class NullReporter
+        def record: (Event event) -> void
+      end
+
+      class JsonlReporter
+        def initialize: (String path) -> void
+        def record: (Event event) -> void
+      end
+    end
+
+    class Event < ::Struct
+      attr_accessor schema_version: Integer
+      attr_accessor status: Symbol
+      attr_accessor retry_reason: Symbol?
+      attr_accessor example_id: String
+      attr_accessor description: String
+      attr_accessor location: String
+      attr_accessor attempt: Integer
+      attr_accessor retries: Integer
+      attr_accessor exception_class: String?
+      attr_accessor exception_message: String?
+      attr_accessor duration: Numeric
+      attr_accessor sleep_seconds: Numeric
+      attr_accessor timestamp: String
+    end
+
+    class ExampleContext
+      def initialize: (example: untyped) -> void
+      def source: () -> untyped
+      def metadata: () -> Hash[Symbol, untyped]
+      def id: () -> String
+    end
+
+    module ExampleMethods
+      def run_with_rewind: (?Hash[Symbol | String, untyped]) -> void
+    end
+
+    class RetryDecision
+      def initialize: (exception: Exception?, example: untyped, retry_on: untyped, skip_retry_on: untyped, retry_if: untyped?) -> void
+      def retry?: () -> bool
+    end
+
+    class RetryPolicy
+      def initialize: (example: untyped, configuration: Configuration, metadata: Hash[Symbol, untyped]?) -> void
+      def retry_allowed?: (exception: Exception, retry_on: untyped, skip_retry_on: untyped, retry_if: untyped?) -> bool
+    end
+
+    class RetryCountResolver
+      ENV_RETRIES_KEY: String
+
+      def initialize: (configuration: Configuration, metadata: Hash[Symbol, untyped]?) -> void
+      def resolve: (explicit_retries: untyped) -> Integer
+    end
+
+    class RetryDelayResolver
+      def initialize: (configuration: Configuration, metadata: Hash[Symbol, untyped]?, example: untyped) -> void
+      def resolve: (retry_number: Integer, backoff: untyped, wait: untyped, exception: Exception) -> Float
+    end
+
+    class AttemptRunner
+      def run: (run_target: untyped, exception_source: untyped) -> [Exception?, Float, bool]
+    end
+
+    class FlakyTransition
+      def initialize: (event_builder: untyped, notifier: untyped) -> void
+      def perform: (attempt: Integer, retries: Integer, duration: Numeric) -> void
+    end
+
+    class RetryTransition
+      def initialize: (
+        configuration: Configuration,
+        retry_delay_resolver: untyped,
+        event_builder: untyped,
+        notifier: untyped,
+        state_resetter: untyped,
+        sleep: untyped
+      ) -> void
+      def perform: (
+        retry_number: Integer,
+        resolved_retries: Integer,
+        duration: Numeric,
+        exception: Exception,
+        backoff: untyped,
+        wait: untyped,
+        example_source: untyped
+      ) -> void
+    end
+
+    class RetryGate
+      def initialize: (configuration: Configuration, retry_policy: RetryPolicy, debug: untyped) -> void
+      def allow?: (
+        exception: Exception,
+        retry_number: Integer,
+        resolved_retries: Integer,
+        retry_on: untyped,
+        skip_retry_on: untyped,
+        retry_if: untyped?,
+        example_id: String
+      ) -> bool
+    end
+
+    class RunnerLogger
+      def initialize: (configuration: Configuration, warn_output: untyped) -> void
+      def reporter_message: (String) -> void
+      def debug: (String) -> void
+    end
+
+    class RetryLoop
+      def initialize: (
+        example: untyped,
+        context: ExampleContext,
+        retry_count_resolver: RetryCountResolver,
+        attempt_runner: AttemptRunner,
+        retry_gate: RetryGate,
+        retry_transition: RetryTransition,
+        flaky_transition: FlakyTransition
+      ) -> void
+      def run: (
+        retries: untyped,
+        backoff: untyped,
+        wait: untyped,
+        retry_on: untyped,
+        skip_retry_on: untyped,
+        retry_if: untyped
+      ) -> void
+    end
+
+    class RunnerComponents
+      attr_reader retry_count_resolver: RetryCountResolver
+      attr_reader attempt_runner: AttemptRunner
+      attr_reader retry_gate: RetryGate
+      attr_reader retry_transition: RetryTransition
+      attr_reader flaky_transition: FlakyTransition
+      attr_reader retry_loop: RetryLoop
+
+      def initialize: (
+        example: untyped,
+        configuration: Configuration,
+        context: ExampleContext,
+        logger: RunnerLogger
+      ) -> void
+    end
+
+    class Runner
+      def initialize: (example: untyped, configuration: Configuration) -> void
+      def run: (?retries: untyped, ?backoff: untyped, ?wait: untyped, ?retry_on: untyped, ?skip_retry_on: untyped, ?retry_if: untyped) -> void
+    end
+  end
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: rspec-rewind
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.12'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.12'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: |
+  rspec-rewind provides deterministic retry policies, exception filters,
+  configurable backoff strategies, and flaky test observability for RSpec.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/rspec-rewind.rb
+- lib/rspec/rewind.rb
+- lib/rspec/rewind/attempt_runner.rb
+- lib/rspec/rewind/backoff.rb
+- lib/rspec/rewind/configuration.rb
+- lib/rspec/rewind/event.rb
+- lib/rspec/rewind/example_context.rb
+- lib/rspec/rewind/example_methods.rb
+- lib/rspec/rewind/example_state_resetter.rb
+- lib/rspec/rewind/flaky_reporter.rb
+- lib/rspec/rewind/flaky_transition.rb
+- lib/rspec/rewind/matcher_validation.rb
+- lib/rspec/rewind/retry_budget.rb
+- lib/rspec/rewind/retry_count_resolver.rb
+- lib/rspec/rewind/retry_decision.rb
+- lib/rspec/rewind/retry_delay_resolver.rb
+- lib/rspec/rewind/retry_event_builder.rb
+- lib/rspec/rewind/retry_gate.rb
+- lib/rspec/rewind/retry_loop.rb
+- lib/rspec/rewind/retry_notifier.rb
+- lib/rspec/rewind/retry_policy.rb
+- lib/rspec/rewind/retry_transition.rb
+- lib/rspec/rewind/runner.rb
+- lib/rspec/rewind/runner_components.rb
+- lib/rspec/rewind/runner_logger.rb
+- lib/rspec/rewind/version.rb
+- rspec-rewind.gemspec
+- sig/rspec/rewind.rbs
+homepage: https://github.com/ydah/rspec-rewind
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ydah/rspec-rewind
+  source_code_uri: https://github.com/ydah/rspec-rewind
+  changelog_uri: https://github.com/ydah/rspec-rewind/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Modern retry orchestration for flaky RSpec examples
+test_files: []