snap_diff-capybara 2.0.0.beta2 → 2.0.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 480337577271341982e3f8eef57cf123003092ba90833e4b4a497676920c0466
-  data.tar.gz: e844a383454976b32c46059e4593dd0c472133d22eac3e1d531b6bca35935f6e
+  metadata.gz: 8807b325d8008757c4d15af8f81361f00249539c93b17304d44ce0120ffa4f0e
+  data.tar.gz: d285b26c779add8576a9fcd347bf4460238d1c89a488535465db83d331d9b5f2
 SHA512:
-  metadata.gz: b44e77a9e696cd8f326655ba6bd19d5b4275f7f2b86ea0961c913dc30d1ecb6eb0806fa89340359357049bf70c2c015ccaf4d22fc9f6d733c84788db358435f4
-  data.tar.gz: 322a1b64abd4bc2234dea9f6ffcda02f7dac5e9e09c640f1f6decc588b0715953add332a08a61e685bec944358b80b999f77a17b5524663e6c107f771ad7a2fb
+  metadata.gz: 57890b29242441e7afe1b8be5de45a7ebea5f23752a7d806cdb2dbfbcf49ccf7c27289fc4ea40a148728eaab2396a88b843c95fcd1641d82b7a5adc8950b7835
+  data.tar.gz: ea38f270abcd858cb71830d2268bba8a54d6ccc5ffa3fffc63828b3dbe0a8bf0a21c9e5354c3683983913915be93b6564e15ec367ec9680a83f22e64e3bedddf

data/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v2.0.0.beta3] - 2026-08-23
+
+Fixes the canonical `SnapDiff` entry points, which were incomplete in beta2.
+If you are trying the 2.0 experiment on the new API, upgrade — beta2's
+documented quick start does not work.
+
+### Fixed
+- **`require "snap_diff/integrations/minitest"` (and rspec/cucumber/dsl/static)
+  now load the full `SnapDiff` surface.** In beta2 those entry points left
+  `SnapDiff.configure`, `.start`, `.compare` and `SnapDiff::VERSION` undefined,
+  so the quick start in the canonical guide raised `NoMethodError`
+- **The dual-install guard now runs on every canonical entry point.** In beta2
+  it lived only in `require "snap_diff"`, so the recommended path was the one
+  place it never fired
+- **Legacy entry points keep the full `CapybaraScreenshotDiff` session surface** —
+  `require "capybara/screenshot/diff/cucumber"` and
+  `require "capybara_screenshot_diff/static"` lost `verify`/`reset`/`reporters`
+  and friends in beta2 while the module stayed defined, so calls failed late
+- **`Capybara::Screenshot::Diff::Reporters::Default` and
+  `…::Diff::Comparison` are eager aliases again**, so `defined?` and
+  `const_defined?` report them as they did in beta1. beta2 made them lazy,
+  which silently broke feature detection — and made beta2's own compatibility
+  note inaccurate for those two constants
+- **`SnapDiff::Error` is now the catch-all the docs promise** —
+  `WindowSizeMismatchError` and `DualInstallError` inherit it, so
+  `rescue SnapDiff::Error` catches every error the gem raises
+- **`gem "snap_diff-capybara"` works with `Bundler.require`** — the gem had no
+  matching entry file, so Rails users got nothing loaded and a confusing
+  `NameError` later
+- Reporter failure warnings use one brand and name the failing reporter class
+
+---
+
 ## [v2.0.0.beta2] - 2026-08-23
 
 Third prerelease of the 2.0 opt-in experiment. This one finishes the namespace

data/docs/UPGRADING.md

@@ -6,7 +6,7 @@
 
 Version 2.0 introduces a new canonical namespace (`SnapDiff`) for cleaner, more discoverable code. The public DSL remains unchanged — your existing `screenshot` and `assert_matches_screenshot` calls work without modification. This guide covers the optional migration path for settings and the new namespace.
 
-**Status:** `2.0.0.beta2` is an opt-in prerelease. RubyGems never installs prereleases by default resolution — normal `bundle update` keeps you on the 1.x line. The final 2.0.0 ships only after adopter feedback; please report anything surprising on [#166](https://github.com/snap-diff/snap_diff-capybara/issues/166).
+**Status:** `2.0.0.beta3` is an opt-in prerelease. RubyGems never installs prereleases by default resolution — normal `bundle update` keeps you on the 1.x line. The final 2.0.0 ships only after adopter feedback; please report anything surprising on [#166](https://github.com/snap-diff/snap_diff-capybara/issues/166).
 
 **Estimated upgrade time:** 5–15 minutes (most users need only the Gemfile pin)
 
@@ -22,7 +22,7 @@ with canonical names only, no legacy shapes to unlearn.
 
 ```ruby
 # In your Gemfile — the exact prerelease version is required to opt in
-gem "capybara-screenshot-diff", "2.0.0.beta2" # or the latest 2.0.0 prerelease
+gem "capybara-screenshot-diff", "2.0.0.beta3" # or the latest 2.0.0 prerelease
 ```
 
 ```bash
@@ -233,7 +233,7 @@ All settings and baselines are compatible with v1.x. Simply pin your Gemfile bac
 
 ### Summary Checklist
 
-- [ ] Pin `gem "capybara-screenshot-diff", "2.0.0.beta2"` (or the latest 2.0.0 prerelease) in your Gemfile
+- [ ] Pin `gem "capybara-screenshot-diff", "2.0.0.beta3"` (or the latest 2.0.0 prerelease) in your Gemfile
 - [ ] Run `bundle install`
 - [ ] Run your test suite to verify no regressions
 - [ ] (Optional) Migrate config to the `SnapDiff` namespace

data/lib/capybara/screenshot/diff/cucumber.rb

@@ -1,3 +1,7 @@
 # frozen_string_literal: true
 
-require "snap_diff/integrations/cucumber"
+# Legacy (v1-documented) entry point: like every other legacy entry, it must
+# load the legacy surface too -- requiring only the canonical integration
+# left CapybaraScreenshotDiff half-present (module defined, but .verify /
+# .reset / .reporters / ... gone) for v1 users of this path.
+require "capybara_screenshot_diff/cucumber"

data/lib/capybara/screenshot/diff/image_compare.rb

@@ -6,10 +6,22 @@
 # snap_diff/comparison itself pulls in the ComparisonResult and Drivers
 # units, and the shims keep the old ::Difference / ::Drivers names
 # resolvable, so this path still provides everything the pre-move
-# image_compare.rb did. The internal images-holder struct lives at
-# SnapDiff::Comparison::Images (its old ::Comparison name resolves via the
-# shims) and the driver cache at SnapDiff::Drivers.loaded, with
-# LOADED_DRIVERS kept as an eager same-object alias by legacy_shims
-# (ADR-008 step 5).
+# image_compare.rb did. The images-holder struct lives at
+# SnapDiff::Comparison::Images and the driver cache at
+# SnapDiff::Drivers.loaded, with LOADED_DRIVERS kept as an eager same-object
+# alias by legacy_shims (ADR-008 step 5).
 require "snap_diff/comparison"
 require "snap_diff/legacy_shims"
+
+# Deliberately EAGER and silent (v2 step 6 exception): Comparison is a
+# documented user-facing struct, so adopters feature-detect it with
+# defined?/const_defined? -- neither of which triggers const_missing, so a
+# lazy shim reported it permanently absent. See snap_diff/legacy_shims.rb
+# for the full exception list.
+module Capybara
+  module Screenshot
+    module Diff
+      Comparison = SnapDiff::Comparison::Images
+    end
+  end
+end

data/lib/capybara/screenshot/diff/reporters/default.rb

@@ -1,7 +1,21 @@
 # frozen_string_literal: true
 
 # Forwarder (ADR-008 step 4): the default reporter lives at
-# SnapDiff::Reporters::Default; the old name now resolves lazily via
-# snap_diff/legacy_shims' const_missing, with a deprecation warning.
+# SnapDiff::Reporters::Default.
 require "snap_diff/reporters/default"
 require "snap_diff/legacy_shims"
+
+# Deliberately EAGER and silent (v2 step 6 exception): Default is a
+# documented subclassing extension point, so adopters feature-detect it with
+# defined?/const_defined? -- neither of which triggers const_missing, so a
+# lazy shim reported it permanently absent. See snap_diff/legacy_shims.rb
+# for the full exception list.
+module Capybara
+  module Screenshot
+    module Diff
+      module Reporters
+        Default = SnapDiff::Reporters::Default
+      end
+    end
+  end
+end

data/lib/capybara_screenshot_diff/static.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# Legacy entry point: loads the legacy surface (the umbrella) like its
+# minitest/rspec/cucumber siblings, so consumers who require only this file
+# still get CapybaraScreenshotDiff's session and reporter methods.
+require "capybara_screenshot_diff"
 require "snap_diff/static"
 
 module CapybaraScreenshotDiff

data/lib/snap_diff/dsl.rb

@@ -1,5 +1,13 @@
 # frozen_string_literal: true
 
+# The canonical entry point. Everything a user is told to require under
+# snap_diff/ (this file, snap_diff/integrations/*, snap_diff/static) routes
+# through here, so this one line is what makes SnapDiff.configure/.start/
+# .compare/::VERSION -- and the dual-install guard -- present no matter
+# which of those paths the user picked. snap_diff.rb never requires this
+# file back, so the require graph stays acyclic.
+require "snap_diff"
+
 # No require of "capybara_screenshot_diff" here: every Capybara::Screenshot
 # reference below is inside a method body, resolved lazily at call time, not
 # at this file's own load time -- so this unit has no eager dependency on

data/lib/snap_diff/errors.rb

@@ -8,6 +8,12 @@ require "snap_diff/error_with_filtered_backtrace"
 # shims, because rescue clauses and defined?/const_defined? feature
 # detection in adopter code must keep behaving exactly as before
 # (const_defined? never triggers const_missing).
+#
+# Error is the catch-all docs/snapdiff.md advertises: EVERY error this gem
+# raises inherits it, so `rescue SnapDiff::Error` really does catch them all
+# (pinned by test/unit/errors_alias_test.rb, which discovers the classes
+# rather than listing them). ErrorWithFilteredBacktrace is plumbing, not a
+# second root.
 module SnapDiff
   class Error < ErrorWithFilteredBacktrace; end
 
@@ -15,5 +21,5 @@ module SnapDiff
 
   class UnstableImage < Error; end
 
-  class WindowSizeMismatchError < ErrorWithFilteredBacktrace; end
+  class WindowSizeMismatchError < Error; end
 end

data/lib/snap_diff/legacy_shims.rb

@@ -20,6 +20,11 @@ require "snap_diff/drivers"
 #   const_missing, so a lazy shim would break that contract.
 # - Capybara::Screenshot::Diff::VERSION: the gemspec resolves it at build
 #   time; a lazy shim would make every `gem build` warn.
+# - Capybara::Screenshot::Diff::Reporters::Default (a documented subclassing
+#   extension point) and Capybara::Screenshot::Diff::Comparison (the images
+#   struct): documented user-facing names that adopters feature-detect with
+#   defined?/const_defined?. Assigned eagerly by their own forwarder files
+#   (reporters/default.rb, image_compare.rb).
 # - Drivers::ChunkyPNGDriver / Drivers::VipsDriver: real constants on the
 #   shared SnapDiff::Drivers module (the Drivers alias is same-object by
 #   contract), so const_missing can never fire for the leaf names;
@@ -57,9 +62,6 @@ module Capybara
     module Diff
       # EAGER same-object alias of the canonical driver cache (see header).
       LOADED_DRIVERS = SnapDiff::Drivers.loaded
-
-      module Reporters
-      end
     end
   end
 end
@@ -84,14 +86,9 @@ SnapDiff::LegacyShims.install(Capybara::Screenshot::Diff, "Capybara::Screenshot:
   ScreenshotMatcher: "SnapDiff::ScreenshotMatcher",
   Drivers: "SnapDiff::Drivers",
   ImageCompare: "SnapDiff::Comparison",
-  Comparison: "SnapDiff::Comparison::Images",
   Difference: "SnapDiff::ComparisonResult"
 }.freeze)
 
-SnapDiff::LegacyShims.install(Capybara::Screenshot::Diff::Reporters, "Capybara::Screenshot::Diff::Reporters", {
-  Default: "SnapDiff::Reporters::Default"
-}.freeze)
-
 SnapDiff::LegacyShims.install(CapybaraScreenshotDiff, "CapybaraScreenshotDiff", {
   RED_RGBA: "SnapDiff::RED_RGBA",
   ORANGE_RGBA: "SnapDiff::ORANGE_RGBA",

data/lib/snap_diff/reporting.rb

@@ -40,7 +40,7 @@ module SnapDiff
         reporters_snapshot.each do |reporter|
           reporter.record(assertions)
         rescue => e
-          warn "[capybara-screenshot-diff] Reporter failed: #{e.message}"
+          warn "[snap_diff] Reporter #{reporter.class} failed (#{e.class}: #{e.message})"
         end
       end
 

data/lib/snap_diff/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SnapDiff
-  VERSION = "2.0.0.beta2"
+  VERSION = "2.0.0.beta3"
 end

data/lib/snap_diff-capybara.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Bundler.require entry point for `gem "snap_diff-capybara"`: Bundler
+# requires the gem's own name, and its dash->slash fallback ("snap_diff/
+# capybara") misses too, so without this file a Rails user gets a silent
+# no-op and a confusing NameError later. Loads what the sibling
+# capybara-screenshot-diff.rb loads.
+require "capybara_screenshot_diff/minitest"

data/lib/snap_diff.rb

@@ -6,8 +6,14 @@
 # undetectable. Refuse that setup at the entry point. Local dev from
 # source loads neither spec, so the guard fires only when both are
 # genuinely installed as gems.
+#
+# snap_diff/errors is pulled in first (two dependency-free files) so
+# DualInstallError can sit under SnapDiff::Error like every other error the
+# gem raises -- docs/snapdiff.md promises Error is the catch-all.
+require "snap_diff/errors"
+
 module SnapDiff
-  DualInstallError = Class.new(StandardError)
+  DualInstallError = Class.new(Error)
 
   # @api private
   def self.assert_single_gem!(loaded_specs = Gem.loaded_specs)
@@ -40,8 +46,13 @@ SnapDiff.assert_single_gem!
 require "capybara/dsl"
 require "capybara/screenshot/diff/config_legacy"
 require "capybara/screenshot/diff/image_compare"
-require "snap_diff/errors"
 require "snap_diff/config"
+require "snap_diff/version"
+# SnapDiff.session/.reset/.pending_screenshots_message are part of the
+# documented core surface (docs/snapdiff.md object map lists them with no
+# extra require), so the entry point owns them rather than leaving them to
+# whichever integration happens to be loaded.
+require "snap_diff/screenshot_assertion"
 
 # Forward-looking namespace for the gem, per ADR-004.
 #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: snap_diff-capybara
 version: !ruby/object:Gem::Version
-  version: 2.0.0.beta2
+  version: 2.0.0.beta3
 platform: ruby
 authors:
 - Uwe Kubosch
@@ -133,6 +133,7 @@ files:
 - lib/capybara_screenshot_diff/snap.rb
 - lib/capybara_screenshot_diff/snap_manager.rb
 - lib/capybara_screenshot_diff/static.rb
+- lib/snap_diff-capybara.rb
 - lib/snap_diff.rb
 - lib/snap_diff/annotation_service.rb
 - lib/snap_diff/area_calculator.rb