capybara-storyboard 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad9e5b4eaf1c9021974e3b98572e5df40de5cd7d9a76a4596d1d1498a5b1ba6e
-  data.tar.gz: d43fd39b24c6501f2e22f89c63e83df203da15cc111b4812b520727fa26280e7
+  metadata.gz: 3bf6a851426d1aa00542d1d81071115072cd603519243887686156f178c62d57
+  data.tar.gz: 145f880b26d5d6ae6b8042f2434b398bb018f7d0b646cc5fc0922cd9ed25d509
 SHA512:
-  metadata.gz: 83807f656992133cd59d9602f2a1574e9d018d69e63a69010b01dc28ba0bcc27de48d464fe10e36eb1e60ab914eae6b9725d226735b4b3266cf39c983c24d0ce
-  data.tar.gz: 513c4e0147ef78eee5a5e36c720ea428b8a8ee9ebbf885c31201438d3d12b8bdbc2bc495a3e0fd6e8c58c2458ba49fc7ddd3d8350f59d5ead1b5f9e019953afc
+  metadata.gz: b73fed754aafe430f72452947b62f3ebb50480b3deeeea2c3dff00f6296d17297eaa96004c94d12908838dedbde58ac5ff966db331003e628fc3b639d9312129
+  data.tar.gz: 6f61ca195317e9c69f7cd476e158d55b48f86fc1d072a60829a93a780527176d94d0a5c1bf44cb5137e8ddbd6739cd7f4081d12f84c850e9991bcd39b6ac4a6f

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [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

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/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.3.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.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - aki