capybara-screenshot-diff 1.15.0 → 2.0.0.alpha1

data/lib/snap_diff/drivers/chunky_png_driver.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+begin
+  require "chunky_png"
+rescue LoadError => e
+  raise 'Required chunky_png gem is missing. Add `gem "chunky_png"` to Gemfile' if e.message.match?(/chunky_png/i)
+  raise
+end
+
+require "snap_diff/driver"
+require "snap_diff/drivers"
+require "snap_diff/comparison_result"
+
+module SnapDiff
+  module Drivers
+    class ChunkyPNGDriver
+      include SnapDiff::Driver
+      include ChunkyPNG::Color
+
+      def load_images(old_file_name, new_file_name)
+        old_bytes, new_bytes = load_image_files(old_file_name, new_file_name)
+
+        _load_images(old_bytes, new_bytes)
+      end
+
+      def add_black_box(image, _region)
+        image
+      end
+
+      def find_difference_region(comparison)
+        DifferenceRegionFinder.new(comparison, self).perform
+      end
+
+      def crop(region, i)
+        i.crop(*region.to_top_left_corner_coordinates)
+      end
+
+      def from_file(filename_or_path)
+        ChunkyPNG::Image.from_file(filename_or_path.to_s)
+      end
+
+      def save_image_to(image, filename)
+        image.save(filename, :fast_rgba)
+      end
+
+      def resize_image_to(image, new_width, new_height)
+        image.resample_bilinear(new_width, new_height)
+      end
+
+      def load_image_files(old_file_name, file_name)
+        [old_file_name.binread, file_name.binread]
+      end
+
+      def draw_rectangles(images, region, (r, g, b), offset: 0)
+        border_color = ChunkyPNG::Color.rgb(r, g, b)
+        border_shadow = ChunkyPNG::Color.rgba(r, g, b, 100)
+
+        images.map do |image|
+          new_img = image.dup
+          new_img.rect(region.left - offset, region.top - offset, region.right + offset, region.bottom + offset, border_color)
+          new_img.rect(region.left, region.top, region.right, region.bottom, border_shadow)
+          new_img
+        end
+      end
+
+      def same_pixels?(comparison)
+        comparison.new_image == comparison.base_image
+      end
+
+      private
+
+      def _load_images(old_file, new_file)
+        [ChunkyPNG::Image.from_blob(old_file), ChunkyPNG::Image.from_blob(new_file)]
+      end
+
+      class DifferenceRegionFinder
+        attr_accessor :skip_area, :color_distance_limit, :shift_distance_limit
+
+        def initialize(comparison, driver = nil)
+          @comparison = comparison
+          @driver = driver
+
+          @color_distance_limit = comparison.options[:color_distance_limit]
+          @shift_distance_limit = comparison.options[:shift_distance_limit]
+          @skip_area = comparison.options[:skip_area]
+        end
+
+        def perform
+          find_difference_region(@comparison)
+        end
+
+        def find_difference_region(comparison)
+          new_image, base_image, = comparison.new_image, comparison.base_image
+
+          meta = {}
+          meta[:max_color_distance] = 0
+          meta[:max_shift_distance] = 0 if shift_distance_limit
+
+          region = find_top(base_image, new_image, cache: meta)
+          region = if region.nil? || region[1].nil?
+            nil
+          else
+            find_diff_rectangle(base_image, new_image, region, cache: meta)
+          end
+
+          result = ComparisonResult.new(region, meta, comparison)
+
+          unless result.blank?
+            meta[:max_color_distance] = meta[:max_color_distance].ceil(1) if meta[:max_color_distance]
+
+            if comparison.options[:tolerance]
+              meta[:difference_level] = difference_level(nil, base_image, region)
+            end
+          end
+
+          result
+        end
+
+        def difference_level(_diff_mask, base_image, region)
+          image_area_size = @driver.image_area_size(base_image)
+          return nil if image_area_size.zero?
+
+          region.size.to_f / image_area_size
+        end
+
+        def find_diff_rectangle(org_img, new_img, area_coordinates, cache:)
+          left, top, right, bottom = find_left_right_and_top(org_img, new_img, area_coordinates, cache: cache)
+          bottom = find_bottom(org_img, new_img, left, right, bottom, cache: cache)
+
+          Region.from_edge_coordinates(left, top, right, bottom)
+        end
+
+        def find_top(old_img, new_img, cache:)
+          old_img.height.times do |y|
+            old_img.width.times do |x|
+              return [x, y, x, y] unless same_color?(old_img, new_img, x, y, cache: cache)
+            end
+          end
+          nil
+        end
+
+        def find_left_right_and_top(old_img, new_img, region, cache:)
+          region = region.is_a?(Region) ? region.to_edge_coordinates : region
+
+          left = region[0] || old_img.width - 1
+          top = region[1]
+          right = region[2] || 0
+          bottom = region[3]
+
+          old_img.height.times do |y|
+            (0...left).find do |x|
+              next if same_color?(old_img, new_img, x, y, cache: cache)
+
+              top ||= y
+              bottom = y
+              left = x
+              right = x if x > right
+              x
+            end
+            (old_img.width - 1).step(right + 1, -1).find do |x|
+              unless same_color?(old_img, new_img, x, y, cache: cache)
+                bottom = y
+                right = x
+              end
+            end
+          end
+
+          [left, top, right, bottom]
+        end
+
+        def find_bottom(old_img, new_img, left, right, bottom, cache:)
+          if bottom
+            (old_img.height - 1).step(bottom + 1, -1).find do |y|
+              (left..right).find do |x|
+                bottom = y unless same_color?(old_img, new_img, x, y, cache: cache)
+              end
+            end
+          end
+
+          bottom
+        end
+
+        def same_color?(old_img, new_img, x, y, cache:)
+          return true if skipped_region?(x, y)
+
+          color_distance =
+            color_distance_at(new_img, old_img, x, y, shift_distance_limit: @shift_distance_limit)
+
+          if color_distance > cache[:max_color_distance]
+            cache[:max_color_distance] = color_distance
+          end
+
+          color_matches = color_distance == 0 ||
+            (!!@color_distance_limit && @color_distance_limit > 0 && color_distance <= @color_distance_limit)
+
+          return color_matches if !@shift_distance_limit || cache[:max_shift_distance] == Float::INFINITY
+
+          shift_distance = (color_matches && 0) ||
+            shift_distance_at(new_img, old_img, x, y, color_distance_limit: @color_distance_limit)
+          if shift_distance && (cache[:max_shift_distance].nil? || shift_distance > cache[:max_shift_distance])
+            cache[:max_shift_distance] = shift_distance
+          end
+
+          color_matches
+        end
+
+        def skipped_region?(x, y)
+          return false unless @skip_area
+
+          @skip_area.any? { |region| region.cover?(x, y) }
+        end
+
+        def color_distance_at(new_img, old_img, x, y, shift_distance_limit:)
+          org_color = old_img[x, y]
+          unless shift_distance_limit
+            return ChunkyPNG::Color.euclidean_distance_rgba(org_color, new_img[x, y])
+          end
+
+          start_x = [0, x - shift_distance_limit].max
+          end_x = [x + shift_distance_limit, new_img.width - 1].min
+          start_y = [0, y - shift_distance_limit].max
+          end_y = [y + shift_distance_limit, new_img.height - 1].min
+
+          min_distance = Float::INFINITY
+          (start_y..end_y).each do |dy|
+            (start_x..end_x).each do |dx|
+              distance = ChunkyPNG::Color.euclidean_distance_rgba(org_color, new_img[dx, dy])
+              return 0 if distance == 0
+              min_distance = distance if distance < min_distance
+            end
+          end
+          min_distance
+        end
+
+        def shift_distance_at(new_img, old_img, x, y, color_distance_limit:)
+          org_color = old_img[x, y]
+          shift_distance = 0
+          loop do
+            bounds_breached = 0
+            top_row = y - shift_distance
+            if top_row >= 0 # top
+              ([0, x - shift_distance].max..[x + shift_distance, new_img.width - 1].min).each do |dx|
+                if color_matches(new_img, org_color, dx, top_row, color_distance_limit)
+                  return shift_distance
+                end
+              end
+            else
+              bounds_breached += 1
+            end
+            if shift_distance > 0
+              if (x - shift_distance) >= 0 # left
+                ([0, top_row + 1].max..[y + shift_distance, new_img.height - 2].min)
+                  .each do |dy|
+                    if color_matches(new_img, org_color, x - shift_distance, dy, color_distance_limit)
+                      return shift_distance
+                    end
+                  end
+              else
+                bounds_breached += 1
+              end
+              if (y + shift_distance) < new_img.height # bottom
+                ([0, x - shift_distance].max..[x + shift_distance, new_img.width - 1].min).each do |dx|
+                  if color_matches(new_img, org_color, dx, y + shift_distance, color_distance_limit)
+                    return shift_distance
+                  end
+                end
+              else
+                bounds_breached += 1
+              end
+              if (x + shift_distance) < new_img.width # right
+                ([0, top_row + 1].max..[y + shift_distance, new_img.height - 2].min)
+                  .each do |dy|
+                    if color_matches(new_img, org_color, x + shift_distance, dy, color_distance_limit)
+                      return shift_distance
+                    end
+                  end
+              else
+                bounds_breached += 1
+              end
+            end
+            break if bounds_breached == 4
+
+            shift_distance += 1
+          end
+          Float::INFINITY
+        end
+
+        def color_matches(new_img, org_color, x, y, color_distance_limit)
+          new_color = new_img[x, y]
+          return new_color == org_color unless color_distance_limit
+
+          color_distance = ChunkyPNG::Color.euclidean_distance_rgba(org_color, new_color)
+          color_distance <= color_distance_limit
+        end
+      end
+    end
+  end
+end

data/lib/snap_diff/drivers/vips_driver.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+begin
+  require "vips"
+rescue LoadError => e
+  raise 'Required ruby-vips gem is missing. Add `gem "ruby-vips"` to Gemfile' if e.message.match?(/vips/i)
+  raise
+end
+
+require "snap_diff/driver"
+require "snap_diff/drivers"
+require "snap_diff/comparison_result"
+# Defines SnapDiff::RED_RGBA, the highlight_mask default color.
+require "snap_diff/annotation_service"
+
+module SnapDiff
+  module Drivers
+    class VipsDriver
+      include SnapDiff::Driver
+
+      def find_difference_region(comparison)
+        new_image, base_image, options = comparison.new_image, comparison.base_image, comparison.options
+
+        diff_mask = if options[:perceptual_threshold]
+          self.class.perceptual_difference_mask(base_image, new_image, options[:perceptual_threshold])
+        else
+          self.class.difference_mask(base_image, new_image, options[:color_distance_limit])
+        end
+        region = self.class.difference_region_by(diff_mask)
+        # TODO: schedule research when we got this case for VIPs
+        # region = nil if region && region_covers_entire_image?(region, base_image)
+
+        result = ComparisonResult.new(region, {}, comparison)
+
+        unless result.blank?
+          result.meta[:difference_level] = difference_level(diff_mask, base_image) if comparison.options[:tolerance]
+          result.meta[:diff_mask] = diff_mask
+        end
+
+        result
+      end
+
+      def crop(region, i)
+        i.crop(*region.to_top_left_corner_coordinates)
+      rescue Vips::Error => e
+        warn(
+          "[capybara-screenshot-diff] Crop has been failed for " \
+            "{ region: #{region.to_top_left_corner_coordinates.inspect}, image: #{dimension(i).join("x")} }"
+        )
+        raise e
+      end
+
+      def filter_image_with_median(image, median_filter_window_size)
+        image.median(median_filter_window_size)
+      end
+
+      def add_black_box(memo, region)
+        return memo unless region
+
+        memo.draw_rect([0, 0, 0, 0], *region.to_top_left_corner_coordinates, fill: true)
+      end
+
+      def difference_level(diff_mask, old_img, _region = nil)
+        self.class.difference_area_size_by(diff_mask).to_f / image_area_size(old_img)
+      end
+
+      MAX_FILENAME_LENGTH = 200
+
+      # Vips could not work with the same file. Per each process we require to create new file
+      def save_image_to(image, filename)
+        # Dir::Tmpname will happily produce tempfile names that are too long for most unix filesystems,
+        # which leads to "unix error: File name too long". Apply a limit to avoid this.
+        limited_filename = filename.to_s[-MAX_FILENAME_LENGTH..] || filename.to_s
+        ::Dir::Tmpname.create([limited_filename, PNG_EXTENSION]) do |tmp_image_filename|
+          image.write_to_file(tmp_image_filename)
+          FileUtils.mv(tmp_image_filename, filename)
+        end
+      end
+
+      def resize_image_to(image, new_width, new_height)
+        image.resize(new_width.to_f / image.width, vscale: new_height.to_f / image.height)
+      end
+
+      def load_images(old_file_name, new_file_name)
+        [from_file(old_file_name), from_file(new_file_name)]
+      end
+
+      def from_file(filename)
+        result = ::Vips::Image.new_from_file(filename.to_s)
+
+        result = result.colourspace(:srgb) if result.bands < 3
+        result = result.bandjoin(255) if result.bands == 3
+
+        result
+      end
+
+      def draw_rectangles(images, region, rgba, offset: 0)
+        images.map do |image|
+          image.draw_rect(rgba, region.left - offset, region.top - offset, region.width + (offset * 2), region.height + (offset * 2))
+        end
+      end
+
+      def same_pixels?(comparison)
+        (comparison.new_image == comparison.base_image).min == 255
+      end
+
+      def merge(new_image, base_image)
+        base_image.composite2(new_image, :over)
+      end
+
+      def highlight_mask(diff_mask, merged_image, color: SnapDiff::RED_RGBA)
+        diff_mask.ifthenelse(color, merged_image * 0.75)
+      end
+
+      private
+
+      class << self
+        def difference_area(old_image, new_image, color_distance: 0)
+          mask = difference_mask(new_image, old_image, color_distance)
+          difference_area_size_by(mask)
+        end
+
+        def difference_area_size_by(difference_mask)
+          diff_mask = difference_mask == 0
+          diff_mask.hist_find.to_a[0][0].max
+        end
+
+        def difference_mask(base_image, new_image, color_distance = nil)
+          result = (new_image - base_image).abs
+          color_distance ? result > color_distance : result
+        end
+
+        def perceptual_difference_mask(base_image, new_image, threshold = 2.0)
+          color_diff = perceptual_color_diff(base_image, new_image) > threshold
+          alpha_diff = alpha_channel_diff(base_image, new_image)
+          alpha_diff ? (color_diff | alpha_diff) : color_diff
+        end
+
+        def perceptual_color_diff(base_image, new_image)
+          base_rgb = (base_image.bands > 3) ? base_image.extract_band(0, n: 3) : base_image
+          new_rgb = (new_image.bands > 3) ? new_image.extract_band(0, n: 3) : new_image
+          base_lab = base_rgb.colourspace(:lab)
+          new_lab = new_rgb.colourspace(:lab)
+          base_lab.dE00(new_lab)
+        rescue Vips::Error
+          base_lab.dE76(new_lab)
+        end
+
+        def alpha_channel_diff(base_image, new_image)
+          return unless base_image.bands > 3 && new_image.bands > 3
+
+          (base_image.extract_band(3) - new_image.extract_band(3)).abs > 0
+        end
+
+        def difference_region_by(diff_mask)
+          columns, rows = diff_mask.bandor.project
+
+          left = columns.profile[1].min
+          right = columns.width - columns.flip(:horizontal).profile[1].min
+
+          top = rows.profile[0].min
+          bottom = rows.height - rows.flip(:vertical).profile[0].min
+
+          return nil if right < left || bottom < top
+
+          Region.from_edge_coordinates(left, top, right, bottom)
+        end
+      end
+    end
+  end
+end

data/lib/snap_diff/drivers.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SnapDiff
+  # Compare two images and determine if they are equal, different, or within some comparison
+  # range considering color values and difference area size.
+  module Drivers
+    def self.for(driver_options = {})
+      driver_option = driver_options.is_a?(Hash) ? driver_options.fetch(:driver, :chunky_png) : driver_options
+      return driver_option unless driver_option.is_a?(Symbol)
+
+      Utils.find_driver_class_for(driver_option).new
+    end
+  end
+end

data/lib/snap_diff/dsl.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+# No require of "capybara_screenshot_diff" here: every Capybara::Screenshot
+# / CapybaraScreenshotDiff reference below is inside a method body, resolved
+# lazily at call time, not at this file's own load time -- so this unit has
+# no eager dependency on the umbrella entry point, and requiring it here
+# would create a require cycle back to capybara_screenshot_diff.rb (which
+# requires this file's old-path forwarder).
+# DSL includes Capybara::DSL directly below, so it needs the base gem
+# loaded regardless of what pulled this file in.
+require "capybara/dsl"
+require "capybara/screenshot/diff/config_legacy"
+require "capybara/screenshot/diff/drivers"
+require "snap_diff/comparison"
+require "capybara/screenshot/diff/screenshot_matcher"
+require_relative "screenshot_namer"
+require_relative "screenshot_assertion"
+
+module SnapDiff
+  # DSL for taking screenshots and making assertions in Capybara tests.
+  # This module provides methods for taking screenshots, comparing them against baselines,
+  # and managing the comparison process with various configuration options.
+  #
+  # The DSL is designed to be included in your test context (e.g., RSpec, Minitest)
+  # to provide screenshot comparison capabilities.
+  module DSL
+    include Capybara::DSL
+
+    def screenshot_section(name)
+      screenshot_namer.section = name
+    end
+
+    def screenshot_group(name)
+      screenshot_namer.group = name
+    end
+
+    # Takes a screenshot and compares it against a baseline image.
+    #
+    # The method follows a layered optimization strategy for comparison:
+    # 1. First checks if screenshot functionality is active
+    # 2. Builds a full screenshot name using the current context
+    # 3. Creates a screenshot assertion object
+    # 4. Either validates immediately or defers validation based on options
+    #
+    # @param name [String] The base name of the screenshot, used to generate the filename.
+    # @param skip_stack_frames [Integer] The number of stack frames to skip when reporting errors.
+    # @param options [Hash] Additional options for taking the screenshot and comparison.
+    # @option options [Boolean] :delayed (Capybara::Screenshot::Diff.delayed)
+    #   Whether to validate the screenshot immediately or delay validation.
+    # @option options [Array<Integer>] :crop [left, top, right, bottom] Edge coordinates to crop the screenshot to.
+    # @option options [Array<Array<Integer>>] :skip_area Array of [left, top, right, bottom] edge coordinates to ignore.
+    # @option options [Numeric] :tolerance (0.001 for :vips driver) Color tolerance for comparison.
+    #   Represents the maximum allowed ratio of different pixels (0.0-1.0 scale).
+    # @option options [Numeric] :color_distance_limit Maximum allowed color distance between pixels.
+    #   Uses Euclidean RGBA distance (0-510 scale). Mutually exclusive with :perceptual_threshold.
+    # @option options [Numeric] :perceptual_threshold Maximum perceptual color difference (CIE dE00).
+    #   Uses human perception-based scale (0-100+). VIPS only. Takes priority over :color_distance_limit if both set.
+    # @option options [Numeric] :shift_distance_limit Maximum allowed shift distance for pixels.
+    # @option options [Numeric] :area_size_limit Maximum allowed difference area size in pixels.
+    # @option options [Symbol] :driver (:auto) The image processing driver to use (:auto, :chunky_png, :vips).
+    # @return [Boolean] True if the screenshot was successfully captured and processed.
+    # @raise [CapybaraScreenshotDiff::ExpectationNotMet] If comparison fails and immediate validation is enabled.
+    # @raise [CapybaraScreenshotDiff::UnstableImage] If the image comparison is unstable.
+    # @raise [CapybaraScreenshotDiff::WindowSizeMismatchError] If the window size doesn't match expectations.
+    def assert_matches_screenshot(name, skip_stack_frames: 0, **options)
+      return false unless Capybara::Screenshot.active?
+
+      # Get the full name with section and group information
+      full_name = CapybaraScreenshotDiff.screenshot_namer.full_name(name)
+
+      # Build the screenshot assertion
+      assertion = build_screenshot_assertion(full_name, options, skip_stack_frames: skip_stack_frames + 1)
+
+      return false unless assertion
+
+      # Determine if validation should be delayed or immediate
+      delayed = options.fetch(:delayed, Capybara::Screenshot::Diff.delayed)
+
+      if delayed
+        CapybaraScreenshotDiff.add_assertion(assertion)
+      else
+        assertion.validate!
+      end
+
+      true
+    end
+
+    # Convenience wrapper around {#assert_matches_screenshot} and {#capture_screenshot}.
+    # @param compare [Boolean] When false, only captures the screenshot without comparing it to a baseline.
+    # @see #assert_matches_screenshot
+    # @see #capture_screenshot
+    def screenshot(name, skip_stack_frames: 0, compare: true, **options)
+      if compare
+        assert_matches_screenshot(name, skip_stack_frames: skip_stack_frames + 1, **options)
+      else
+        capture_screenshot(name, **options)
+      end
+    end
+
+    # Captures a screenshot without comparing it to a baseline.
+    # @param name [String] The base name of the screenshot, used to generate the filename.
+    # @param options [Hash] Additional options for taking the screenshot. See {#assert_matches_screenshot}.
+    # @return [Boolean] True if the screenshot was successfully captured.
+    def capture_screenshot(name, **options)
+      return false unless Capybara::Screenshot.active?
+
+      full_name = CapybaraScreenshotDiff.screenshot_namer.full_name(name)
+      SnapDiff::ScreenshotMatcher.new(full_name, options).capture
+
+      true
+    end
+
+    # Asserts the current page has no visual changes from the baseline.
+    # Override in your base test class to add project-specific behavior
+    # (e.g., waiting for Turbo, default skip areas).
+    def assert_no_screenshot_changes(name, skip_stack_frames: 0, **opts)
+      assert_matches_screenshot(name, skip_stack_frames: skip_stack_frames + 1, **opts)
+    end
+
+    private
+
+    # Builds a screenshot assertion object that can be validated immediately or later.
+    #
+    # This method constructs a screenshot assertion that encapsulates the comparison logic.
+    # The actual comparison is deferred until {ScreenshotAssertion#validate!} is called.
+    #
+    # @param name [String] The full name of the screenshot, including any section/group context.
+    # @param options [Hash] Options for screenshot taking and comparison.
+    #   See {#assert_matches_screenshot} for available options.
+    # @param skip_stack_frames [Integer] Number of stack frames to skip for error reporting.
+    # @return [ScreenshotAssertion, nil] The assertion object or nil if no assertion is needed.
+    # @see ScreenshotAssertion
+    def build_screenshot_assertion(name, options, skip_stack_frames: 0)
+      SnapDiff::ScreenshotMatcher
+        .new(name, options)
+        .build_screenshot_assertion(skip_stack_frames: skip_stack_frames + 1)
+    end
+
+    def screenshot_namer
+      CapybaraScreenshotDiff.screenshot_namer
+    end
+  end
+end

data/lib/snap_diff/error_with_filtered_backtrace.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SnapDiff
+  class BacktraceFilter
+    LIB_DIRECTORY = File.expand_path(File.join(File.dirname(__FILE__), "..")) + File::SEPARATOR
+
+    def initialize(lib_directory = LIB_DIRECTORY)
+      # Trailing separator keeps the prefix match on a directory boundary,
+      # so "/app/lib" does not also reject "/app/library".
+      @lib_directory = lib_directory.end_with?(File::SEPARATOR) ? lib_directory : lib_directory + File::SEPARATOR
+    end
+
+    # Filters out any backtrace lines originating from the library directory or from gems such as ActiveSupport, Minitest, and Railties
+    # @param backtrace [Array<String>]
+    # @return [Array<String>]
+    def filtered(backtrace)
+      backtrace
+        .reject { |location| File.expand_path(location).start_with?(@lib_directory) }
+        .reject { |l| l =~ /gems\/(activesupport|minitest|railties)/ }
+    end
+  end
+
+  # @private
+  class ErrorWithFilteredBacktrace < StandardError
+    # @private
+    def initialize(message = nil, backtrace = [])
+      super(message)
+      filter = BacktraceFilter.new
+      set_backtrace(filter.filtered(backtrace))
+    end
+  end
+end