snap_diff-capybara 2.0.0.beta1 → 2.0.0.beta3

data/lib/snap_diff/stable_screenshoter.rb

@@ -34,7 +34,7 @@ module SnapDiff
     #
     # @param snapshot Snap The snapshot details to take a stable screenshot of.
     # @return [void]
-    # @raise [CapybaraScreenshotDiff::UnstableImage] If a stable screenshot cannot be obtained within the specified `:wait` time.
+    # @raise [SnapDiff::UnstableImage] If a stable screenshot cannot be obtained within the specified `:wait` time.
     def take_comparison_screenshot(snapshot)
       result = take_stable_screenshot(snapshot)
 
@@ -43,7 +43,7 @@ module SnapDiff
         # The failed-stability outcome is data (the annotated attempts report); raising is this
         # boundary's decision, not the reporter's.
         # FIXME(uwe): Hand the failure to the verify path so it only reports after the test's own assertions run.
-        raise CapybaraScreenshotDiff::UnstableImage.new(stability_failure_report(snapshot), caller)
+        raise SnapDiff::UnstableImage.new(stability_failure_report(snapshot), caller)
       end
 
       # store success attempt as actual screenshot

data/lib/snap_diff/utils.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "snap_diff/drivers"
+
 module SnapDiff
   module Utils
     def self.detect_available_drivers
@@ -20,9 +22,9 @@ module SnapDiff
     end
 
     def self.find_driver_class_for(driver)
-      driver = Capybara::Screenshot::Diff::AVAILABLE_DRIVERS.first if driver == :auto
+      driver = Drivers.available.first if driver == :auto
 
-      Capybara::Screenshot::Diff::LOADED_DRIVERS[driver] ||=
+      Drivers.loaded[driver] ||=
         case driver
         when :chunky_png
           require "snap_diff/drivers/chunky_png_driver"
@@ -31,7 +33,7 @@ module SnapDiff
           require "snap_diff/drivers/vips_driver"
           SnapDiff::Drivers::VipsDriver
         else
-          fail "Wrong adapter #{driver.inspect}. Available adapters: #{Capybara::Screenshot::Diff::AVAILABLE_DRIVERS.inspect}"
+          fail "Wrong adapter #{driver.inspect}. Available adapters: #{Drivers.available.inspect}"
         end
     end
   end

data/lib/snap_diff/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SnapDiff
-  VERSION = "2.0.0.beta1"
+  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

@@ -1,7 +1,36 @@
 # frozen_string_literal: true
 
-# None of these requires ever leads back to this file: config_legacy is a
-# leaf (see its own header comment), the image_compare forwarder pulls in
+# Dual-install guard: capybara-screenshot-diff and snap_diff-capybara ship
+# identical files. With BOTH activated, every require silently resolves
+# from whichever gem activated first, so version skew between the two is
+# 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(Error)
+
+  # @api private
+  def self.assert_single_gem!(loaded_specs = Gem.loaded_specs)
+    return unless loaded_specs.key?("capybara-screenshot-diff") && loaded_specs.key?("snap_diff-capybara")
+
+    raise DualInstallError,
+      "Both `capybara-screenshot-diff` and `snap_diff-capybara` gems are installed. " \
+      "They ship identical files, so files load from whichever gem activated first " \
+      "and versions can silently diverge. Remove one of them from your Gemfile."
+  end
+end
+SnapDiff.assert_single_gem!
+
+# None of these requires ever leads back to this file: config_legacy sits
+# just above the snap_diff/config leaf (see both headers -- since ADR-008
+# step 1 the storage leaf is snap_diff/config, which config_legacy
+# requires), the image_compare forwarder pulls in
 # snap_diff/comparison plus the legacy const_missing shims, and
 # "capybara/dsl" is the base gem. That keeps this file's require graph
 # acyclic -- it never requires "capybara_screenshot_diff" back, unlike the
@@ -11,13 +40,19 @@
 # stay resolvable (now with deprecation warnings) even in processes that
 # only ever require "snap_diff".
 # "capybara/dsl" is needed directly (not just transitively) so
-# `Capybara.default_max_wait_time` in Diff.default_options resolves even
+# `Capybara.default_max_wait_time` in Config#default_options resolves even
 # when "snap_diff" is required standalone (SnapDiffTest's
 # "standalone-loadable in a fresh process" regression test).
 require "capybara/dsl"
 require "capybara/screenshot/diff/config_legacy"
 require "capybara/screenshot/diff/image_compare"
 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.
 #
@@ -27,22 +62,28 @@ require "snap_diff/config"
 # shims (snap_diff/legacy_shims) that emit a deprecation warning once per
 # constant per process. See ADR-004 for the full migration plan.
 module SnapDiff
-  def self.compare(...)
-    Capybara::Screenshot::Diff.compare(...)
+  # Compare two images on disk with the configured defaults. Canonical home
+  # since ADR-008 step 7b; +Capybara::Screenshot::Diff.compare+ now forwards
+  # here rather than the other way round.
+  #
+  # Note the argument order swap: callers pass baseline first (reading
+  # "compare baseline against current"), Comparison takes current first.
+  def self.compare(baseline_path, current_path, **options)
+    Comparison.new(current_path, baseline_path, config.default_options.merge(options))
   end
 
-  # v1-style configuration: yields the two existing mattr_accessor holders
+  # v1-style configuration: yields the two legacy accessor holders
   # (+Capybara::Screenshot+, +Capybara::Screenshot::Diff+) exactly as
-  # +Capybara::Screenshot::Diff.configure+ always has. Kept byte-for-byte
-  # identical to +Diff.configure+ for existing callers migrating namespaces
-  # without changing call shape.
+  # +Capybara::Screenshot::Diff.configure+ always has -- and, since ADR-008
+  # step 7b, this is where that yield actually happens; Diff.configure
+  # forwards here. Both names stay identical in call shape.
   #
   #   SnapDiff.start do |screenshot, diff|
   #     screenshot.window_size = [1280, 1024]
   #     diff.tolerance = 0.0005
   #   end
-  def self.start(&block)
-    Capybara::Screenshot::Diff.configure(&block)
+  def self.start
+    yield Capybara::Screenshot, Capybara::Screenshot::Diff
   end
 
   # Forward-looking configuration: yields the single consolidated
@@ -58,8 +99,7 @@ module SnapDiff
     yield config
   end
 
-  # The single consolidated settings object. See {SnapDiff::Config}.
-  def self.config
-    @config ||= Config.new
-  end
+  # SnapDiff.config itself is defined in snap_diff/config.rb (the storage
+  # leaf), where the Config instance is created eagerly at require time so
+  # the ENV["CI"] / Rails.root defaults evaluate at load, not first call.
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: snap_diff-capybara
 version: !ruby/object:Gem::Version
-  version: 2.0.0.beta1
+  version: 2.0.0.beta3
 platform: ruby
 authors:
 - Uwe Kubosch
@@ -94,6 +94,7 @@ files:
 - docs/migration-guide.md
 - docs/organization.md
 - docs/reporters.md
+- docs/snapdiff.md
 - docs/thread_safety.md
 - gems.rb
 - lib/capybara-screenshot-diff.rb
@@ -132,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
@@ -148,12 +150,15 @@ files:
 - lib/snap_diff/drivers/vips_driver.rb
 - lib/snap_diff/dsl.rb
 - lib/snap_diff/error_with_filtered_backtrace.rb
+- lib/snap_diff/errors.rb
 - lib/snap_diff/image_preprocessor.rb
 - lib/snap_diff/integrations/cucumber.rb
 - lib/snap_diff/integrations/minitest.rb
 - lib/snap_diff/integrations/rspec.rb
 - lib/snap_diff/legacy_shims.rb
 - lib/snap_diff/os.rb
+- lib/snap_diff/region.rb
+- lib/snap_diff/reporters/default.rb
 - lib/snap_diff/reporters/html.rb
 - lib/snap_diff/reporters/templates/report.html.erb
 - lib/snap_diff/reporting.rb