patiently 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f738cd510ed2b9ff9b43ba29a3a72201f3c6a85332ff47af71f171bd7478d3ac
+  data.tar.gz: 6d5d64fbe90a9b14be3bc00480d53e79823441d4b194c14adcac7cc75ef5266b
+SHA512:
+  metadata.gz: 2c85cbcda0754060cd80be043067a61fe21b8a4cd70a27722f3ddb433bb82cb7d96e158e0d273ce3c30aa96ddc0fc89fbae86ba1999a468c0e088093f26d753b
+  data.tar.gz: fe576c8eb91123d2c6de6b5dd1519ab0f3cdaa2fc3607bbe0899482ccf0fbb5aa5ad0b0e4da3e1657c6f118546a318f48774afa68c6d9c9ddf65d7f7bfac1b5f

data/.github/workflows/test.yml

@@ -0,0 +1,35 @@
+---
+name: Tests
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+    branches:
+    - main
+  workflow_dispatch: {}
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    continue-on-error: "${{ matrix.experimental || false }}"
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+        - "2.7"
+        - "3.0"
+        - "3.2"
+        - "3.4"
+        include:
+        - ruby: "head"
+          experimental: true
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: "${{ matrix.ruby }}"
+        bundler-cache: true
+    - name: Run tests
+      run: bundle exec rake spec

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.idea
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+2.7.8

data/AGENTS.md

@@ -0,0 +1,67 @@
+# AGENTS.md
+
+Conventions for working on the `patiently` gem. Read this before changing code,
+dependencies, or CI.
+
+## What this gem is
+
+`patiently` retries a block until it stops raising (`patiently`) or returns
+truthy (`patiently_until`, alias `patiently_wait_until`). It was extracted from a
+`spec/support/patiently.rb` helper that used to be copy-pasted into many test
+suites.
+
+## Hard rules
+
+- **No runtime dependencies.** Do not add RSpec, Capybara, Rails or
+  ActiveSupport as a runtime dependency. The gem must work in any Ruby project.
+  RSpec/Capybara are dev-only (for the self-tests).
+- **Ruby >= 2.7.** Keep the code compatible with 2.7 syntax. `required_ruby_version`
+  in the gemspec is the source of truth.
+- **Ask before committing** (repo-wide preference).
+
+## Ruby versions & the lockfile
+
+- `.ruby-version` pins **2.7.8** (our support floor). Locally you can use any
+  Ruby (`rbenv shell 2.7.8`, or just your default 3.x) — both are expected to pass.
+- CI (`.github/workflows/test.yml`) runs a **matrix** across 2.7 / 3.0 / 3.2 / 3.4
+  and `head`. We do NOT use gemika/appraisals — one `Gemfile`, one `Gemfile.lock`.
+- `Gemfile.lock` **is committed** and was generated under **Ruby 2.7.8 with
+  bundler 2.1.4** so `BUNDLED WITH` stays readable on every matrix Ruby. If you
+  change dependencies, regenerate the lock under the oldest supported Ruby:
+  `RBENV_VERSION=2.7.8 bundle _2.1.4_ install` — otherwise a newer bundler pin
+  breaks the 2.7 CI job.
+
+## Running tests
+
+```bash
+bundle exec rspec        # or: bundle exec rake spec  (the CI entrypoint)
+```
+
+Testing notes:
+- Time-freeze detection is tested by **stubbing the private `monotonic_time`**
+  helper, not by mocking `Time`/`Process.clock_gettime` globally.
+- Some examples wait **real** (sub-second) time on purpose; that is acceptable
+  here. Keep any real waits well under a second and stub `sleep` where timing
+  isn't the thing under test.
+- Keep the suite dependency-light: no embedded Rails app, no nested RSpec runs.
+
+## Public API & semantics (don't break without a version bump)
+
+- Mix in with `include Patiently::Helpers`.
+- Config lives on `Patiently.config` (`timeout`, `retry_intervals`,
+  `min_retries`, `max_retries`) or `Patiently.configure { |c| ... }`.
+- `min_retries` / `max_retries` count **re-attempts** (invocations after the
+  first). `min_retries = 1` reproduces the original "try at least twice"
+  behavior. `max_retries = nil` means unlimited.
+- `retry_intervals` is a backoff array; the last element is reused once exhausted.
+- Errors: `Patiently::Error` (base) and `Patiently::FrozenInTime`. Do NOT reach
+  for Capybara's error classes.
+- Optional RSpec glue is `require "patiently/rspec"` — keep it a thin
+  `config.include(Patiently::Helpers, type: :feature)` and nothing more.
+
+## Packaging (house style, mirrors capybara-lockstep)
+
+The gemspec ships **every tracked file except `spec/`, `test/`, `features/`** —
+so `Gemfile`, `Gemfile.lock`, `.github/`, the gemspec and `bin/` are included in
+the published `.gem` on purpose. `.gitignore` keeps IDE/build cruft (`.idea`,
+`tmp/`, `pkg/`, `.rspec_status`) out of git and therefore out of the gem.

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+### Added
+
+- Initial extraction of the `patiently` / `patiently_until` test helpers into a
+  standalone, dependency-free gem.
+- `include Patiently::Helpers` to gain the `patiently` and `patiently_until`
+  helpers (`patiently_wait_until` is kept as an alias).
+- Configurable defaults via `Patiently.config`: `timeout`, `retry_intervals`
+  (with backoff), `min_retries` and `max_retries`.
+- Per-call timeout argument for both `patiently` and `patiently_until`.
+- `Patiently::FrozenInTime` error raised when the monotonic clock does not
+  advance between retries (mocked/frozen time).
+- Optional RSpec integration via `require "patiently/rspec"`.

data/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in patiently.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"

data/Gemfile.lock

@@ -0,0 +1,34 @@
+PATH
+  remote: .
+  specs:
+    patiently (1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.6.2)
+    rake (13.4.2)
+    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.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  patiently!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   2.1.4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Henning Koch
+
+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,187 @@
+<p>
+  <a href="https://makandra.de/">
+    <picture>
+      <source media="(prefers-color-scheme: light)" srcset="media/makandra-with-bottom-margin.light.svg">
+      <source media="(prefers-color-scheme: dark)" srcset="media/makandra-with-bottom-margin.dark.svg">
+      <img align="right" width="25%" alt="makandra" src="media/makandra-with-bottom-margin.light.svg">
+    </picture>
+  </a>
+
+  <picture>
+    <source media="(prefers-color-scheme: light)" srcset="media/logo.light.shapes.svg">
+    <source media="(prefers-color-scheme: dark)" srcset="media/logo.dark.shapes.svg">
+    <img width="200" alt="patiently" role="heading" aria-level="1" src="media/logo.light.shapes.svg">
+  </picture>
+</p>
+
+`patiently` retries a block of code until it stops raising an exception (or
+returns a truthy value). It is most useful in tests that need to wait for an
+eventually-consistent condition — a background job to finish, an AJAX request to
+update the DOM, a file to appear — without sprinkling `sleep` calls everywhere.
+
+It has **no runtime dependencies**: it does not require RSpec, Capybara, Rails or
+ActiveSupport.
+
+## Installation
+
+Add it to your `Gemfile` and run `bundle install`:
+
+```ruby
+gem "patiently"
+```
+
+Patiently does not depend on RSpec, but if you use it, wire the helpers into your
+specs. Either require the bundled integration, which includes the helpers into
+feature and system specs:
+
+```ruby
+# spec/spec_helper.rb (or rails_helper.rb)
+require "patiently/rspec"
+```
+
+or include the helpers yourself with whatever scope you like:
+
+```ruby
+RSpec.configure do |config|
+  config.include(Patiently::Helpers, type: :feature)
+  config.include(Patiently::Helpers, type: :system)
+end
+```
+
+## Usage
+
+Mix the helpers into any class:
+
+```ruby
+include Patiently::Helpers
+```
+
+This gives you two methods.
+
+### `patiently`
+
+Runs the block and, if it raises, keeps retrying until it succeeds or the
+patience window is exhausted. On success it returns the block's value; on failure
+it re-raises the block's last exception.
+
+```ruby
+patiently do
+  expect(page).to have_content("Saved!")
+end
+```
+
+`patiently` retries on **any** exception (including non-`StandardError`s such as
+RSpec's `ExpectationNotMetError`), which is what makes it work with test
+assertions.
+
+You can pass a custom timeout (in seconds) as the first argument, overriding the
+global default:
+
+```ruby
+patiently(10) do
+  expect(page).to have_content("Slow import finished")
+end
+```
+
+### `patiently_until`
+
+Retries the block until it returns a truthy value, then returns `true`. If the
+block is still falsey when the window elapses, it returns `false`. A *real*
+exception raised inside the block still propagates.
+
+```ruby
+patiently_until { user.reload.confirmed? } # => true / false
+```
+
+This is handy for building custom matchers that retry internally while keeping
+their own failure message. It also accepts a custom timeout:
+
+```ruby
+patiently_until(10) { import.reload.done? }
+```
+
+`patiently_wait_until` is available as an alias for `patiently_until`.
+
+### Nested blocks
+
+When you call `patiently` (or `patiently_until`) while already inside a
+`patiently` block on the same thread, the inner block simply runs once — only the
+**outermost** block is retried. This prevents an inner retry loop from repeatedly
+re-running expensive setup and lets the outer block drive the timing.
+
+## Configuration
+
+Configure global defaults via `Patiently.config`:
+
+```ruby
+Patiently.config.timeout = 5              # seconds before giving up
+Patiently.config.retry_intervals = [0.05] # sleep durations between retries
+Patiently.config.min_retries = 1          # always retry at least this often
+Patiently.config.max_retries = nil        # cap on retries (nil = unlimited)
+```
+
+Or use a block:
+
+```ruby
+Patiently.configure do |config|
+  config.timeout = 10
+end
+```
+
+| Option            | Default  | Meaning |
+| ----------------- | -------- | ------- |
+| `timeout`         | `5`      | How long (in seconds) to keep retrying before giving up. |
+| `retry_intervals` | `[0.05]` | Sleep durations (seconds) between retries. See "Backoff" below. |
+| `min_retries`     | `1`      | The minimum number of *retries* performed before giving up, even if the timeout has already elapsed. |
+| `max_retries`     | `nil`    | The maximum number of *retries* before giving up, regardless of the timeout. `nil` means unlimited. |
+
+Both `min_retries` and `max_retries` count **retries** — re-invocations *after*
+the first call. So `min_retries = 1` means the block runs at least twice before
+`patiently` is allowed to give up.
+
+`patiently` gives up (and re-raises the block's exception) when either:
+
+- the timeout has elapsed **and** at least `min_retries` retries have happened, or
+- `max_retries` retries have happened (when `max_retries` is set).
+
+### Backoff
+
+`retry_intervals` may be an array, used as a backoff schedule. The value at index
+N is the sleep before the (N+1)-th retry; once the array is exhausted, its last
+element is reused for all further retries:
+
+```ruby
+Patiently.config.retry_intervals = [0.05, 0.05, 0.05, 0.1]
+# sleeps 0.05, 0.05, 0.05, then 0.1, 0.1, 0.1, ...
+```
+
+## Frozen time detection
+
+If the monotonic clock does not advance between retries — which usually means time
+has been mocked or frozen (Timecop, Rails' `travel`/`freeze_time`, …) —
+`patiently` would loop forever. Instead it raises `Patiently::FrozenInTime` so you
+notice and travel time explicitly.
+
+## Errors
+
+- `Patiently::Error` — base class for all errors raised by this gem.
+- `Patiently::FrozenInTime` — raised when time appears to be frozen (see above).
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies, then run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt.
+
+To release a new version, update the version number in
+`lib/patiently/version.rb`, then run `bundle exec rake release`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/makandra/patiently.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "patiently"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/patiently/configuration.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Patiently
+  # Holds the global defaults for {Patiently::Helpers#patiently}. Access the
+  # shared instance via +Patiently.config+.
+  class Configuration
+    DEFAULT_TIMEOUT = 5
+    DEFAULT_RETRY_INTERVALS = [0.05].freeze
+    DEFAULT_MIN_RETRIES = 1
+    DEFAULT_MAX_RETRIES = nil # nil = unlimited
+
+    attr_writer :timeout, :retry_intervals, :min_retries, :max_retries
+
+    def initialize
+      reset!
+    end
+
+    # How long (in seconds) `patiently` keeps retrying before giving up.
+    def timeout
+      @timeout.nil? ? DEFAULT_TIMEOUT : @timeout
+    end
+
+    # An array of sleep durations (in seconds) used between retries. The value
+    # at index N is used before the (N+1)-th retry; once the array is exhausted
+    # its last element is reused for all further retries. This allows a backoff,
+    # e.g. `[0.05, 0.05, 0.05, 0.1]`. A bare number is accepted and wrapped in
+    # an array.
+    def retry_intervals
+      intervals = @retry_intervals.nil? ? DEFAULT_RETRY_INTERVALS : @retry_intervals
+      Array(intervals)
+    end
+
+    # The minimum number of *retries* (re-invocations after the first call)
+    # `patiently` performs before it is allowed to give up, even if the timeout
+    # has already elapsed. `1` reproduces the historical "try at least twice"
+    # behavior.
+    def min_retries
+      @min_retries.nil? ? DEFAULT_MIN_RETRIES : @min_retries
+    end
+
+    # The maximum number of *retries* `patiently` performs before giving up,
+    # regardless of the timeout. `nil` means unlimited.
+    def max_retries
+      @max_retries
+    end
+
+    # Returns the sleep duration for the given (zero-based) retry index.
+    def retry_interval(retry_index)
+      intervals = retry_intervals
+      intervals[retry_index] || intervals.last
+    end
+
+    # Restores all defaults. Handy in test suites.
+    def reset!
+      @timeout = nil
+      @retry_intervals = nil
+      @min_retries = nil
+      @max_retries = nil
+    end
+  end
+end

data/lib/patiently/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Patiently
+  # Base class for all errors raised by Patiently.
+  class Error < StandardError; end
+
+  # Raised when the (monotonic) clock does not advance between retries, which
+  # usually means time has been mocked/frozen (e.g. via Timecop or Rails'
+  # `travel`/`freeze_time`). Retrying against a frozen clock would loop forever,
+  # so we fail loudly instead.
+  class FrozenInTime < Error; end
+end

data/lib/patiently/helpers.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Patiently
+  # Mix this into a class (or configure RSpec to include it) to gain the
+  # {#patiently} and {#patiently_until} helpers:
+  #
+  #   include Patiently::Helpers
+  module Helpers
+    # Thread-local flag marking that we are already inside a `patiently` block.
+    # Nested blocks are run once and let the *outer* block do the retrying.
+    IN_PATIENTLY = :patiently_in_progress
+
+    # Internal sentinel used by {#patiently_until} to signal "not truthy yet".
+    RetryUntilTrue = Class.new(StandardError)
+
+    # Runs `block`, retrying it whenever it raises, until it succeeds or the
+    # patience window (timeout + min/max retries) is exhausted. Returns the
+    # block's return value on success; re-raises the last exception on failure.
+    #
+    # When called while another `patiently` block is already running on the
+    # current thread, the block is simply run once: only the outermost block is
+    # retried.
+    #
+    # @param timeout [Numeric, nil] overrides +Patiently.config.timeout+
+    # rubocop:disable Lint/RescueException
+    def patiently(timeout = nil, &block)
+      return block.call if Thread.current[IN_PATIENTLY]
+
+      config = Patiently.config
+      timeout ||= config.timeout
+      started_at = monotonic_time
+      retries = 0
+
+      begin
+        Thread.current[IN_PATIENTLY] = true
+        attempt_started_at = monotonic_time
+        block.call
+      rescue Exception => e
+        elapsed = attempt_started_at - started_at
+        timed_out = elapsed > timeout && retries >= config.min_retries
+        retries_exhausted = config.max_retries && retries >= config.max_retries
+        raise e if timed_out || retries_exhausted
+
+        sleep(config.retry_interval(retries))
+
+        if monotonic_time == started_at
+          raise Patiently::FrozenInTime, "time appears to be frozen, consider time travelling instead"
+        end
+
+        retries += 1
+        retry
+      ensure
+        Thread.current[IN_PATIENTLY] = false
+      end
+    end
+    # rubocop:enable Lint/RescueException
+
+    # Retries `block` until it returns a truthy value or the patience window
+    # elapses, then returns the final result as a boolean.
+    #
+    # Because `patiently` only retries on a *raise*, we raise an internal
+    # sentinel while the block is falsey and translate a timed-out sentinel back
+    # into `false`. A real exception inside the block is not the sentinel, so it
+    # still propagates.
+    #
+    # @param timeout [Numeric, nil] overrides +Patiently.config.timeout+
+    def patiently_until(timeout = nil, &block)
+      patiently(timeout) { block.call || raise(RetryUntilTrue) }
+      true
+    rescue RetryUntilTrue
+      false
+    end
+    alias patiently_wait_until patiently_until
+
+    private
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/patiently/rspec.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "../patiently"
+
+# Convenience integration for RSpec: makes `patiently` and `patiently_until`
+# available in feature and system specs (both drive a browser and need retries).
+# If you want a different scope, skip this file and call
+# `config.include(Patiently::Helpers, ...)` yourself.
+RSpec.configure do |config|
+  config.include(Patiently::Helpers, type: :feature)
+  config.include(Patiently::Helpers, type: :system)
+end

data/lib/patiently/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Patiently
+  VERSION = "1.0.0"
+end

data/lib/patiently.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "patiently/version"
+require_relative "patiently/errors"
+require_relative "patiently/configuration"
+require_relative "patiently/helpers"
+
+module Patiently
+  class << self
+    # The global configuration object. See Patiently::Configuration.
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Yields the configuration object for block-style setup:
+    #
+    #   Patiently.configure do |config|
+    #     config.timeout = 10
+    #   end
+    def configure
+      yield config
+    end
+  end
+end