capybara-screenshot-diff 1.10.3.1 → 1.13.0

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

@@ -1,17 +1,41 @@
 # frozen_string_literal: true
 
+require "pathname"
+require "fileutils"
+
 require "capybara/screenshot/diff/comparison"
+require "capybara/screenshot/diff/image_preprocessor"
+require "capybara/screenshot/diff/difference_finder"
+require "capybara/screenshot/diff/reporters/default"
 
 module Capybara
   module Screenshot
     module Diff
       LOADED_DRIVERS = {}
 
-      # Compare two image and determine if they are equal, different, or within some comparison
-      # range considering color values and difference area size.
+      # 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
@@ -20,41 +44,48 @@ module Capybara
           @image_path = Pathname.new(image_path)
           @base_image_path = Pathname.new(base_image_path)
 
-          @driver_options = options.dup
+          ensure_files_exist!
 
+          @driver_options = options.freeze
           @driver = Drivers.for(@driver_options)
         end
 
-        # Compare the two image files and return `true` or `false` as quickly as possible.
-        # Return falsely if the old file does not exist or the image dimensions do not match.
+        # 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?
-          require_images_exists!
-
-          # NOTE: This is very fuzzy logic, but so far it's helps to support current performance.
-          return true if new_file_size == old_file_size
-
-          comparison = load_and_process_images
-
-          unless driver.same_dimension?(comparison)
-            self.difference = build_failed_difference(comparison, {different_dimensions: true})
-            return false
+          if base_image_path.size == image_path.size
+            return true if files_identical?(base_image_path, image_path)
           end
 
-          if driver.same_pixels?(comparison)
-            self.difference = build_no_difference(comparison)
-            return true
-          end
-
-          # NOTE: Could not make any difference to be tolerable, so skip and return as not equal.
-          return false if without_tolerable_options?
-
-          self.difference = driver.find_difference_region(comparison)
+          result, difference = find_difference(quick_mode: true)
+          self.difference = difference
+          result
+        end
 
-          !difference.different?
+        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
 
-        # Compare the two image referenced by this object, and return `true` if they are different,
-        # and `false` if they are the same.
+        # 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 DifferenceFinder
         def different?
           processed.difference.different?
         end
@@ -64,10 +95,7 @@ module Capybara
         end
 
         def reporter
-          @reporter ||= begin
-            current_difference = difference || build_no_difference(nil)
-            Capybara::Screenshot::Diff::Reporters::Default.new(current_difference)
-          end
+          @reporter ||= build_reporter
         end
 
         def processed?
@@ -75,122 +103,83 @@ module Capybara
         end
 
         def processed
-          self.difference = find_difference unless processed?
+          self.difference = find_difference(quick_mode: false) unless processed?
           @error_message ||= reporter.generate
           self
         end
 
         private
 
-        def find_difference
-          require_images_exists!
-
-          comparison = load_and_process_images
-
-          unless driver.same_dimension?(comparison)
-            return build_failed_difference(comparison, {different_dimensions: true})
-          end
-
-          if driver.same_pixels?(comparison)
-            build_no_difference(comparison)
-          else
-            driver.find_difference_region(comparison)
-          end
-        end
-
-        def require_images_exists!
-          raise ArgumentError, "There is no original (base) screenshot version to compare, located: #{base_image_path}" unless base_image_path.exist?
-          raise ArgumentError, "There is no new screenshot version to compare, located: #{image_path}" unless image_path.exist?
-        end
-
-        def difference=(new_difference)
-          @error_message = nil
-          @reporter = nil
-          @difference = new_difference
-        end
-
-        def image_files_exist?
-          @base_image_path.exist? && @image_path.exist?
+        def difference_finder
+          @difference_finder ||= DifferenceFinder.new(driver, driver_options)
         end
 
-        def without_tolerable_options?
-          (@driver_options.keys & TOLERABLE_OPTIONS).empty?
+        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 build_failed_difference(comparison, failed_by)
-          Difference.new(
-            nil,
-            {difference_level: nil, max_color_distance: 0},
-            comparison,
-            failed_by
-          )
+        def image_preprocessor
+          @image_preprocessor ||= ImagePreprocessor.new(driver, driver_options)
         end
 
-        def load_and_process_images
-          images = driver.load_images(base_image_path, image_path)
-          base_image, new_image = preprocess_images(images)
-          Comparison.new(new_image, base_image, @driver_options, driver, image_path, base_image_path)
-        end
+        def find_difference(quick_mode: false)
+          # Validate images exist
+          return build_null_difference("missing_image") unless images_exist?
 
-        def skip_area
-          @driver_options[:skip_area]
-        end
-
-        def median_filter_window_size
-          @driver_options[:median_filter_window_size]
-        end
+          # Create comparison with preprocessed images
+          comparison = load_comparison(base_image_path, image_path, driver_options)
 
-        def preprocess_images(images)
-          images.map { |image| preprocess_image(image) }
+          # Use difference finder to analyze the comparison
+          difference_finder.call(comparison, quick_mode: quick_mode)
         end
 
-        def preprocess_image(image)
-          result = image
-
-          if skip_area
-            result = ignore_skipped_area(result)
-          end
-
-          if median_filter_window_size
-            if driver.is_a?(Drivers::VipsDriver)
-              result = blur_image_by(image, median_filter_window_size)
-            else
-              warn(
-                "[capybara-screenshot-diff] Median filter has been skipped for #{image_path} " \
-                  "because it is not supported by #{driver.class.name}"
-              )
-            end
-          end
-
-          result
-        end
-
-        def blur_image_by(image, size)
-          driver.filter_image_with_median(image, size)
+        def difference=(new_difference)
+          @error_message = nil
+          @reporter = nil
+          @difference = new_difference
         end
 
-        def ignore_skipped_area(image)
-          skip_area&.reduce(image) { |memo, region| driver.add_black_box(memo, region) }
+        def build_reporter
+          current_difference = difference || build_null_difference
+          Reporters::Default.new(current_difference)
         end
 
-        def old_file_size
-          base_image_path.size
+        # 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 new_file_size
-          image_path.size
+        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
 
-        def build_no_difference(comparison = nil)
-          Difference.new(
-            nil,
-            {difference_level: nil, max_color_distance: 0},
-            comparison || build_comparison
-          ).freeze
+        # Check if both images exist
+        def images_exist?
+          base_image_path.exist? && image_path.exist?
         end
 
-        def build_comparison
-          Capybara::Screenshot::Diff::Comparison.new(nil, nil, driver_options, driver, image_path, base_image_path).freeze
+        # Check if files are identical by content
+        def files_identical?(file1, file2)
+          FileUtils.compare_file(file1, file2)
+        rescue SystemCallError, IOError
+          false
         end
       end
     end

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

@@ -0,0 +1,72 @@
+# 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

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

@@ -8,7 +8,8 @@ module Capybara::Screenshot::Diff
       def initialize(difference)
         @difference = difference
 
-        screenshot_format = difference.comparison.options[:screenshot_format] || comparison.new_image_path.extname.slice(1..-1)
+        ext = comparison.new_image_path.extname.delete_prefix(".")
+        screenshot_format = difference.comparison.options[:screenshot_format] || (ext unless ext.empty?) || "png"
         @annotated_image_path = comparison.new_image_path.sub_ext(".diff.#{screenshot_format}")
         @annotated_base_image_path = comparison.base_image_path.sub_ext(".diff.#{screenshot_format}")
         @heatmap_diff_path = comparison.new_image_path.sub_ext(".heatmap.diff.#{screenshot_format}")
@@ -32,6 +33,7 @@ module Capybara::Screenshot::Diff
       def clean_tmp_files
         annotated_base_image_path.unlink if annotated_base_image_path.exist?
         annotated_image_path.unlink if annotated_image_path.exist?
+        heatmap_diff_path.unlink if heatmap_diff_path.exist?
       end
 
       def build_error_for_different_dimensions
@@ -45,27 +47,23 @@ module Capybara::Screenshot::Diff
       def annotate_and_save_images
         save_annotation_for(new_image, annotated_image_path)
         save_annotation_for(base_image, annotated_base_image_path)
-        save_heatmap_diff if difference.meta[:diff_mask]
+        save_heatmap_diff if difference.diff_mask
       end
 
       def save_annotation_for(image, image_path)
         image = annotate_difference(image, difference.region)
-        image = annotate_skip_areas(image, difference.skip_area) if difference.skip_area
+        image = annotate_skip_areas(image, difference.comparison.skip_area) if difference.comparison.skip_area
 
         save(image, image_path.to_path)
       end
 
-      DIFF_COLOR = [255, 0, 0, 255].freeze
-
       def annotate_difference(image, region)
-        driver.draw_rectangles([image], region, DIFF_COLOR, offset: 1).first
+        driver.draw_rectangles([image], region, CapybaraScreenshotDiff::RED_RGBA, offset: 1).first
       end
 
-      SKIP_COLOR = [255, 192, 0, 255].freeze
-
       def annotate_skip_areas(image, skip_areas)
         skip_areas.reduce(image) do |memo, region|
-          driver.draw_rectangles([memo], region, SKIP_COLOR).first
+          driver.draw_rectangles([memo], region, CapybaraScreenshotDiff::ORANGE_RGBA).first
         end
       end
 
@@ -80,7 +78,8 @@ module Capybara::Screenshot::Diff
           "(#{difference.inspect})",
           image_path.to_path,
           annotated_base_image_path.to_path,
-          annotated_image_path.to_path
+          annotated_image_path.to_path,
+          heatmap_diff_path.to_path
         ].join(NEW_LINE)
       end
 
@@ -88,7 +87,7 @@ module Capybara::Screenshot::Diff
 
       def save_heatmap_diff
         merged_image = driver.merge(new_image, base_image)
-        highlighted_mask = driver.highlight_mask(difference.meta[:diff_mask], merged_image, color: DIFF_COLOR)
+        highlighted_mask = driver.highlight_mask(difference.diff_mask, merged_image, color: CapybaraScreenshotDiff::RED_RGBA)
 
         save(highlighted_mask, heatmap_diff_path.to_path)
       end

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

@@ -21,37 +21,94 @@ module Capybara
           @snapshot = CapybaraScreenshotDiff::SnapManager.snapshot(screenshot_full_name, @screenshot_format)
         end
 
-        def build_screenshot_matches_job
-          # TODO: Move this into screenshot stage, in order to re-evaluate coordinates after page updates
-          return if BrowserHelpers.window_size_is_wrong?(Screenshot.window_size)
+        def build_screenshot_assertion(skip_stack_frames: 0)
+          check_window_size!
+          prepare_screenshot_options
+          check_base_screenshot
 
-          # TODO: Move this into screenshot stage, in order to re-evaluate coordinates after page updates
-          area_calculator = AreaCalculator.new(driver_options.delete(:crop), driver_options[:skip_area])
-          driver_options[:crop] = area_calculator.calculate_crop
+          capture_options, comparison_options = extract_capture_and_comparison_options!(driver_options)
 
-          # TODO: Move this into screenshot stage, in order to re-evaluate coordinates after page updates
-          # Allow nil or single or multiple areas
-          driver_options[:skip_area] = area_calculator.calculate_skip_area
-          driver_options[:driver] = Drivers.for(driver_options[:driver])
+          capture_screenshot(capture_options, comparison_options)
 
-          @snapshot.checkout_base_screenshot
+          # 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
 
-          # When fail_if_new is true no need to create screenshot if base screenshot is missing
-          return if Capybara::Screenshot::Diff.fail_if_new && !@snapshot.base_path.exist?
+          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)
 
-          # Load new screenshot from Browser
-          take_comparison_screenshot(capture_options, comparison_options, @snapshot)
+          @snapshot.manager.create_output_directory_for(@snapshot.path)
+          capture_screenshot(capture_options, comparison_options)
+        end
 
-          # Pre-computation: No need to compare without base screenshot
-          return unless @snapshot.base_path.exist?
+        private
 
-          # Add comparison job in the queue
-          [screenshot_full_name, ImageCompare.new(@snapshot.path, @snapshot.base_path, comparison_options)]
+        def need_to_compare?
+          @snapshot.base_path.exist?
         end
 
-        private
+        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 = {})
           [
@@ -68,22 +125,6 @@ module Capybara
             driver_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(capture_options, comparison_options, snapshot = nil)
-          screenshoter = build_screenshoter_for(capture_options, comparison_options)
-          screenshoter.take_comparison_screenshot(snapshot)
-        end
-
-        def build_screenshoter_for(capture_options, comparison_options = {})
-          if capture_options[:stability_time_limit]
-            StableScreenshoter.new(capture_options, comparison_options)
-          else
-            Diff.screenshoter.new(capture_options, comparison_options[:driver])
-          end
-        end
       end
     end
   end

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

@@ -8,9 +8,11 @@ module Capybara
     class Screenshoter
       attr_reader :capture_options, :driver
 
-      def initialize(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 = driver
+        @driver = Diff::Drivers.for(comparison_options)
       end
 
       def crop
@@ -30,7 +32,7 @@ module Capybara
       # 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
+        snapshot.cleanup_attempts!
       end
 
       PNG_EXTENSION = ".png"
@@ -70,9 +72,8 @@ module Capybara
 
         blurred_input = BrowserHelpers.blur_from_focused_element if Screenshot.blur_active_element
 
-        if Screenshot.hide_caret
-          BrowserHelpers.hide_caret
-        end
+        BrowserHelpers.hide_caret if Screenshot.hide_caret
+        BrowserHelpers.disable_animations if Screenshot.disable_animations
 
         blurred_input
       end
@@ -86,7 +87,7 @@ module Capybara
           break unless pending_image
 
           if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline_at
-            raise CapybaraScreenshotDiff::ExpectationNotMet, "Images have not been loaded after #{timeout}s: #{pending_image.inspect}"
+            raise CapybaraScreenshotDiff::ExpectationNotMet.new("Images have not been loaded after #{timeout}s: #{pending_image.inspect}", caller)
           end
 
           sleep 0.025
@@ -101,7 +102,7 @@ module Capybara
         # Load saved screenshot and pre-process it
         process_screenshot(tmpfile.path, screenshot_path)
       ensure
-        File.unlink(tmpfile) if tmpfile
+        tmpfile&.close!
       end
 
       def capture_screenshot_at(snapshot)