block_repeater 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e3926f813063452596a76a2849a30a37d0ca1c16e59061cf2bde4e33f930a7a
-  data.tar.gz: cb16a69e2a7ca8302d1d45fd2278c6dbe4d405b88efb95df3acc2806fe109287
+  metadata.gz: ea41f6457e3cf7aa83b6e1f5989f2a92b24174ebb6d12f48b564033661af1477
+  data.tar.gz: 7df266b49f3b8c32aff6a8d2826d18864b5d1885f41e3888ce80896bb715f73a
 SHA512:
-  metadata.gz: 46b55edc17c35928ae37d40b41d07830dcdfcaef3c42859b12ff69e7acdf5b229dd43e4c80512a0c3129b66085189139cbadf364238f176e62b0a66e3e28b7ea
-  data.tar.gz: c3d24fdc65de04ca0a75432dd74dfe2e6fc5cdacbd4b9e7a309b83721cce9569458114ccac7cc5f342bb456768e4734cc7c2742d554b63f42ff350e62d063a32
+  metadata.gz: 75426f7a71bd028729e26a82424e142a9ffa40c2d88cc8704bf95f22051ddd2fc4c2677896d30d690d6c819a17c2e81d89013ff681d1511c224d56bb92eefd53
+  data.tar.gz: 414d3d2a92040b4e143d1fc4103f82ddb403fa9e154f0d2a688ef303b4b444c465d787260646bd0e875c41466484c7338c03941cadad06ba966289a33481998d

data/Gemfile

@@ -5,5 +5,5 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in block_repeater.gemspec
 gemspec
 
-gem 'rake', '~> 12.0'
+gem 'rake', '~> 13.0'
 gem 'rubocop', '~> 1.50.0'

data/Gemfile.lock

@@ -1,40 +1,43 @@
 PATH
   remote: .
   specs:
-    block_repeater (1.1.0)
+    block_repeater (1.2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.2)
+    ast (2.4.3)
     bump (0.10.0)
     coderay (1.1.3)
-    diff-lcs (1.4.4)
-    json (2.6.3)
-    method_source (1.0.0)
-    parallel (1.23.0)
-    parser (3.2.2.1)
+    diff-lcs (1.6.2)
+    json (2.21.1)
+    method_source (1.1.0)
+    ostruct (0.6.3)
+    parallel (1.28.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
-    pry (0.14.1)
+      racc
+    pry (0.14.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (12.3.3)
-    regexp_parser (2.8.0)
-    rexml (3.2.5)
-    rspec (3.10.0)
-      rspec-core (~> 3.10.0)
-      rspec-expectations (~> 3.10.0)
-      rspec-mocks (~> 3.10.0)
-    rspec-core (3.10.1)
-      rspec-support (~> 3.10.0)
-    rspec-expectations (3.10.1)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
+    rexml (3.4.4)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-mocks (3.10.2)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-support (3.10.2)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
     rubocop (1.50.2)
       json (~> 2.3)
       parallel (~> 1.10)
@@ -56,9 +59,10 @@ PLATFORMS
 DEPENDENCIES
   block_repeater!
   bump (~> 0.6)
-  bundler (~> 2.4.0)
+  bundler (>= 2.4)
+  ostruct
   pry
-  rake (~> 12.0)
+  rake (~> 13.0)
   rspec (~> 3.8)
   rubocop (~> 1.50.0)
 

data/README.md

@@ -98,13 +98,13 @@ You can also define default exception handling behaviour which all repeaters in
 ```ruby
 BlockRepeater::Repeater.default_catch(exceptions: [IOError], behaviour: :defer) do |e|
   puts 'An IOError occurred'
-  e.raise
+  raise e
 end
 ```
 A common use-case for default exception handling is if using a gem such as RSpec, where you may want to handle failed expectations in a uniform manner. To do so you need define the default behaviour first, in a place such as a `env.rb` file or similar:
 ```ruby
 BlockRepeater::Repeater.default_catch(exceptions: [RSpec::Expectations::ExpectationNotMetError], behaviour: :defer) do |e|
-  e.raise
+  raise e
 end
 ```
 Then an RSpec expectation can be used in the block for the `until` method. The expectation will be attempted each try, but the exception will only be raised if it has still failed once the number or attempts has been reached.
@@ -115,6 +115,43 @@ Then an RSpec expectation can be used in the block for the `until` method. The e
     expect(result.count).to be_positive, raise 'No result returned from databased'
   end
 ```
+### Replay method
+The `replay` method provides a retry-with-refresh mechanism for UI actions that may fail due to transient errors. It is designed for use with browser automation tools like Capybara.
+
+```ruby
+replay(exceptions: [Capybara::ElementNotFound], refresh: -> { page.refresh }) do
+  find('#submit-button').click
+end
+```
+
+`replay` takes five parameters:
+- `times:` maximum retry attempts (defaults to 3)
+- `delay:` seconds between retries (defaults to 0.5)
+- `exceptions:` array of exception types to catch and retry on (defaults to [])
+- `refresh:` a callable (Proc/lambda) to execute between retries for page refresh (defaults to nil)
+- `logger:` any object responding to `#error` for error messages, or nil to silence logging (defaults to nil)
+
+The block is executed and if a configured exception is raised, the error is logged, the refresh callable is invoked (if provided), and the block is retried. If the exception persists after all attempts, it is re-raised. The refresh is not called on the final attempt.
+
+A typical setup with Capybara and locale handling:
+```ruby
+UI_ERRORS = [Capybara::ElementNotFound, Selenium::WebDriver::Error::ElementClickInterceptedError]
+
+replay(exceptions: UI_ERRORS, refresh: -> { visit("#{current_path}?locale=#{I18n.locale}") }) do
+  click_link_or_button('Continue')
+end
+```
+
+To use a custom logger:
+```ruby
+replay(exceptions: UI_ERRORS, logger: Rails.logger) { perform_action }
+```
+
+To silence logging:
+```ruby
+replay(exceptions: UI_ERRORS, logger: nil) { perform_action }
+```
+
 ### Non predefined condition methods
 Very simple conditions can be utilised without using a block. This expects either one or two method names which will be called against the result of repeating the main block.
 The required format is `until_<method name>` or `until_<method name>_becomes_<method name>`.

data/block_repeater.gemspec

@@ -27,9 +27,10 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_development_dependency 'bump', '~> 0.6'
-  spec.add_development_dependency 'bundler', '~> 2.4.0'
+  spec.add_development_dependency 'bundler', '>= 2.4'
+  spec.add_development_dependency 'ostruct'
   spec.add_development_dependency 'pry'
-  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.8'
   spec.add_development_dependency 'rubocop'
 end

data/lib/block_repeater/replay.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module BlockRepeater
+  ##
+  # Provides a retry-with-refresh mechanism for UI actions
+  # that may fail due to transient driver/page errors.
+  #
+  # Consumers configure which exceptions to catch and how to refresh the page.
+  module Replay
+    ##
+    # Execute a block, retrying on configured exceptions with optional page refresh.
+    #
+    # @param exceptions [Array<Class>] Exception types to catch and retry on
+    # @param times [Integer] Maximum retry attempts (default: 3)
+    # @param delay [Float] Seconds between retries (default: 0.5)
+    # @param refresh [Proc, nil] Callable to execute between retries for page refresh (default: nil)
+    # @param logger [#error, nil] Logger for error messages; nil to silence (default: nil)
+    # @param &block - The block of code to retry
+    # @return The result of the block
+    def replay(exceptions:, times: 3, delay: 0.5, refresh: nil, logger: nil, &block)
+      raise ArgumentError, 'replay requires a block' unless block
+
+      attempt = 0
+
+      repeat(times: times, delay: delay, &block).catch(exceptions: exceptions, behaviour: :continue) do |e|
+        attempt += 1
+        logger&.error { e.message }
+        raise(e) if attempt >= times
+
+        refresh&.call
+      end.until do |result|
+        !result.is_a?(Exception)
+      end
+    end
+  end
+end

data/lib/block_repeater/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BlockRepeater
-  VERSION = '1.1.0'
+  VERSION = '1.2.0'
 end

data/lib/block_repeater.rb

@@ -2,6 +2,7 @@
 
 require 'block_repeater/version'
 require 'block_repeater/repeatable'
+require 'block_repeater/replay'
 require 'block_repeater/repeater'
 
 ##
@@ -11,4 +12,5 @@ require 'block_repeater/repeater'
 #
 module BlockRepeater
   include Repeatable
+  include Replay
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: block_repeater
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - William Bray
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-08-16 00:00:00.000000000 Z
+date: 2026-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bump
@@ -28,16 +28,30 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 2.4.0
+        version: '2.4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 2.4.0
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -58,14 +72,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -119,6 +133,7 @@ files:
 - lib/block_repeater/repeatable.rb
 - lib/block_repeater/repeater.rb
 - lib/block_repeater/repeater_methods.rb
+- lib/block_repeater/replay.rb
 - lib/block_repeater/version.rb
 homepage: https://github.com/dvla/block-repeater
 licenses:
@@ -126,7 +141,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/dvla/block-repeater
   source_code_uri: https://github.com/dvla/block-repeater
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -142,7 +157,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.2.15
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Conditionally repeat a block of code
 test_files: []