snap_diff-capybara 2.0.0.alpha1 → 2.0.0.beta2

data/lib/snap_diff/reporters/default.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "snap_diff/annotation_service"
+
+module SnapDiff
+  module Reporters
+    class Default
+      attr_reader :difference
+
+      def initialize(difference)
+        @difference = difference
+        @annotation_service = SnapDiff::AnnotationService.new(difference)
+      end
+
+      def annotated_image_path
+        annotation_service.annotated_image_path
+      end
+
+      def annotated_base_image_path
+        annotation_service.annotated_base_image_path
+      end
+
+      def heatmap_diff_path
+        annotation_service.heatmap_diff_path
+      end
+
+      def generate
+        if difference.equal?
+          # NOTE: Delete previous run runtime files
+          clean_tmp_files
+          return nil
+        end
+
+        if difference.failed? && difference.failed_by[:different_dimensions]
+          return build_error_for_different_dimensions
+        end
+
+        annotate_and_save_images
+        build_error_message
+      end
+
+      def clean_tmp_files
+        annotation_service.clean_tmp_files
+      end
+
+      def annotate_and_save_images
+        annotation_service.annotate_and_save_images
+      end
+
+      def save_annotation_for(image, image_path)
+        annotation_service.save_annotation_for(image, image_path)
+      end
+
+      def annotate_difference(image, region)
+        annotation_service.annotate_difference(image, region)
+      end
+
+      def annotate_skip_areas(image, skip_areas)
+        annotation_service.annotate_skip_areas(image, skip_areas)
+      end
+
+      def save(image, image_path)
+        annotation_service.save(image, image_path)
+      end
+
+      def build_error_for_different_dimensions
+        change_msg = [comparison.base_image, comparison.new_image]
+          .map { |image| driver.dimension(image).join("x") }
+          .join(" => ")
+
+        "Dimensions have changed: #{change_msg}\n#{base_image_path.to_path}\n#{image_path.to_path}"
+      end
+
+      NEW_LINE = "\n"
+
+      def build_error_message
+        [
+          "(#{difference.to_h.to_json})",
+          image_path.to_path,
+          annotated_base_image_path.to_path,
+          annotated_image_path.to_path,
+          heatmap_diff_path.to_path
+        ].join(NEW_LINE)
+      end
+
+      private
+
+      attr_reader :annotation_service
+
+      def base_image_path
+        comparison.base_image_path
+      end
+
+      def image_path
+        comparison.new_image_path
+      end
+
+      def driver
+        @_driver ||= comparison.driver
+      end
+
+      def comparison
+        @_comparison ||= difference.comparison
+      end
+    end
+  end
+end

data/lib/snap_diff/reporters/html.rb

@@ -5,11 +5,9 @@ require "erb"
 require "fileutils"
 require "pathname"
 require "json"
-# The auto-registration block at the bottom of this file calls
-# CapybaraScreenshotDiff.reporters, which needs the registry singleton
-# machinery in the *old* capybara_screenshot_diff/screenshot_assertion.rb
-# file (deliberately not moved -- see that file's own comment).
-require "capybara_screenshot_diff/screenshot_assertion"
+# The auto-registration block at the bottom of this file registers with
+# SnapDiff::Reporting.
+require "snap_diff/reporting"
 require "capybara/screenshot/diff/config_legacy"
 
 module SnapDiff
@@ -136,8 +134,8 @@ module SnapDiff
 end
 
 # Auto-register reporter.
-# Framework adapters (Minitest, RSpec, Cucumber) call finalize_reporters! via native hooks.
-# For custom frameworks, call CapybaraScreenshotDiff.finalize_reporters! manually.
-unless CapybaraScreenshotDiff.reporters.any?(SnapDiff::Reporters::HTML)
-  CapybaraScreenshotDiff.reporters << SnapDiff::Reporters::HTML.new(embed_images: !!ENV["CI"])
+# Framework adapters (Minitest, RSpec, Cucumber) call SnapDiff::Reporting.finalize! via native hooks.
+# For custom frameworks, call SnapDiff::Reporting.finalize! manually.
+unless SnapDiff::Reporting.reporters.any?(SnapDiff::Reporters::HTML)
+  SnapDiff::Reporting.register(SnapDiff::Reporters::HTML.new(embed_images: !!ENV["CI"]))
 end

data/lib/snap_diff/reporting.rb

@@ -5,10 +5,9 @@ module SnapDiff
   # end-of-suite finalization. One list of reporters for the whole process,
   # guarded by one mutex.
   #
-  # Deliberately separate from the per-test session lifecycle (the
-  # thread-local AssertionRegistry reached through
-  # CapybaraScreenshotDiff.registry): reporters outlive any single test,
-  # the registry does not. CapybaraScreenshotDiff keeps its public
+  # Deliberately separate from the per-test session lifecycle
+  # (SnapDiff.session): reporters outlive any single test, the session does
+  # not. CapybaraScreenshotDiff keeps its public
   # reporters/reporters_mutex/finalize_reporters! methods as thin shims
   # over this module.
   module Reporting
@@ -18,6 +17,16 @@ module SnapDiff
     class << self
       attr_reader :reporters, :mutex
 
+      # Registers a reporter for the rest of the process. The canonical way
+      # in: the append happens under the mutex, so concurrent registrations
+      # cannot lose one (issue #217 item 2). `reporters` stays public and
+      # mutable for compatibility -- appending to it directly still works,
+      # it just skips the lock.
+      def register(reporter)
+        @mutex.synchronize { @reporters << reporter }
+        reporter
+      end
+
       # Delivers a finished test's assertions to every registered reporter.
       # Iterates over a snapshot so a reporter mutating the list mid-notify
       # cannot affect the current round. A raising reporter is warned about

data/lib/snap_diff/screenshot_assertion.rb

@@ -2,8 +2,42 @@
 
 require "fileutils"
 require_relative "screenshot_namer"
+require_relative "reporting"
 
 module SnapDiff
+  # --- Session lifecycle (per-test) ---
+  #
+  # The canonical home of the per-test session: the AssertionRegistry
+  # holding the assertions and new-screenshot names of the test running
+  # here. CapybaraScreenshotDiff.registry / .reset /
+  # .pending_screenshots_message are thin forwarders over these.
+  #
+  # Note: Thread.current[] is *fiber*-local, so a session is per fiber, not
+  # per thread. That is pre-existing, documented behaviour (issue #217);
+  # ADR-008 step 6 relocates the accessor without touching the semantics.
+  def self.session
+    Thread.current[:capybara_screenshot_diff_registry] ||= AssertionRegistry.new
+  end
+
+  # Ends a test: hands the finished session's assertions to the reporters,
+  # then clears it. The one deliberate bridge between the process-global
+  # reporter lifecycle (SnapDiff::Reporting) and the per-test session.
+  def self.reset
+    Reporting.notify(session.assertions)
+    session.reset
+  end
+
+  # Message to skip the test with when a new screenshot has no baseline yet
+  # and `pending_if_new` is enabled. Adapters call this after verifying
+  # screenshots, and skip the test with the returned message when present.
+  #
+  # @return [String, nil] the pending message, or nil when there is nothing to report
+  def self.pending_screenshots_message
+    return unless ::Capybara::Screenshot::Diff.pending_if_new && session.new_screenshots_present?
+
+    "No baseline for: #{session.new_screenshots.join(", ")}. Commit the captured screenshots to record them."
+  end
+
   class ScreenshotAssertion
     attr_reader :name, :args
     attr_accessor :compare, :caller
@@ -52,7 +86,7 @@ module SnapDiff
       error_msg = validate
 
       if error_msg
-        raise CapybaraScreenshotDiff::ExpectationNotMet.new(error_msg, caller)
+        raise SnapDiff::ExpectationNotMet.new(error_msg, caller)
       end
     end
 
@@ -118,15 +152,14 @@ module SnapDiff
       !@new_screenshots.empty?
     end
 
-    def verify(screenshots = CapybaraScreenshotDiff.assertions)
+    def verify(screenshots = assertions)
       return unless ::Capybara::Screenshot.active? && ::Capybara::Screenshot::Diff.fail_on_difference
 
-      failed_assertions = CapybaraScreenshotDiff.registry.failed_assertions
       failed_screenshot = failed_assertions.first
       result = ScreenshotAssertion.verify_screenshots!(screenshots)
 
       if result
-        raise CapybaraScreenshotDiff::ExpectationNotMet.new(result.join("\n\n"), failed_screenshot.caller)
+        raise SnapDiff::ExpectationNotMet.new(result.join("\n\n"), failed_screenshot.caller)
       end
     end
 

data/lib/snap_diff/screenshot_matcher.rb

@@ -21,7 +21,7 @@ module SnapDiff
     end
 
     def build_screenshot_assertion(skip_stack_frames: 0)
-      Capture::Viewport.prepare!(Capybara::Screenshot.window_size, anchor: nil)
+      Capture::Viewport.prepare!(Capybara::Screenshot.window_size)
       prepare_screenshot_options
       check_base_screenshot
 
@@ -32,7 +32,7 @@ module SnapDiff
       # Pre-computation: No need to compare without base screenshot
       # NOTE: Consider to return PreValid Assertion Value Object with hard coded valid result
       unless need_to_compare?
-        CapybaraScreenshotDiff.record_new_screenshot(screenshot_full_name)
+        SnapDiff.session.record_new_screenshot(screenshot_full_name)
         return
       end
 
@@ -41,7 +41,7 @@ module SnapDiff
 
     # Captures a screenshot without comparing it to a baseline.
     def capture
-      Capture::Viewport.prepare!(Capybara::Screenshot.window_size, anchor: nil)
+      Capture::Viewport.prepare!(Capybara::Screenshot.window_size)
       prepare_screenshot_options
 
       capture_options, comparison_options = extract_capture_and_comparison_options(driver_options)
@@ -68,7 +68,7 @@ module SnapDiff
       @snapshot.checkout_base_screenshot
 
       if Capybara::Screenshot::Diff.fail_if_new && !@snapshot.base_path.exist?
-        raise CapybaraScreenshotDiff::ExpectationNotMet.new(<<~ERROR.chomp, caller)
+        raise SnapDiff::ExpectationNotMet.new(<<~ERROR.chomp, caller)
           No existing screenshot found for #{@snapshot.base_path}!
           To record baselines: RECORD_SCREENSHOTS=1 bundle exec rake test
           To allow new screenshots: Capybara::Screenshot::Diff.fail_if_new = false

data/lib/snap_diff/screenshoter.rb

@@ -88,7 +88,7 @@ module SnapDiff
         break unless pending_image
 
         if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline_at
-          raise CapybaraScreenshotDiff::ExpectationNotMet.new("Images have not been loaded after #{timeout}s: #{pending_image.inspect}", caller)
+          raise SnapDiff::ExpectationNotMet.new("Images have not been loaded after #{timeout}s: #{pending_image.inspect}", caller)
         end
 
         sleep 0.025

data/lib/snap_diff/snap_manager.rb

@@ -3,7 +3,6 @@
 require "fileutils"
 
 require_relative "vcs"
-require "active_support/core_ext/module/attribute_accessors"
 
 require_relative "snap"
 
@@ -100,7 +99,7 @@ module SnapDiff
     # manager class or screenshot root changes (tests re-root per example).
     #
     # Thread.current[] is fiber-local — same construct as
-    # CapybaraScreenshotDiff.registry; both split per fiber and must migrate
+    # SnapDiff.session; both split per fiber and must migrate
     # together if async support ever lands.
     #
     # Scope of the fix: default-root unit tests and before_setup re-rooters

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.alpha1"
+  VERSION = "2.0.0.beta2"
 end

data/lib/snap_diff.rb

@@ -1,7 +1,30 @@
 # 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.
+module SnapDiff
+  DualInstallError = Class.new(StandardError)
+
+  # @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,12 +34,13 @@
 # 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/errors"
 require "snap_diff/config"
 
 # Forward-looking namespace for the gem, per ADR-004.
@@ -27,22 +51,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 +88,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.alpha1
+  version: 2.0.0.beta2
 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
@@ -148,12 +149,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