rspec-rewind 0.1.0 → 1.0.0

data/lib/rspec/rewind/retry_event_builder.rb

@@ -3,27 +3,94 @@
 module RSpec
   module Rewind
     class RetryEventBuilder
-      def initialize(example_source:)
+      def initialize(example_source:, metadata_keys: [])
         @example_source = example_source
+        @metadata_keys = Array(metadata_keys).map(&:to_sym)
       end
 
-      def build(status:, retry_reason:, attempt:, retries:, duration:, sleep_seconds:, exception:)
+      def build(
+        status:,
+        retry_reason:,
+        attempt:,
+        retries:,
+        duration:,
+        sleep_seconds:,
+        exception:,
+        decision_reason: nil,
+        total_duration: nil,
+        attempt_durations: nil,
+        first_failure_duration: nil,
+        scheduled_sleep_seconds: sleep_seconds,
+        actual_sleep_seconds: nil,
+        sleep_total: nil,
+        budget_decision: nil,
+        matched_retry_on: nil,
+        matched_skip_retry_on: nil,
+        matcher_error: nil
+      )
         Event.new(
           schema_version: EVENT_SCHEMA_VERSION,
           status: status,
           retry_reason: retry_reason,
-          example_id: @example_source.id,
-          description: @example_source.full_description,
-          location: @example_source.location,
+          decision_reason: decision_reason,
+          example_id: safe_read(:id, 'unknown'),
+          description: safe_read(:full_description, 'unknown'),
+          location: safe_read(:location, 'unknown'),
           attempt: attempt,
           retries: retries,
+          max_attempts: retries.to_i + 1,
           exception_class: exception&.class&.name,
           exception_message: exception&.message,
+          exception_backtrace_top: exception&.backtrace&.first,
+          failure_fingerprint: FailureFingerprint.build(exception),
           duration: duration,
+          total_duration: total_duration,
+          attempt_durations: attempt_durations,
+          first_failure_duration: first_failure_duration,
           sleep_seconds: sleep_seconds,
-          timestamp: Time.now.utc.iso8601
+          scheduled_sleep_seconds: scheduled_sleep_seconds,
+          actual_sleep_seconds: actual_sleep_seconds,
+          sleep_total: sleep_total,
+          timestamp: Time.now.utc.iso8601,
+          budget_limit: read_decision_value(budget_decision, :limit),
+          budget_used: read_decision_value(budget_decision, :used),
+          budget_remaining: read_decision_value(budget_decision, :remaining),
+          matched_retry_on: matched_retry_on,
+          matched_skip_retry_on: matched_skip_retry_on,
+          matcher_error: matcher_error,
+          metadata: filtered_metadata
         )
       end
+
+      private
+
+      def safe_read(method_name, fallback)
+        return fallback unless @example_source.respond_to?(method_name)
+
+        value = @example_source.public_send(method_name)
+        value.nil? ? fallback : value
+      rescue StandardError
+        fallback
+      end
+
+      def filtered_metadata
+        return nil if @metadata_keys.empty?
+        return {} unless @example_source.respond_to?(:metadata)
+
+        metadata = @example_source.metadata || {}
+        @metadata_keys.each_with_object({}) do |key, selected|
+          selected[key] = metadata[key] if metadata.key?(key)
+        end
+      rescue StandardError
+        {}
+      end
+
+      def read_decision_value(decision, field)
+        return nil unless decision
+        return decision.public_send(field) if decision.respond_to?(field)
+
+        nil
+      end
     end
   end
 end

data/lib/rspec/rewind/retry_gate.rb

@@ -2,6 +2,18 @@
 
 module RSpec
   module Rewind
+    RetryGateDecision = Struct.new(
+      :allowed,
+      :reason,
+      :policy_decision,
+      :budget_decision,
+      keyword_init: true
+    ) do
+      def allowed?
+        allowed
+      end
+    end
+
     class RetryGate
       def initialize(configuration:, retry_policy:, debug:)
         @configuration = configuration
@@ -16,25 +28,107 @@ module RSpec
         retry_on:,
         skip_retry_on:,
         retry_if:,
-        example_id:
+        example_id:,
+        elapsed_time: nil,
+        sleep_total: nil
       )
-        return false unless retry_number <= resolved_retries
+        decision(
+          exception: exception,
+          retry_number: retry_number,
+          resolved_retries: resolved_retries,
+          retry_on: retry_on,
+          skip_retry_on: skip_retry_on,
+          retry_if: retry_if,
+          example_id: example_id,
+          elapsed_time: elapsed_time,
+          sleep_total: sleep_total
+        ).allowed?
+      end
 
-        return false unless @retry_policy.retry_allowed?(
+      def decision(
+        exception:,
+        retry_number:,
+        resolved_retries:,
+        retry_on:,
+        skip_retry_on:,
+        retry_if:,
+        example_id:,
+        elapsed_time: nil,
+        sleep_total: nil
+      )
+        return rejected(:retries_exhausted) unless retry_number <= resolved_retries
+        return rejected(:max_elapsed_time_exceeded) if exceeded?(@configuration.max_elapsed_time, elapsed_time)
+        return rejected(:max_total_sleep_exceeded) if exceeded?(@configuration.max_total_sleep, sleep_total)
+
+        policy_decision = @retry_policy.decision(
           exception: exception,
           retry_on: retry_on,
           skip_retry_on: skip_retry_on,
-          retry_if: retry_if
+          retry_if: retry_if,
+          retry_number: retry_number,
+          resolved_retries: resolved_retries,
+          budget_remaining: budget_remaining,
+          elapsed_time: elapsed_time,
+          sleep_total: sleep_total
         )
+        return rejected(policy_decision.reason, policy_decision: policy_decision) unless policy_decision.allowed?
 
-        return true if @configuration.retry_budget.consume!
+        return rejected(:dry_run, policy_decision: policy_decision) if @configuration.dry_run
+
+        budget_decision = consume_budget
+        return allowed(policy_decision: policy_decision, budget_decision: budget_decision) if budget_decision.allowed?
 
         debug("retry budget exhausted for #{example_id}")
-        false
+        rejected(:budget_exhausted, policy_decision: policy_decision, budget_decision: budget_decision)
       end
 
       private
 
+      def allowed(policy_decision: nil, budget_decision: nil)
+        RetryGateDecision.new(
+          allowed: true,
+          reason: :allowed,
+          policy_decision: policy_decision,
+          budget_decision: budget_decision
+        )
+      end
+
+      def rejected(reason, policy_decision: nil, budget_decision: nil)
+        RetryGateDecision.new(
+          allowed: false,
+          reason: reason,
+          policy_decision: policy_decision,
+          budget_decision: budget_decision
+        )
+      end
+
+      def consume_budget
+        budget = @configuration.retry_budget
+        return budget.consume if budget.respond_to?(:consume)
+
+        allowed = budget.consume!
+        BudgetDecision.new(
+          allowed: allowed,
+          limit: read_budget_value(budget, :limit),
+          used: read_budget_value(budget, :used),
+          remaining: read_budget_value(budget, :remaining)
+        )
+      end
+
+      def budget_remaining
+        read_budget_value(@configuration.retry_budget, :remaining)
+      end
+
+      def read_budget_value(budget, field)
+        return budget.public_send(field) if budget.respond_to?(field)
+
+        nil
+      end
+
+      def exceeded?(limit, value)
+        !limit.nil? && !value.nil? && value >= limit
+      end
+
       def debug(message)
         @debug.call(message)
       end

data/lib/rspec/rewind/retry_loop.rb

@@ -10,7 +10,8 @@ module RSpec
         attempt_runner:,
         retry_gate:,
         retry_transition:,
-        flaky_transition:
+        flaky_transition:,
+        clock: nil
       )
         @example = example
         @context = context
@@ -19,6 +20,7 @@ module RSpec
         @retry_gate = retry_gate
         @retry_transition = retry_transition
         @flaky_transition = flaky_transition
+        @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
       end
 
       def run(retries:, backoff:, wait:, retry_on:, skip_retry_on:, retry_if:)
@@ -27,46 +29,91 @@ module RSpec
 
         total_attempts = resolved_retries + 1
         attempt = 1
+        first_exception = nil
+        first_failure_duration = nil
+        attempt_durations = []
+        sleep_total = 0.0
+        started_at = monotonic_time
 
         while attempt <= total_attempts
           exception, duration, raised = @attempt_runner.run(
             run_target: @example,
             exception_source: @context.source
           )
+          attempt_durations << duration
 
           if exception.nil?
-            @flaky_transition.perform(attempt: attempt, retries: resolved_retries, duration: duration) if attempt > 1
+            if attempt > 1
+              @flaky_transition.perform(
+                attempt: attempt,
+                retries: resolved_retries,
+                duration: duration,
+                exception: first_exception,
+                total_duration: monotonic_time - started_at,
+                attempt_durations: attempt_durations.dup,
+                first_failure_duration: first_failure_duration,
+                sleep_total: sleep_total
+              )
+            end
             return
           end
 
+          first_exception ||= exception
+          first_failure_duration ||= duration
           retry_number = attempt
-          unless @retry_gate.allow?(
+          decision = @retry_gate.decision(
             exception: exception,
             retry_number: retry_number,
             resolved_retries: resolved_retries,
             retry_on: retry_on,
             skip_retry_on: skip_retry_on,
             retry_if: retry_if,
-            example_id: @context.id
+            example_id: @context.id,
+            elapsed_time: monotonic_time - started_at,
+            sleep_total: sleep_total
           )
+          unless decision.allowed?
+            @retry_transition.publish_not_retried(
+              retry_number: retry_number,
+              resolved_retries: resolved_retries,
+              duration: duration,
+              exception: exception,
+              decision: decision,
+              total_duration: monotonic_time - started_at,
+              attempt_durations: attempt_durations.dup,
+              sleep_total: sleep_total
+            )
             raise exception if raised
 
             return
           end
 
-          @retry_transition.perform(
+          sleep_measurement = @retry_transition.perform(
             retry_number: retry_number,
             resolved_retries: resolved_retries,
             duration: duration,
             exception: exception,
             backoff: backoff,
             wait: wait,
-            example_source: @context.source
+            example_source: @context.source,
+            total_duration: monotonic_time - started_at,
+            attempt_durations: attempt_durations.dup,
+            sleep_total: sleep_total,
+            failure_fingerprint: FailureFingerprint.build(exception),
+            budget_decision: decision.budget_decision,
+            policy_decision: decision.policy_decision
           )
+          sleep_total += sleep_measurement.actual
 
           attempt += 1
         end
       end
+
+      private
+
+      def monotonic_time
+        @clock.call
+      end
     end
   end
 end

data/lib/rspec/rewind/retry_notifier.rb

@@ -11,32 +11,79 @@ module RSpec
 
       def notify_retry(event)
         debug("retry #{event.attempt}/#{event.retries} for #{event.example_id} in #{event.sleep_seconds.round(3)}s")
-        @configuration.retry_callback&.call(event)
-      rescue StandardError => e
-        debug("retry callback failed: #{e.class}: #{e.message}")
+        record_summary(event)
+        publish_retry_report(event) if @configuration.report_retry_events
+        invoke_callback(@configuration.retry_callback, event, 'retry callback')
+      end
+
+      def notify_before_retry(event)
+        invoke_callback(@configuration.before_retry, event, 'before_retry hook')
+      end
+
+      def notify_after_retry(event)
+        invoke_callback(@configuration.after_retry, event, 'after_retry hook')
+      end
+
+      def publish_not_retried(event)
+        debug("not retrying #{event.example_id}: #{event.decision_reason}")
+        record_summary(event)
+        publish_retry_report(event) if @configuration.report_retry_events
+        invoke_callback(@configuration.not_retried_callback, event, 'not_retried callback')
+      end
+
+      def publish_reset_failed(event)
+        debug("state reset failed for #{event.example_id}: #{event.exception_class}: #{event.exception_message}")
+        record_summary(event)
+        publish_retry_report(event) if @configuration.report_retry_events
       end
 
       def publish_flaky(event)
+        record_summary(event)
         publish_flaky_report(event)
-        invoke_flaky_callback(event)
+        invoke_callback(@configuration.flaky_callback, event, 'flaky callback')
       end
 
       def show_failure_message(exception)
-        @reporter_message.call("[rspec-rewind] #{exception.class}: #{exception.message}")
+        message = "[rspec-rewind] #{exception.class}: #{exception.message}"
+        if @configuration.display_retry_backtrace_top && exception.backtrace&.first
+          message = "#{message} (#{exception.backtrace.first})"
+        end
+
+        @reporter_message.call(message)
       end
 
       private
 
+      def publish_retry_report(event)
+        @configuration.flaky_reporter.record(event)
+      rescue StandardError => e
+        raise if @configuration.strict_callbacks
+
+        debug("failed to record retry event: #{e.class}: #{e.message}")
+      end
+
+      def record_summary(event)
+        @configuration.retry_summary.record(event)
+      rescue StandardError => e
+        raise if @configuration.strict_callbacks
+
+        debug("failed to record retry summary: #{e.class}: #{e.message}")
+      end
+
       def publish_flaky_report(event)
         @configuration.flaky_reporter.record(event)
       rescue StandardError => e
+        raise if @configuration.strict_callbacks
+
         debug("failed to record flaky event: #{e.class}: #{e.message}")
       end
 
-      def invoke_flaky_callback(event)
-        @configuration.flaky_callback&.call(event)
+      def invoke_callback(callback, event, label)
+        callback&.call(event)
       rescue StandardError => e
-        debug("flaky callback failed: #{e.class}: #{e.message}")
+        raise if @configuration.strict_callbacks
+
+        debug("#{label} failed: #{e.class}: #{e.message}")
       end
 
       def debug(message)

data/lib/rspec/rewind/retry_policy.rb

@@ -12,40 +12,168 @@ module RSpec
       end
 
       def retry_allowed?(exception:, retry_on:, skip_retry_on:, retry_if:)
+        decision(
+          exception: exception,
+          retry_on: retry_on,
+          skip_retry_on: skip_retry_on,
+          retry_if: retry_if
+        ).allowed?
+      end
+
+      def decision(
+        exception:,
+        retry_on:,
+        skip_retry_on:,
+        retry_if:,
+        retry_number: nil,
+        resolved_retries: nil,
+        budget_remaining: nil,
+        elapsed_time: nil,
+        sleep_total: nil
+      )
         RetryDecision.new(
           exception: exception,
           example: @example,
           retry_on: effective_retry_on(retry_on),
           skip_retry_on: effective_skip_retry_on(skip_retry_on),
-          retry_if: effective_retry_if(retry_if)
-        ).retry?
+          retry_if: effective_retry_if(retry_if),
+          retry_on_default: @configuration.retry_on_default,
+          strict_callable_arity: @configuration.strict_callable_arity,
+          context: retry_context(
+            retry_number: retry_number,
+            resolved_retries: resolved_retries,
+            budget_remaining: budget_remaining,
+            elapsed_time: elapsed_time,
+            sleep_total: sleep_total,
+            exception: exception
+          )
+        ).decision
       end
 
       private
 
       def effective_retry_on(explicit_retry_on)
-        normalize_matchers(@configuration.retry_on, field: 'retry_on') +
-          normalize_matchers(@metadata[:rewind_retry_on], field: 'rewind_retry_on') +
-          normalize_matchers(explicit_retry_on, field: 'retry_on')
+        if retry_on_mode == :override
+          return normalize_policy_matchers(@metadata[:rewind_retry_on], field: 'rewind_retry_on') +
+                 normalize_policy_matchers(explicit_retry_on, field: 'retry_on')
+        end
+
+        normalize_policy_matchers(@configuration.retry_on, field: 'retry_on') +
+          normalize_policy_matchers(@metadata[:rewind_retry_on], field: 'rewind_retry_on') +
+          normalize_policy_matchers(explicit_retry_on, field: 'retry_on')
       end
 
       def effective_skip_retry_on(explicit_skip_retry_on)
-        normalize_matchers(@configuration.skip_retry_on, field: 'skip_retry_on') +
-          normalize_matchers(metadata_skip_retry_on, field: 'rewind_skip_retry_on') +
-          normalize_matchers(explicit_skip_retry_on, field: 'skip_retry_on')
+        if skip_retry_on_mode == :override
+          return normalize_policy_matchers(metadata_skip_retry_on, field: 'rewind_skip_retry_on') +
+                 normalize_policy_matchers(explicit_skip_retry_on, field: 'skip_retry_on')
+        end
+
+        normalize_policy_matchers(@configuration.skip_retry_on, field: 'skip_retry_on') +
+          normalize_policy_matchers(metadata_skip_retry_on, field: 'rewind_skip_retry_on') +
+          normalize_policy_matchers(explicit_skip_retry_on, field: 'skip_retry_on')
       end
 
       def effective_retry_if(explicit_retry_if)
-        first_non_nil(explicit_retry_if, @metadata[:rewind_if], @configuration.retry_if)
+        predicates = [@configuration.retry_if, @metadata[:rewind_if], explicit_retry_if].compact
+        predicates.each { |predicate| validate_callable!(predicate, field: 'retry_if') }
+
+        case retry_if_mode
+        when :and
+          return nil if predicates.empty?
+
+          ->(*args) { predicates.all? { |predicate| call_predicate(predicate, args) } }
+        when :or
+          return nil if predicates.empty?
+
+          ->(*args) { predicates.any? { |predicate| call_predicate(predicate, args) } }
+        else
+          first_non_nil(explicit_retry_if, @metadata[:rewind_if], @configuration.retry_if)
+        end
       end
 
       def metadata_skip_retry_on
         @metadata[:rewind_skip_retry_on]
       end
 
+      def normalize_policy_matchers(values, field:)
+        normalize_matchers(
+          values,
+          field: field,
+          strict_exception_matchers: @configuration.strict_matcher_validation
+        )
+      end
+
+      def retry_if_mode
+        normalize_mode(
+          @metadata[:rewind_if_mode],
+          allowed: %i[override and or],
+          fallback: @configuration.retry_if_mode,
+          field: 'rewind_if_mode'
+        )
+      end
+
+      def retry_on_mode
+        normalize_mode(
+          @metadata[:rewind_retry_on_mode],
+          allowed: %i[append override],
+          fallback: :append,
+          field: 'rewind_retry_on_mode'
+        )
+      end
+
+      def skip_retry_on_mode
+        normalize_mode(
+          @metadata[:rewind_skip_retry_on_mode],
+          allowed: %i[append override],
+          fallback: :append,
+          field: 'rewind_skip_retry_on_mode'
+        )
+      end
+
+      def retry_context(retry_number:, resolved_retries:, budget_remaining:, elapsed_time:, sleep_total:, exception:)
+        RetryContext.new(
+          attempt: retry_number,
+          retries: resolved_retries,
+          metadata: @metadata,
+          budget_remaining: budget_remaining,
+          failure_fingerprint: FailureFingerprint.build(exception),
+          elapsed_time: elapsed_time,
+          sleep_total: sleep_total
+        )
+      end
+
+      def validate_callable!(callable, field:)
+        return if callable.respond_to?(:call)
+
+        raise ArgumentError, "#{field} must be callable"
+      end
+
+      def call_predicate(predicate, args)
+        arity = predicate.respond_to?(:arity) ? predicate.arity : predicate.method(:call).arity
+        return predicate.call if arity.zero?
+
+        if arity.positive?
+          predicate.call(*args.take(arity))
+        else
+          predicate.call(*args)
+        end
+      end
+
       def first_non_nil(*values)
         values.find { |value| !value.nil? }
       end
+
+      def normalize_mode(value, allowed:, fallback:, field:)
+        return fallback.to_sym if value.nil?
+
+        mode = value.to_sym
+        return mode if allowed.include?(mode)
+
+        raise ArgumentError, "#{field} must be one of: #{allowed.join(', ')}"
+      rescue NoMethodError
+        raise ArgumentError, "#{field} must be one of: #{allowed.join(', ')}"
+      end
     end
   end
 end

data/lib/rspec/rewind/retry_summary.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rewind
+    class FlakyThresholdExceeded < StandardError; end
+
+    class RetrySummary
+      attr_reader :retry_events, :flaky_examples, :not_retried_events, :reset_failed_events, :sleep_seconds
+
+      def initialize
+        reset!
+      end
+
+      def record(event)
+        @mutex.synchronize do
+          case event.status
+          when :retrying
+            @retry_events += 1
+            @sleep_seconds += event.actual_sleep_seconds.to_f
+          when :flaky
+            @flaky_examples += 1
+          when :not_retried
+            @not_retried_events += 1
+          when :reset_failed
+            @reset_failed_events += 1
+          end
+        end
+      end
+
+      def reset!
+        @mutex = Mutex.new
+        @retry_events = 0
+        @flaky_examples = 0
+        @not_retried_events = 0
+        @reset_failed_events = 0
+        @sleep_seconds = 0.0
+      end
+
+      def to_message(budget:)
+        parts = [
+          "#{@flaky_examples} flaky examples",
+          "#{@retry_events} retry attempts",
+          "#{format('%.3f', @sleep_seconds)}s spent sleeping",
+          "#{@not_retried_events} not retried",
+          "#{@reset_failed_events} reset failures"
+        ]
+        parts << budget_message(budget)
+        "[rspec-rewind] #{parts.compact.join(', ')}"
+      end
+
+      private
+
+      def budget_message(budget)
+        return nil unless budget.respond_to?(:used)
+
+        limit = budget.respond_to?(:limit) ? budget.limit : nil
+        limit.nil? ? "budget #{budget.used}/unlimited used" : "budget #{budget.used}/#{limit} used"
+      end
+    end
+  end
+end