snap_diff-capybara 0.0.1 → 2.0.0.alpha1

data/lib/snap_diff/comparison_result.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SnapDiff
+  # Represents the result of comparing two images
+  #
+  # This value object encapsulates the result of an image comparison operation.
+  # It follows the Single Responsibility Principle by focusing solely on representing
+  # the difference state, including:
+  # - Whether images are different or equal
+  # - Why they differ (dimensions, pixels, etc.)
+  # - The specific region of difference
+  # - Whether differences are tolerable based on configured thresholds
+  #
+  # As part of the layered comparison architecture, this class represents the final
+  # output of the comparison process, containing all data needed for reporting.
+  class ComparisonResult < Struct.new(:region, :meta, :comparison, :failed_by, :base_image_path, :image_path, keyword_init: nil)
+    def self.build_null(comparison, base_image_path, new_image_path, failed_by = nil)
+      ComparisonResult.new(
+        nil,
+        {difference_level: nil, max_color_distance: 0},
+        comparison,
+        failed_by,
+        base_image_path,
+        new_image_path
+      ).freeze
+    end
+
+    def different?
+      failed? || !(blank? || tolerable?)
+    end
+
+    def equal?
+      !different?
+    end
+
+    def failed?
+      !!failed_by
+    end
+
+    def options
+      comparison.options
+    end
+
+    def tolerance
+      options[:tolerance]
+    end
+
+    def skip_area
+      comparison.skip_area
+    end
+
+    def area_size_limit
+      options[:area_size_limit]
+    end
+
+    def blank?
+      region.nil? || region_area_size.zero?
+    end
+
+    def region_area_size
+      @region_area_size ||= region&.size || 0
+    end
+
+    def ratio
+      meta[:difference_level]
+    end
+
+    def to_h
+      {area_size: region_area_size, region: coordinates}.merge!(meta)
+    end
+
+    def coordinates
+      region&.to_edge_coordinates
+    end
+
+    # One-line debugging summary with the difference metrics.
+    # (Error messages use #to_h — see Reporters::Default#build_error_message.)
+    def inspect
+      "#<#{self.class.name} different=#{different?} failed_by=#{failed_by.inspect} " \
+        "area_size=#{region_area_size} region=#{coordinates.inspect} " \
+        "difference_level=#{ratio.inspect} " \
+        "base=#{original_image_path} new=#{new_image_path}>"
+    end
+
+    def tolerable?
+      !!((area_size_limit && area_size_limit >= region_area_size) || (tolerance && tolerance >= ratio))
+    end
+
+    # Path accessors for backward compatibility
+    def new_image_path
+      image_path || comparison&.new_image_path
+    end
+
+    def original_image_path
+      base_image_path || comparison&.base_image_path
+    end
+
+    def diff_mask
+      meta[:diff_mask]
+    end
+  end
+end

data/lib/snap_diff/config.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# The MAPPING below references the legacy modules, so they must be loaded
+# first. Requires config_legacy directly (a leaf, see its own header
+# comment), not the capybara_screenshot_diff umbrella -- config.rb is
+# required by both snap_diff.rb and (indirectly) capybara_screenshot_diff.rb,
+# and neither of those may lead back here.
+require "capybara/screenshot/diff/config_legacy"
+
+module SnapDiff
+  # Flat, additive consolidation of every existing
+  # +Capybara::Screenshot+ / +Capybara::Screenshot::Diff+ +mattr_accessor+
+  # setting behind one object: <tt>SnapDiff.config.<em>attr</em></tt>.
+  #
+  # Storage ownership: the OLD mattr_accessors remain the single source of
+  # truth. Config holds no state of its own -- every reader/writer defined
+  # from {MAPPING} simply forwards to the existing accessor. This is
+  # deliberate, not just simplest: several of those accessors carry default
+  # logic with observable timing (+fail_if_new+ derives its default from
+  # +ENV["CI"]+, +root+ falls back to +Rails.root+) that Rails' +mattr_accessor+
+  # evaluates once, at class-body-eval time, when +capybara_screenshot_diff.rb+
+  # first loads. Re-implementing that logic here -- even faithfully -- would
+  # mean evaluating it again, at a different moment (Config#new time), which
+  # is exactly the kind of "when defaults are evaluated" divergence the v2
+  # consolidation must not introduce. Delegating sidesteps the question
+  # entirely: Config never evaluates a default, it only ever forwards to
+  # whichever accessor already owns one. Bidirectional consistency (a write
+  # through either the old accessor or Config is visible through the other)
+  # falls out for free, because both paths read and write the exact same
+  # class-variable-backed storage.
+  class Config
+    # config attr name => [owning module, mattr_accessor name].
+    #
+    # The two names differ only for +screenshot_enabled+:
+    # +Capybara::Screenshot.enabled+ and +Capybara::Screenshot::Diff.enabled+
+    # are independent settings (see +Capybara::Screenshot.active?+, which
+    # reads both) that happen to share a bare name in their own modules. A
+    # flat Config can't expose two attributes both called +enabled+, so the
+    # Screenshot-side one is renamed here; Diff's keeps the bare +enabled+
+    # name since it's the one most existing configuration touches directly.
+    MAPPING = {
+      # Capybara::Screenshot
+      add_driver_path: [Capybara::Screenshot, :add_driver_path],
+      add_os_path: [Capybara::Screenshot, :add_os_path],
+      blur_active_element: [Capybara::Screenshot, :blur_active_element],
+      screenshot_enabled: [Capybara::Screenshot, :enabled],
+      hide_caret: [Capybara::Screenshot, :hide_caret],
+      disable_animations: [Capybara::Screenshot, :disable_animations],
+      root: [Capybara::Screenshot, :root],
+      stability_time_limit: [Capybara::Screenshot, :stability_time_limit],
+      window_size: [Capybara::Screenshot, :window_size],
+      save_path: [Capybara::Screenshot, :save_path],
+      use_lfs: [Capybara::Screenshot, :use_lfs],
+      screenshot_format: [Capybara::Screenshot, :screenshot_format],
+      capybara_screenshot_options: [Capybara::Screenshot, :capybara_screenshot_options],
+      # Capybara::Screenshot::Diff
+      delayed: [Capybara::Screenshot::Diff, :delayed],
+      area_size_limit: [Capybara::Screenshot::Diff, :area_size_limit],
+      fail_if_new: [Capybara::Screenshot::Diff, :fail_if_new],
+      pending_if_new: [Capybara::Screenshot::Diff, :pending_if_new],
+      fail_on_difference: [Capybara::Screenshot::Diff, :fail_on_difference],
+      color_distance_limit: [Capybara::Screenshot::Diff, :color_distance_limit],
+      enabled: [Capybara::Screenshot::Diff, :enabled],
+      shift_distance_limit: [Capybara::Screenshot::Diff, :shift_distance_limit],
+      skip_area: [Capybara::Screenshot::Diff, :skip_area],
+      driver: [Capybara::Screenshot::Diff, :driver],
+      tolerance: [Capybara::Screenshot::Diff, :tolerance],
+      perceptual_threshold: [Capybara::Screenshot::Diff, :perceptual_threshold],
+      screenshoter: [Capybara::Screenshot::Diff, :screenshoter],
+      manager: [Capybara::Screenshot::Diff, :manager]
+    }.freeze
+
+    MAPPING.each do |name, (mod, mattr)|
+      define_method(name) { mod.public_send(mattr) }
+      define_method(:"#{name}=") { |value| mod.public_send(:"#{mattr}=", value) }
+    end
+  end
+end

data/lib/snap_diff/deprecation.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module SnapDiff
+  # @api private
+  #
+  # Internal until the v2 namespace transition; not a public contract.
+  #
+  # Warn-once-per-subject deprecation helper. Dormant: nothing in the
+  # current codebase calls this yet -- it exists so the gated v2 shim layer
+  # (ADR-004's +const_missing+-based legacy constant shim and the
+  # mattr_accessor-to-Config method shims) has pre-tested warning
+  # machinery to call into once it lands.
+  module Deprecation
+    # Emission channel: Kernel#warn, not a direct +$stderr.puts+.
+    #
+    # Kernel#warn delegates to +Warning.warn+ (Ruby >= 2.4), so anything
+    # that hooks +Warning.warn+ -- a test suite that raises on warnings, a
+    # custom log formatter, Ruby's own -W flag -- sees these messages the
+    # same way it sees every other Ruby warning. Writing straight to
+    # +$stderr+ would bypass that hook entirely and be invisible to any
+    # caller who has customized +Warning+ behavior.
+    MUTEX = Mutex.new
+    @seen = {}
+
+    class << self
+      # Emit a deprecation warning for +subject+, exactly once per unique
+      # +subject+ per process.
+      #
+      # @param subject [String] the deprecated old-namespace name being
+      #   referenced, e.g. "Capybara::Screenshot::Diff::ImageCompare"
+      # @param replacement [String] the new-namespace name to use instead
+      # @param category [Symbol] what kind of thing moved, for the human
+      #   reading the message (e.g. :constant, :config)
+      # @return [void]
+      def warn(subject, replacement, category:)
+        return if SnapDiff.silence_deprecations?
+
+        first_time = MUTEX.synchronize do
+          @seen.key?(subject) ? false : (@seen[subject] = true)
+        end
+        return unless first_time
+
+        Kernel.warn(message_for(subject, replacement, category))
+      end
+
+      # @api private
+      #
+      # Clears the seen-set. For tests only -- lets each example assert
+      # "warns once" from a clean slate instead of leaking state across
+      # the suite.
+      # @return [void]
+      def reset!
+        MUTEX.synchronize { @seen.clear }
+      end
+
+      private
+
+      def message_for(subject, replacement, category)
+        "[snap_diff deprecation] `#{subject}` is deprecated (#{category}); " \
+          "use `#{replacement}` instead."
+      end
+    end
+  end
+
+  class << self
+    # @api private
+    attr_accessor :silence_deprecations
+
+    # @api private
+    #
+    # @return [Boolean] true if deprecation warnings should be suppressed,
+    #   either via the {silence_deprecations} accessor or the
+    #   SNAP_DIFF_SILENCE_DEPRECATIONS env var (truthy = "1"/"true").
+    def silence_deprecations?
+      !!silence_deprecations || truthy_env?(ENV["SNAP_DIFF_SILENCE_DEPRECATIONS"])
+    end
+
+    private
+
+    def truthy_env?(value)
+      %w[1 true].include?(value.to_s.downcase)
+    end
+  end
+end

data/lib/snap_diff/driver.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SnapDiff
+  # Shared default behavior for image-processing drivers.
+  #
+  # Replaces the old +Capybara::Screenshot::Diff::Drivers::BaseDriver+
+  # superclass (ADR-004 v2 step 4): concrete drivers +include Driver+
+  # instead of inheriting. Method names are intentionally unchanged from
+  # v1 — see dissent #4 in the v2 architecture design.
+  module Driver
+    PNG_EXTENSION = ".png"
+
+    def same_dimension?(comparison)
+      dimension(comparison.base_image) == dimension(comparison.new_image)
+    end
+
+    def height_for(image)
+      image.height
+    end
+
+    def width_for(image)
+      image.width
+    end
+
+    def image_area_size(image)
+      width_for(image) * height_for(image)
+    end
+
+    def dimension(image)
+      [width_for(image), height_for(image)]
+    end
+
+    def supports?(feature)
+      respond_to?(feature)
+    end
+  end
+end

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