capybara-screenshot-diff 1.15.0 → 2.0.0.alpha1

data/lib/snap_diff/comparison.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "fileutils"
+
+require "snap_diff/comparison_result"
+require "snap_diff/drivers"
+require "snap_diff/image_preprocessor"
+require "capybara/screenshot/diff/reporters/default"
+
+# The internal images-holder struct and the driver cache keep their legacy
+# Capybara::Screenshot::Diff homes for now: SnapDiff::Comparison is the
+# comparison class below (ex-ImageCompare), so the struct cannot take the
+# same name. Its SnapDiff home arrives only when it is folded into
+# Comparison as a nested value (v2 design section 2) -- renaming it here
+# would exceed step 5's two approved renames.
+module Capybara
+  module Screenshot
+    module Diff
+      LOADED_DRIVERS = {}
+
+      # Holds the two images (and their paths/options/driver) being compared.
+      class Comparison < Struct.new(:new_image, :base_image, :options, :driver, :new_image_path, :base_image_path)
+        def skip_area
+          options[:skip_area]
+        end
+      end
+    end
+  end
+end
+
+module SnapDiff
+  # 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 Comparison
+    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)
+      Capybara::Screenshot::Diff::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 [Capybara::Screenshot::Diff::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 ComparisonResult object or nil
+    #   When false, returns a ComparisonResult object directly.
+    # @return [Array, ComparisonResult] Result format depends on quick_mode parameter.
+    def analyze_difference(comparison, quick_mode: true)
+      # Handle dimension differences
+      unless driver.same_dimension?(comparison)
+        result = ComparisonResult.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 = ComparisonResult.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
+      Capybara::Screenshot::Diff::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 Capybara::Screenshot::Diff::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 [Capybara::Screenshot::Diff::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 = Capybara::Screenshot::Diff::Comparison.new(nil, nil, driver_options, driver, image_path, base_image_path).freeze
+      ComparisonResult.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

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

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
-# The MAPPING below references the legacy modules, so they must be loaded first.
-require "capybara_screenshot_diff"
+# 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

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