snap_diff-capybara 2.0.0.alpha1 → 2.0.0.beta2

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

@@ -6,7 +6,10 @@
 # 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 Comparison struct and LOADED_DRIVERS
-# keep their legacy names and are defined by snap_diff/comparison.rb itself.
+# 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).
 require "snap_diff/comparison"
 require "snap_diff/legacy_shims"

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

@@ -1,107 +1,5 @@
 # frozen_string_literal: true
 
-class Region
-  attr_accessor :x, :y, :width, :height
-
-  def initialize(x, y, width, height)
-    @x, @y, @width, @height = x, y, width, height
-  end
-
-  def self.from_edge_coordinates(left, top, right, bottom)
-    return nil unless left && top && right && bottom
-    return nil if right < left || bottom < top
-
-    Region.new(left, top, right - left, bottom - top)
-  end
-
-  def to_edge_coordinates
-    [left, top, right, bottom]
-  end
-
-  def to_top_left_corner_coordinates
-    [x, y, width, height]
-  end
-
-  def top
-    y
-  end
-
-  def bottom
-    y + height
-  end
-
-  def left
-    x
-  end
-
-  def right
-    x + width
-  end
-
-  def size
-    return 0 if width < 0 || height < 0
-
-    result = width * height
-    result.zero? ? 1 : result
-  end
-
-  def to_a
-    [@x, @y, @width, @height]
-  end
-
-  def find_intersect_with(region)
-    return nil unless intersect?(region)
-
-    new_left = [x, region.x].max
-    new_top = [y, region.y].max
-
-    Region.new(new_left, new_top, [right, region.right].min - new_left, [bottom, region.bottom].min - new_top)
-  end
-
-  def intersect?(region)
-    left <= region.right && right >= region.left && top <= region.bottom && bottom >= region.top
-  end
-
-  def move_by(right_by, down_by)
-    Region.new(x + right_by, y + down_by, width, height)
-  end
-
-  def find_relative_intersect(region)
-    intersect = find_intersect_with(region)
-    return nil unless intersect
-
-    intersect.move_by(-x, -y)
-  end
-
-  def cover?(x, y)
-    x.between?(left, right) && y.between?(top, bottom)
-  end
-
-  def empty?
-    width.zero? || height.zero?
-  end
-
-  def blank?
-    empty?
-  end
-
-  def present?
-    !empty?
-  end
-
-  def inspect
-    "Region(x: #{x}, y: #{y}, width: #{width}, height: #{height})"
-  end
-
-  # need to add this method to make it work with assert_equal
-  def ==(other)
-    case other
-    when Region
-      x == other.x && y == other.y && width == other.width && height == other.height
-    when Array
-      to_a == other
-    else
-      false
-    end
-  end
-end
+# Forwarder (ADR-008 step 3): Region now lives at SnapDiff::Region;
+# snap_diff/region also defines the eager top-level `Region` alias.
+require "snap_diff/region"

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

@@ -1,109 +1,7 @@
 # frozen_string_literal: true
 
-require "snap_diff/annotation_service"
-# Defines the Capybara::Screenshot::Diff namespace this file reopens.
+# 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.
+require "snap_diff/reporters/default"
 require "snap_diff/legacy_shims"
-
-module Capybara::Screenshot::Diff
-  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/capybara_screenshot_diff/screenshot_assertion.rb

@@ -6,49 +6,37 @@ require "snap_diff/reporting"
 # warnings) via snap_diff/legacy_shims' const_missing since v2 step 6.
 require "snap_diff/legacy_shims"
 
-# CapybaraScreenshotDiff's module methods cover two lifecycles with
-# different scopes, kept separate below:
-#
-# - Session lifecycle: thread-local, per-test. The AssertionRegistry holds
-#   the assertions and screenshot names of the test running on this thread;
-#   `reset` clears it between tests.
-# - Reporter lifecycle: process-global, suite-long. Owned by
-#   SnapDiff::Reporting; the methods here are thin public shims over it.
-#
-# `reset` is the one deliberate bridge between the two: a finished test's
-# assertions are handed to the reporters before the registry is cleared.
+# Since ADR-008 step 6 every method here is a thin forwarder; the canonical
+# homes are SnapDiff (session lifecycle: per-test, `SnapDiff.session` and
+# friends) and SnapDiff::Reporting (reporter lifecycle: process-global,
+# suite-long). Names, arities and object identities are unchanged -- this
+# module stays as the compatibility surface for existing consumers.
 module CapybaraScreenshotDiff
   class << self
     require "forwardable"
     extend Forwardable
 
-    # --- Session lifecycle (thread-local, per-test) ---
+    # --- Session lifecycle (per-test) -> SnapDiff ---
 
     def registry
-      Thread.current[:capybara_screenshot_diff_registry] ||= SnapDiff::AssertionRegistry.new
+      SnapDiff.session
     end
 
     def_delegators :registry, :add_assertion, :assertions, :assertions_present?,
       :failed_assertions, :record_new_screenshot, :new_screenshots,
       :new_screenshots_present?, :screenshot_namer, :verify
 
+    # Written out rather than def_delegators so the arities stay 0 (a
+    # Forwardable-generated method takes *args, **kwargs, &block).
     def reset
-      notify_reporters(registry.assertions)
-      registry.reset
+      SnapDiff.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 pending_screenshots_message
-      return unless ::Capybara::Screenshot::Diff.pending_if_new && new_screenshots_present?
-
-      "No baseline for: #{new_screenshots.join(", ")}. Commit the captured screenshots to record them."
+      SnapDiff.pending_screenshots_message
     end
 
-    # --- Reporter lifecycle (process-global, suite-long) ---
+    # --- Reporter lifecycle (process-global, suite-long) -> SnapDiff::Reporting ---
 
     def reporters
       SnapDiff::Reporting.reporters

data/lib/capybara_screenshot_diff.rb

@@ -22,19 +22,25 @@ require "capybara/screenshot/diff/screenshot_matcher"
 require "capybara/screenshot/diff/reporters/default"
 
 require "capybara_screenshot_diff/error_with_filtered_backtrace"
+require "snap_diff/errors"
 
 module CapybaraScreenshotDiff
   # RED_RGBA / ORANGE_RGBA moved to SnapDiff (snap_diff/annotation_service)
   # so the bare "snap_diff" entry gets them too; the old names resolve via
   # snap_diff/legacy_shims with a deprecation warning.
 
-  class CapybaraScreenshotDiffError < SnapDiff::ErrorWithFilteredBacktrace; end
+  # ADR-008 step 2: the error classes moved to SnapDiff (snap_diff/errors).
+  # These are EAGER same-object aliases -- deliberately not const_missing
+  # shims -- so rescue-by-old-name and defined?/const_defined? feature
+  # detection keep working exactly as before (const_defined? never
+  # triggers const_missing).
+  CapybaraScreenshotDiffError = SnapDiff::Error
 
-  class ExpectationNotMet < CapybaraScreenshotDiffError; end
+  ExpectationNotMet = SnapDiff::ExpectationNotMet
 
-  class UnstableImage < CapybaraScreenshotDiffError; end
+  UnstableImage = SnapDiff::UnstableImage
 
-  class WindowSizeMismatchError < SnapDiff::ErrorWithFilteredBacktrace; end
+  WindowSizeMismatchError = SnapDiff::WindowSizeMismatchError
 end
 
 require "capybara_screenshot_diff/dsl"

data/lib/snap_diff/area_calculator.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-# Region has not moved yet (ADR-004 v2 scoping: it's already unnamespaced,
-# no v2.0 move needed).
-require "capybara/screenshot/diff/region"
+require "snap_diff/region"
 
 module SnapDiff
   class AreaCalculator

data/lib/snap_diff/browser_helpers.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-# Region has not moved yet (ADR-004 v2 scoping: it's already unnamespaced,
-# no v2.0 move needed) so this is an absolute require, not require_relative.
-require "capybara/screenshot/diff/region"
+require "snap_diff/region"
 
 module SnapDiff
   module BrowserHelpers

data/lib/snap_diff/capture/viewport.rb

@@ -9,24 +9,23 @@ module SnapDiff
     # Called exactly once per capture, before the screenshoter runs and outside
     # any stability retry loop. Today it only validates the window size
     # (raise-only, never resizes) — the same guard ScreenshotMatcher carried
-    # inline before. v3 hangs scroll-position preservation and element-anchored
-    # capture off this seam via the +anchor+ parameter without touching callers.
+    # inline before. When v3 adds scroll preservation / element-anchored
+    # capture it designs its own parameters here; adding an optional kwarg
+    # later is non-breaking, so none is reserved up front.
     module Viewport
       module_function
 
       # @param expected_window_size [Array(Integer, Integer), nil] the configured window size
-      # @param anchor [Object, nil] reserved for v3 (scroll preservation /
-      #   element-anchored capture); accepted but unused today.
-      # @raise [CapybaraScreenshotDiff::WindowSizeMismatchError] if the browser
+      # @raise [SnapDiff::WindowSizeMismatchError] if the browser
       #   window does not match the expected size.
-      def prepare!(expected_window_size, anchor: nil)
+      def prepare!(expected_window_size)
         return unless BrowserHelpers.window_size_is_wrong?(expected_window_size)
 
         current_size = BrowserHelpers.selenium? ?
           BrowserHelpers.session.driver.browser.manage.window.size.to_s :
           "unknown"
 
-        raise CapybaraScreenshotDiff::WindowSizeMismatchError.new(<<~ERROR.chomp, caller)
+        raise SnapDiff::WindowSizeMismatchError.new(<<~ERROR.chomp, caller)
           Window size mismatch detected!
           Expected: #{expected_window_size.inspect}
           Actual: #{current_size}

data/lib/snap_diff/comparison.rb

@@ -6,28 +6,7 @@ require "fileutils"
 require "snap_diff/comparison_result"
 require "snap_diff/drivers"
 require "snap_diff/image_preprocessor"
-require "capybara/screenshot/diff/reporters/default"
-
-# The internal images-holder struct and the driver cache keep their legacy
-# Capybara::Screenshot::Diff homes for now: SnapDiff::Comparison is the
-# comparison class below (ex-ImageCompare), so the struct cannot take the
-# same name. Its SnapDiff home arrives only when it is folded into
-# Comparison as a nested value (v2 design section 2) -- renaming it here
-# would exceed step 5's two approved renames.
-module Capybara
-  module Screenshot
-    module Diff
-      LOADED_DRIVERS = {}
-
-      # Holds the two images (and their paths/options/driver) being compared.
-      class Comparison < Struct.new(:new_image, :base_image, :options, :driver, :new_image_path, :base_image_path)
-        def skip_area
-          options[:skip_area]
-        end
-      end
-    end
-  end
-end
+require "snap_diff/reporters/default"
 
 module SnapDiff
   # Handles comparison of two images with a focus on performance and accuracy.
@@ -53,6 +32,14 @@ module SnapDiff
   # - Only performing expensive operations when absolutely necessary
   # - Maintaining high accuracy for complex comparisons
   class Comparison
+    # Holds the two images (and their paths/options/driver) being compared
+    # (ADR-008 step 5: ex-Capybara::Screenshot::Diff::Comparison struct).
+    Images = Struct.new(:new_image, :base_image, :options, :driver, :new_image_path, :base_image_path) do
+      def skip_area
+        options[:skip_area]
+      end
+    end
+
     TOLERABLE_OPTIONS = [:tolerance, :color_distance_limit, :shift_distance_limit, :area_size_limit].freeze
 
     attr_reader :driver, :driver_options
@@ -136,7 +123,7 @@ module SnapDiff
 
     def load_images_and_build_comparison(base_path, new_path, options)
       base_img, new_img = driver.load_images(base_path, new_path)
-      Capybara::Screenshot::Diff::Comparison.new(new_img, base_img, options, driver, new_path, base_path)
+      Images.new(new_img, base_img, options, driver, new_path, base_path)
     end
 
     def image_preprocessor
@@ -155,7 +142,7 @@ module SnapDiff
 
     # Analyzes the comparison and determines if images are different.
     #
-    # @param comparison [Capybara::Screenshot::Diff::Comparison] The comparison object containing images to analyze.
+    # @param comparison [Comparison::Images] The comparison object containing images to analyze.
     # @param quick_mode [Boolean] When true, performs minimal checks and returns early.
     #   In quick mode, returns [is_equal, difference] where:
     #   - is_equal is true if images are considered equal
@@ -195,7 +182,7 @@ module SnapDiff
 
     def build_reporter
       current_difference = difference || build_null_difference
-      Capybara::Screenshot::Diff::Reporters::Default.new(current_difference)
+      Reporters::Default.new(current_difference)
     end
 
     # Loads and preprocesses images for detailed comparison.
@@ -203,7 +190,7 @@ module SnapDiff
     # This method is responsible for:
     # 1. Loading both images using the configured driver
     # 2. Applying any necessary preprocessing (cropping, normalization)
-    # 3. Creating a Capybara::Screenshot::Diff::Comparison object that holds the image data
+    # 3. Creating a Comparison::Images object that holds the image data
     #
     # @param base_path [String,Pathname] Path to the baseline/reference image
     # @param new_path [String,Pathname] Path to the new/candidate image
@@ -211,7 +198,7 @@ module SnapDiff
     #   - :crop [Array<Integer>] Optional crop area [x, y, width, height]
     #   - :skip_area [Array<Array>] Areas to exclude from comparison
     #   - :tolerance [Numeric] Color tolerance threshold
-    # @return [Capybara::Screenshot::Diff::Comparison] Prepared comparison object ready for analysis
+    # @return [Comparison::Images] Prepared comparison object ready for analysis
     # @raise [ArgumentError] If image files are invalid or unreadable
     def load_comparison(base_path, new_path, options)
       comparison = load_images_and_build_comparison(base_path, new_path, options)
@@ -219,7 +206,7 @@ module SnapDiff
     end
 
     def build_null_difference(failed_by = nil)
-      comparison = Capybara::Screenshot::Diff::Comparison.new(nil, nil, driver_options, driver, image_path, base_image_path).freeze
+      comparison = Images.new(nil, nil, driver_options, driver, image_path, base_image_path).freeze
       ComparisonResult.build_null(comparison, base_image_path, image_path, failed_by)
     end