capybara-screenshot-diff 1.15.0 → 2.0.0.alpha1

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

@@ -1,230 +1,12 @@
 # frozen_string_literal: true
 
-require "pathname"
-require "fileutils"
-
-require "capybara/screenshot/diff/difference"
-require "capybara/screenshot/diff/drivers"
-require "capybara/screenshot/diff/image_preprocessor"
-require "capybara/screenshot/diff/reporters/default"
-
-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
-
-      # Handles comparison of two images with a focus on performance and accuracy.
-      #
-      # This class implements a multi-layered optimization strategy for image comparison:
-      #
-      # 1. Early File-based Checks (Fastest):
-      #    - Verifies both images exist (raises ArgumentError if not)
-      #    - Compares file sizes (different sizes → different images)
-      #    - Performs byte-by-byte comparison for identical files (exact match)
-      #
-      # 2. Quick Comparison (Fast):
-      #    - Compares image dimensions (different dimensions → different images)
-      #    - Performs pixel-by-pixel comparison if dimensions match
-      #
-      # 3. Detailed Analysis (Slower):
-      #    - Only performed if quick comparison finds differences
-      #    - Handles anti-aliasing, color tolerance, and shift detection
-      #    - Respects skip_area and other comparison parameters
-      #
-      # This layered approach ensures optimal performance by:
-      # - Using the fastest possible method for early rejection
-      # - Only performing expensive operations when absolutely necessary
-      # - Maintaining high accuracy for complex comparisons
-      class ImageCompare
-        TOLERABLE_OPTIONS = [:tolerance, :color_distance_limit, :shift_distance_limit, :area_size_limit].freeze
-
-        attr_reader :driver, :driver_options
-        attr_reader :image_path, :base_image_path
-        attr_reader :difference, :error_message
-
-        def initialize(image_path, base_image_path, options = {})
-          @image_path = Pathname.new(image_path)
-          @base_image_path = Pathname.new(base_image_path)
-
-          ensure_files_exist!
-
-          @driver_options = options.freeze
-          @driver = Drivers.for(@driver_options)
-          @without_tolerable_options = (driver_options.keys & TOLERABLE_OPTIONS).empty?
-        end
-
-        # Performs a quick comparison of two image files.
-        #
-        # This method is optimized for speed and will return as soon as a difference is found.
-        # It's used for fast rejection before performing more expensive comparisons.
-        #
-        # @return [Boolean]
-        #   - `true` if images are exactly identical (byte-for-byte match)
-        #   - `false` if images are different or if a quick difference is detected
-        #
-        # @note This method will raise ArgumentError if either image file is missing.
-        def quick_equal?
-          if base_image_path.size == image_path.size
-            return true if files_identical?(base_image_path, image_path)
-          end
-
-          result, difference = find_difference(quick_mode: true)
-          self.difference = difference
-          result
-        end
-
-        def ensure_files_exist!
-          raise ArgumentError, "There is no original (base) screenshot located at #{@base_image_path}" unless @base_image_path.exist?
-          raise ArgumentError, "There is no new screenshot located at #{@image_path}" unless @image_path.exist?
-        end
-
-        # Determines if the images are different according to the comparison rules.
-        #
-        # This method performs a full comparison if not already done, including any
-        # configured tolerances for color differences and shift distances.
-        #
-        # @return [Boolean]
-        #   - `true` if the images are different beyond configured tolerances
-        #   - `false` if the images are considered identical
-        #
-        # @see #processed
-        # @see #analyze_difference
-        def different?
-          processed.difference.different?
-        end
-
-        def dimensions_changed?
-          difference.failed_by&.[](:different_dimensions)
-        end
-
-        def reporter
-          @reporter ||= build_reporter
-        end
-
-        def processed?
-          !!difference
-        end
-
-        def processed
-          self.difference = find_difference(quick_mode: false) unless processed?
-          @error_message ||= reporter.generate
-          self
-        end
-
-        private
-
-        def without_tolerable_options?
-          @without_tolerable_options
-        end
-
-        def load_images_and_build_comparison(base_path, new_path, options)
-          base_img, new_img = driver.load_images(base_path, new_path)
-          Comparison.new(new_img, base_img, options, driver, new_path, base_path)
-        end
-
-        def image_preprocessor
-          @image_preprocessor ||= ImagePreprocessor.new(driver, driver_options)
-        end
-
-        def find_difference(quick_mode: false)
-          # Validate images exist
-          return build_null_difference("missing_image") unless images_exist?
-
-          # Create comparison with preprocessed images
-          comparison = load_comparison(base_image_path, image_path, driver_options)
-
-          analyze_difference(comparison, quick_mode: quick_mode)
-        end
-
-        # Analyzes the comparison and determines if images are different.
-        #
-        # @param comparison [Comparison] 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
-        #   - difference is a Difference object or nil
-        #   When false, returns a Difference object directly.
-        # @return [Array, Difference] Result format depends on quick_mode parameter.
-        def analyze_difference(comparison, quick_mode: true)
-          # Handle dimension differences
-          unless driver.same_dimension?(comparison)
-            result = Difference.build_null(comparison, comparison.base_image_path, comparison.new_image_path, {different_dimensions: true})
-            return quick_mode ? [false, result] : result
-          end
-
-          # Handle identical pixels
-          if driver.same_pixels?(comparison)
-            result = Difference.build_null(comparison, comparison.base_image_path, comparison.new_image_path)
-            return quick_mode ? [true, result] : result
-          end
-
-          # Handle early return for non-tolerable options
-          if quick_mode && without_tolerable_options?
-            return [false, nil]
-          end
-
-          # Process difference region
-          region = driver.find_difference_region(comparison)
-
-          # Only create a proper difference object if we've completed the comparison
-          quick_mode ? [!region.different?, region] : region
-        end
-
-        def difference=(new_difference)
-          @error_message = nil
-          @reporter = nil
-          @difference = new_difference
-        end
-
-        def build_reporter
-          current_difference = difference || build_null_difference
-          Reporters::Default.new(current_difference)
-        end
-
-        # Loads and preprocesses images for detailed comparison.
-        #
-        # This method is responsible for:
-        # 1. Loading both images using the configured driver
-        # 2. Applying any necessary preprocessing (cropping, normalization)
-        # 3. Creating a Comparison 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
-        # @param options [Hash] Comparison options including:
-        #   - :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 [Comparison] 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)
-          image_preprocessor.process_comparison(comparison)
-        end
-
-        def build_null_difference(failed_by = nil)
-          comparison = Comparison.new(nil, nil, driver_options, driver, image_path, base_image_path).freeze
-          Difference.build_null(comparison, base_image_path, image_path, failed_by)
-        end
-
-        # Check if both images exist
-        def images_exist?
-          base_image_path.exist? && image_path.exist?
-        end
-
-        # Check if files are identical by content
-        def files_identical?(file1, file2)
-          FileUtils.compare_file(file1, file2)
-        rescue SystemCallError, IOError
-          false
-        end
-      end
-    end
-  end
-end
+# Forwarder (ADR-004 v2 step 6): the comparison class lives at
+# SnapDiff::Comparison (ex-ImageCompare); the old name now resolves lazily
+# via snap_diff/legacy_shims' const_missing, with a deprecation warning.
+# 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.
+require "snap_diff/comparison"
+require "snap_diff/legacy_shims"

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

@@ -1,72 +1,7 @@
 # frozen_string_literal: true
 
-module Capybara
-  module Screenshot
-    module Diff
-      # Handles image preprocessing operations (skip_area and median filtering)
-      #
-      # This class applies preprocessing filters to images before comparison,
-      # such as masking specific regions (skip_area) or applying noise reduction.
-      # It's designed to work with either direct image objects or with options.
-      class ImagePreprocessor
-        attr_reader :driver, :options
-
-        def initialize(driver, options = {})
-          @driver = driver
-          @options = options
-        end
-
-        # Process a comparison object directly
-        # This allows reusing the comparison's existing options
-        # @param [Comparison] comparison the comparison object
-        # @return [Comparison] the comparison object
-        def process_comparison(comparison)
-          # Process both images
-          comparison.base_image = process_image(comparison.base_image, comparison.base_image_path)
-          comparison.new_image = process_image(comparison.new_image, comparison.new_image_path)
-
-          comparison
-        end
-
-        private
-
-        def process_image(image, path)
-          result = image
-          result = apply_skip_area(result) if skip_area
-          result = apply_median_filter(result, path) if median_filter_window_size
-          result
-        end
-
-        def apply_skip_area(image)
-          skip_area.reduce(image) do |result, region|
-            driver.add_black_box(result, region)
-          end
-        end
-
-        def apply_median_filter(image, path)
-          if driver.supports?(:filter_image_with_median)
-            driver.filter_image_with_median(image, median_filter_window_size)
-          else
-            warn_about_skipped_median_filter(path)
-            image
-          end
-        end
-
-        def warn_about_skipped_median_filter(path)
-          warn(
-            "[capybara-screenshot-diff] Median filter has been skipped for #{path} " \
-            "because it is not supported by #{driver.class}"
-          )
-        end
-
-        def skip_area
-          options[:skip_area]
-        end
-
-        def median_filter_window_size
-          options[:median_filter_window_size]
-        end
-      end
-    end
-  end
-end
+# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Diff::ImagePreprocessor
+# now resolves lazily via snap_diff/legacy_shims' const_missing, with a
+# deprecation warning pointing at SnapDiff::ImagePreprocessor.
+require "snap_diff/image_preprocessor"
+require "snap_diff/legacy_shims"

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

@@ -1,19 +1,14 @@
 # frozen_string_literal: true
 
+require "snap_diff/os"
+
+# Deliberately EAGER and silent (v2 step 6 exception): Os is an advertised
+# entry-point constant probed with Object.const_defined? by
+# support_load_probe_test.rb, and const_defined? never triggers
+# const_missing -- a lazy shim would break that contract. See
+# snap_diff/legacy_shims.rb for the full exception list.
 module Capybara
   module Screenshot
-    module Os
-      ON_WINDOWS = !!(RbConfig::CONFIG["host_os"] =~ /mswin|mingw|cygwin/)
-      ON_MAC = !!(RbConfig::CONFIG["host_os"] =~ /darwin/)
-      ON_LINUX = !!(RbConfig::CONFIG["host_os"] =~ /linux/)
-
-      def self.name
-        return "windows" if ON_WINDOWS
-        return "macos" if ON_MAC
-        return "linux" if ON_LINUX
-
-        "unknown"
-      end
-    end
+    Os = SnapDiff::Os
   end
 end

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

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
-require "capybara/screenshot/diff/annotation_service"
+require "snap_diff/annotation_service"
+# Defines the Capybara::Screenshot::Diff namespace this file reopens.
+require "snap_diff/legacy_shims"
 
 module Capybara::Screenshot::Diff
   module Reporters
@@ -9,7 +11,7 @@ module Capybara::Screenshot::Diff
 
       def initialize(difference)
         @difference = difference
-        @annotation_service = AnnotationService.new(difference)
+        @annotation_service = SnapDiff::AnnotationService.new(difference)
       end
 
       def annotated_image_path
@@ -75,7 +77,7 @@ module Capybara::Screenshot::Diff
 
       def build_error_message
         [
-          "(#{difference.inspect})",
+          "(#{difference.to_h.to_json})",
           image_path.to_path,
           annotated_base_image_path.to_path,
           annotated_image_path.to_path,

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

@@ -1,131 +1,7 @@
 # frozen_string_literal: true
 
-require "capybara_screenshot_diff/snap_manager"
-require_relative "screenshoter"
-require_relative "stable_screenshoter"
-require_relative "browser_helpers"
-require_relative "vcs"
-require_relative "area_calculator"
-
-module Capybara
-  module Screenshot
-    module Diff
-      class ScreenshotMatcher
-        attr_reader :screenshot_full_name, :driver_options, :screenshot_format
-
-        def initialize(screenshot_full_name, options = {})
-          @screenshot_full_name = screenshot_full_name
-          @driver_options = Diff.default_options.merge(options)
-
-          @screenshot_format = @driver_options[:screenshot_format]
-          @snapshot = CapybaraScreenshotDiff::SnapManager.snapshot(screenshot_full_name, @screenshot_format)
-        end
-
-        def build_screenshot_assertion(skip_stack_frames: 0)
-          check_window_size!
-          prepare_screenshot_options
-          check_base_screenshot
-
-          capture_options, comparison_options = extract_capture_and_comparison_options!(driver_options)
-
-          capture_screenshot(capture_options, comparison_options)
-
-          # 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)
-            return
-          end
-
-          create_screenshot_assertion(skip_stack_frames + 1, comparison_options)
-        end
-
-        # Captures a screenshot without comparing it to a baseline.
-        def capture
-          check_window_size!
-          prepare_screenshot_options
-
-          capture_options, comparison_options = extract_capture_and_comparison_options!(driver_options)
-
-          @snapshot.manager.create_output_directory_for(@snapshot.path)
-          capture_screenshot(capture_options, comparison_options)
-        end
-
-        private
-
-        def need_to_compare?
-          @snapshot.base_path.exist?
-        end
-
-        def check_window_size!
-          if BrowserHelpers.window_size_is_wrong?(Screenshot.window_size)
-            current_size = BrowserHelpers.selenium? ?
-              BrowserHelpers.session.driver.browser.manage.window.size.to_s :
-              "unknown"
-
-            raise CapybaraScreenshotDiff::WindowSizeMismatchError.new(<<~ERROR.chomp, caller)
-              Window size mismatch detected!
-              Expected: #{Screenshot.window_size.inspect}
-              Actual: #{current_size}
-              
-              Screenshots cannot be compared when window sizes don't match.
-              Please ensure the browser window is properly sized before taking screenshots.
-            ERROR
-          end
-        end
-
-        def prepare_screenshot_options
-          area_calculator = AreaCalculator.new(driver_options.delete(:crop), driver_options[:skip_area])
-
-          driver_options[:crop] = area_calculator.calculate_crop
-          driver_options[:skip_area] = area_calculator.calculate_skip_area
-          driver_options[:driver] = Drivers.for(driver_options[:driver])
-        end
-
-        def check_base_screenshot
-          @snapshot.checkout_base_screenshot
-
-          if Capybara::Screenshot::Diff.fail_if_new && !@snapshot.base_path.exist?
-            raise CapybaraScreenshotDiff::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
-            ERROR
-          end
-        end
-
-        def capture_screenshot(capture_options, comparison_options)
-          screenshoter = if capture_options[:stability_time_limit]
-            StableScreenshoter.new(capture_options, comparison_options)
-          else
-            Diff.screenshoter.new(capture_options, comparison_options)
-          end
-          screenshoter.take_comparison_screenshot(@snapshot)
-        end
-
-        def create_screenshot_assertion(skip_stack_frames, comparison_options)
-          assertion = CapybaraScreenshotDiff::ScreenshotAssertion.new(screenshot_full_name)
-          assertion.caller = caller(skip_stack_frames + 1)
-          assertion.compare = ImageCompare.new(@snapshot.path, @snapshot.base_path, comparison_options)
-          assertion
-        end
-
-        def extract_capture_and_comparison_options!(driver_options = {})
-          [
-            {
-              # screenshot options
-              capybara_screenshot_options: driver_options[:capybara_screenshot_options],
-              crop: driver_options.delete(:crop),
-              # delivery options
-              screenshot_format: driver_options[:screenshot_format],
-              # stability options
-              stability_time_limit: driver_options.delete(:stability_time_limit),
-              wait: driver_options.delete(:wait)
-            },
-            driver_options
-          ]
-        end
-      end
-    end
-  end
-end
+# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Diff::ScreenshotMatcher
+# now resolves lazily via snap_diff/legacy_shims' const_missing, with a
+# deprecation warning pointing at SnapDiff::ScreenshotMatcher.
+require "snap_diff/screenshot_matcher"
+require "snap_diff/legacy_shims"

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

@@ -1,129 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "os"
-require_relative "browser_helpers"
-
-module Capybara
-  module Screenshot
-    class Screenshoter
-      attr_reader :capture_options, :driver
-
-      # @param capture_options [Hash] Options for capturing (window_size, wait, etc.)
-      # @param comparison_options [Hash] Options for image comparison (driver, tolerance, etc.)
-      def initialize(capture_options, comparison_options = {})
-        @capture_options = capture_options
-        @driver = Diff::Drivers.for(comparison_options)
-      end
-
-      def crop
-        @capture_options[:crop]
-      end
-
-      def wait
-        @capture_options[:wait]
-      end
-
-      def capybara_screenshot_options
-        @capture_options[:capybara_screenshot_options] || {}
-      end
-
-      # Try to get screenshot from browser.
-      # On `stability_time_limit` it checks that page stop updating by comparison several screenshot attempts
-      # On reaching `wait` limit then it has been failed. On failing we annotate screenshot attempts to help to debug
-      def take_comparison_screenshot(snapshot)
-        capture_screenshot_at(snapshot)
-        snapshot.cleanup_attempts!
-      end
-
-      PNG_EXTENSION = ".png"
-
-      def take_screenshot(screenshot_path)
-        blurred_input = prepare_page_for_screenshot(timeout: wait)
-
-        # Take browser screenshot and save
-        save_and_process_screenshot(screenshot_path)
-
-        blurred_input&.click
-      end
-
-      def process_screenshot(stored_path, screenshot_path)
-        screenshot_image = driver.from_file(stored_path)
-
-        # TODO(uwe): Remove when chromedriver takes right size screenshots
-        # TODO: Adds tests when this case is true
-        screenshot_image = resize_if_needed(screenshot_image) if selenium_with_retina_screen?
-        # ODOT
-
-        screenshot_image = driver.crop(crop, screenshot_image) if crop
-
-        driver.save_image_to(screenshot_image, screenshot_path)
-      end
-
-      def notice_how_to_avoid_this
-        unless defined?(@_csd_retina_warned)
-          warn "Halving retina screenshot.  " \
-                 'You should add "force-device-scale-factor=1" to your Chrome chromeOptions args.'
-          @_csd_retina_warned = true
-        end
-      end
-
-      def prepare_page_for_screenshot(timeout:)
-        wait_images_loaded(timeout: timeout) if timeout
-
-        blurred_input = BrowserHelpers.blur_from_focused_element if Screenshot.blur_active_element
-
-        BrowserHelpers.hide_caret if Screenshot.hide_caret
-        BrowserHelpers.disable_animations if Screenshot.disable_animations
-
-        blurred_input
-      end
-
-      def wait_images_loaded(timeout:)
-        return unless timeout
-
-        deadline_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
-        loop do
-          pending_image = BrowserHelpers.pending_image_to_load
-          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)
-          end
-
-          sleep 0.025
-        end
-      end
-
-      private
-
-      def save_and_process_screenshot(screenshot_path)
-        tmpfile = Tempfile.new([screenshot_path.basename.to_s, PNG_EXTENSION])
-        BrowserHelpers.session.save_screenshot(tmpfile.path, **capybara_screenshot_options)
-        # Load saved screenshot and pre-process it
-        process_screenshot(tmpfile.path, screenshot_path)
-      ensure
-        tmpfile&.close!
-      end
-
-      def capture_screenshot_at(snapshot)
-        take_screenshot(snapshot.next_attempt_path!)
-
-        snapshot.commit_last_attempt
-      end
-
-      def resize_if_needed(saved_image)
-        expected_image_width = Screenshot.window_size[0]
-        return saved_image if driver.width_for(saved_image) < expected_image_width * 2
-
-        notice_how_to_avoid_this
-
-        new_height = expected_image_width * driver.height_for(saved_image) / driver.width_for(saved_image)
-        driver.resize_image_to(saved_image, expected_image_width, new_height)
-      end
-
-      def selenium_with_retina_screen?
-        Os::ON_MAC && BrowserHelpers.selenium? && Screenshot.window_size
-      end
-    end
-  end
-end
+# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Screenshoter now
+# resolves lazily via snap_diff/legacy_shims' const_missing, with a
+# deprecation warning pointing at SnapDiff::Screenshoter.
+require "snap_diff/screenshoter"
+require "snap_diff/legacy_shims"