capybara-storyboard 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c4545f0de7b20b1fbfcf71a08ed644553d5445001370ff3d59a4d8c9fc9c88f
-  data.tar.gz: a3aa8204023cab2f89f1799f0fbf7aee7fe6965bbbe00d1944e75c27010dc158
+  metadata.gz: 3bf6a851426d1aa00542d1d81071115072cd603519243887686156f178c62d57
+  data.tar.gz: 145f880b26d5d6ae6b8042f2434b398bb018f7d0b646cc5fc0922cd9ed25d509
 SHA512:
-  metadata.gz: 4aed98cd98f7137740c85d5b9d994adbec0ecd2f9c06c972c7caacc5b4087e7450710855e267d507651ceb1f5d4f4667bfb1bdf8d0a9d0f037c5d39f27bcadb4
-  data.tar.gz: f801d661ab48e2d980fc39aaa7f8d9614a79a6c6b3795c7335f33263658a872d97894c8e7ad76fabf72bd51767d2dfbbc17ad45c056bd86661c4c425e8d1d8b6
+  metadata.gz: b73fed754aafe430f72452947b62f3ebb50480b3deeeea2c3dff00f6296d17297eaa96004c94d12908838dedbde58ac5ff966db331003e628fc3b639d9312129
+  data.tar.gz: 6f61ca195317e9c69f7cd476e158d55b48f86fc1d072a60829a93a780527176d94d0a5c1bf44cb5137e8ddbd6739cd7f4081d12f84c850e9991bcd39b6ac4a6f

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-08-12
+
+- Replace wholly-numeric path segments in `visit` paths with `N` in screenshot filenames
+  (e.g. `visit '/observations/20/edit'` now produces `visit_observations_N_edit.png`), so
+  varying record IDs no longer break visual-regression pairing between runs. Migration note:
+  filenames change for numeric-ID visits, so the first run after upgrading shows one round of
+  added/deleted images when compared against an older baseline.
+
+## [0.3.0] - 2026-07-23
+
+- Fix `NoMethodError` / spurious "skipped after error" warnings when a page navigation happens between setup and a stability poll, by treating non-finite poll results (nil/NaN/Infinity) as "measurement lost" and re-arming the observer
+
 ## [0.2.0] - 2026-07-22
 
 - Add `visual-regression-test` skill for AI-assisted before/after screenshot comparison

data/README.md

@@ -171,6 +171,17 @@ order in which actions occurred. For example:
 Non-ASCII descriptions and labels (e.g. Japanese) are preserved as-is in file and directory
 names; only symbols and whitespace are replaced with underscores.
 
+For `visit`, wholly-numeric path segments are additionally replaced with `N` before
+sanitization, e.g. `visit '/observations/20/edit'` produces `001_visit_observations_N_edit.png`
+rather than embedding the `20`. Record IDs vary between test runs and between branches, and a
+filename that varies with them stops a visual-regression tool from pairing the same screen
+across two runs, which reports it as added + deleted instead of comparing it. This only
+replaces path segments that are *entirely* digits (`user42` and `h2` are left as-is), only
+applies to `visit`, and only touches the path — the query string and fragment are untouched
+(`/search?id=20` stays `search_id_20`). Locators passed to `click_on`, `fill_in`, and friends
+keep their digits. If you want a specific ID to appear in a filename anyway, use
+`storyboard_screenshot(label)` to build the label yourself.
+
 The default output root is `<Rails.root>/tmp/screenshots` (overridable, see
 [Configuration](#configuration)).
 

data/docs/visual-regression.md

@@ -96,7 +96,10 @@ The compare job uploads two artifacts:
   output and would cause over-selection.
 - A large batch of "added"/"deleted" images clustered under one example usually means a
   Capybara step was inserted or removed in that example, shifting every later step's `NNN`
-  sequence number — not many independent regressions.
+  sequence number — not many independent regressions. Numeric `visit` path segments are
+  already normalized to `N` by capybara-storyboard, so a differing record ID there is not a
+  cause — a shifted `NNN` is usually the remaining explanation. (An ID in a query string, as
+  in `/search?user_id=42`, is not normalized and can still shift a filename.)
 - Diff images are linked via artifact URLs rather than embedded in the PR comment, because
   GitHub's Markdown image embedding requires a URL its camo proxy can fetch unauthenticated,
   and artifact URLs require authentication.

data/lib/capybara/storyboard/page_stability.rb

@@ -62,8 +62,15 @@ module Capybara
           stable = stable?(result, interval)
           break if stable
 
-          # No point sleeping after the final check — nothing re-checks it.
-          sleep(interval) unless attempt == max_attempts - 1
+          # No point re-arming or sleeping after the final check — cleanup runs
+          # immediately after and nothing re-checks it.
+          next if attempt == max_attempts - 1
+
+          # The measurement was reset by a page navigation (non-numeric result);
+          # re-arm the observer with the configured excluded animations so the
+          # next poll can measure again.
+          setup(page, excluded_animations) unless measurable?(result)
+          sleep(interval)
         end
 
         # Unstable (or max_attempts was 0): the page is deemed good enough.
@@ -106,9 +113,32 @@ module Capybara
         nil
       end
 
+      # True when the poll returned real numbers to compare. A page navigation
+      # between setup and a poll swaps in a fresh document whose
+      # window._lastMutationTime is undefined, so Date.now() - undefined === NaN.
+      # Callers use this to decide whether to re-arm the observer (Ruby side) and
+      # whether the numeric comparison in #stable? is even meaningful.
+      def measurable?(result)
+        finite_number?(result['runningAnimations']) && finite_number?(result['timeSinceLastMutation'])
+      end
+
+      # True only for a real, finite number. Guards against nil (Selenium
+      # serializes a navigation-reset NaN to JSON null) and against Float::NAN /
+      # Infinity (CDP drivers such as Cuprite/Ferrum decode the reset NaN back
+      # into a literal Float::NAN), both of which mean "the measurement was lost
+      # and must be re-armed".
+      def finite_number?(value)
+        value.is_a?(Numeric) && (!value.is_a?(Float) || value.finite?)
+      end
+
       # evaluate_script returns string-keyed hashes on the real drivers; the
       # DOM-quiet window is measured in ms, so compare against interval * 1000.
+      # A non-numeric result (e.g. the measurement was reset by a page
+      # navigation) is treated as "not stable yet", which also keeps this
+      # comparison free of NoMethodError regardless of what the driver hands back.
       def stable?(result, interval)
+        return false unless measurable?(result)
+
         result['runningAnimations'].zero? && result['timeSinceLastMutation'] >= (interval * 1000)
       end
 

data/lib/capybara/storyboard/session.rb

@@ -12,6 +12,9 @@ module Capybara
     # of Capybara and RSpec hooks: a Session can be built with a plain example
     # double and an injected +output_root+.
     class Session
+      PATH_ID_PLACEHOLDER = 'N'
+      private_constant :PATH_ID_PLACEHOLDER
+
       def initialize(example:, enabled:, output_root: nil)
         @example = example
         @enabled = enabled
@@ -34,6 +37,31 @@ module Capybara
         capture_with_label(page, label)
       end
 
+      # Automatic screenshot for a path-shaped DSL action (currently only
+      # #visit). Same as #auto except wholly-numeric path segments in the detail
+      # are collapsed to N first, so /observations/20/edit and
+      # /observations/33/edit yield one stable filename. Record ids vary between
+      # runs and between branches; a varying filename stops a visual-regression
+      # tool from pairing the two sides by path, which reports the same screen
+      # as added + deleted instead of comparing it.
+      #
+      # Deliberately a separate entry point rather than a branch inside #auto:
+      # Session stays ignorant of which action names are path-shaped, and the
+      # caller declares it by choosing the method (as with #auto vs #manual).
+      # Locators passed to click_link/fill_in/... are human-written fixed
+      # strings, so they keep their digits and keep using #auto.
+      #
+      # The enabled/suppressed guards are repeated here rather than left to
+      # #auto because Ruby evaluates arguments before the call: without them,
+      # every visit in a disabled suite would normalize a path only for #auto to
+      # discard it, breaking the "disabled -> zero overhead" contract.
+      def auto_path(page, action, path)
+        return unless @enabled
+        return if suppressed?
+
+        auto(page, action, normalize_path_ids(path))
+      end
+
       # Manual screenshot hook. Like #auto, captured only when enabled. For an
       # unconditional screenshot, use Capybara's own save_screenshot. The page
       # is passed explicitly rather than held as state.
@@ -144,6 +172,30 @@ module Capybara
       def sanitize(text)
         text.to_s.gsub(/[^\p{Word}-]/, '_').gsub(/_+/, '_').gsub(/\A_|_\z/, '')
       end
+
+      # Replaces every wholly-numeric path segment with N (/observations/20/edit
+      # -> /observations/N/edit). Segment-based on purpose: only a segment that
+      # is *nothing but* digits is a record id, so user42, h2 and v2 are left
+      # alone.
+      #
+      # The query/fragment is split off and left untouched — an id there sits in
+      # a value (?id=20), not a segment, and rewriting it would need parameter
+      # parsing for no gain. Splitting on / with -1 keeps empty segments, so a
+      # trailing slash and a full URL's // both survive round-tripping (the host
+      # segment of http://example.com/x/20 is non-numeric, so a full URL needs
+      # no special case).
+      #
+      # Runs BEFORE #sanitize, which would otherwise collapse / into _ and make
+      # segment boundaries unrecoverable. \A\d+\z is ASCII-only by design: URL
+      # path ids are ASCII digits, and preserving Unicode is #sanitize's job.
+      def normalize_path_ids(path)
+        head, separator, tail = path.to_s.partition(/[?#]/)
+        normalized =
+          head.split('/', -1).map do |segment|
+            segment.match?(/\A\d+\z/) ? PATH_ID_PLACEHOLDER : segment
+          end
+        "#{normalized.join('/')}#{separator}#{tail}"
+      end
     end
   end
 end

data/lib/capybara/storyboard/test_helper.rb

@@ -19,7 +19,7 @@ module Capybara
       end
 
       def visit(path, ...)
-        super.tap { @__storyboard.auto(page, 'visit', path) }
+        super.tap { @__storyboard.auto_path(page, 'visit', path) }
       end
 
       def click_on(locator = nil, ...)

data/lib/capybara/storyboard/version.rb

@@ -2,6 +2,6 @@
 
 module Capybara
   module Storyboard
-    VERSION = '0.2.0'
+    VERSION = '0.4.0'
   end
 end

data/skills/visual-regression-test/SKILL.md

@@ -233,7 +233,9 @@ npx reg-cli tmp/vrt/after tmp/vrt/before tmp/vrt/diff \
   directory). `1` means "there's a diff, go verify it," not failure.
 - Since both sets ran the same spec, filenames match across the two sets and reg-cli pairs them
   automatically by path. Images present on only one side are reported as added/deleted — this
-  happens when the diff changed the spec's own steps.
+  happens when the diff changed the spec's own steps (record IDs in `visit` **path segments** are
+  already normalized to `N` by the gem, so a differing ID there is not a cause — but an ID in a
+  query string, as in `/search?user_id=42`, is not normalized and can still shift a filename).
 
 ### 5. Verify the detected diffs
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capybara-storyboard
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - aki