snap_diff-capybara 0.0.1 → 2.0.0.alpha1

data/lib/capybara_screenshot_diff/snap_manager.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Forwarder (ADR-004 v2 step 6): CapybaraScreenshotDiff::SnapManager now
+# resolves lazily via snap_diff/legacy_shims' const_missing, with a
+# deprecation warning pointing at SnapDiff::SnapManager.
+require "snap_diff/snap_manager"
+require "snap_diff/legacy_shims"

data/lib/capybara_screenshot_diff/static.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "snap_diff/static"
+
+module CapybaraScreenshotDiff
+  def self.serve(...)
+    SnapDiff.serve(...)
+  end
+end

data/lib/capybara_screenshot_diff.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "capybara/dsl"
+require "capybara/screenshot/diff/config_legacy"
+require "capybara/screenshot/diff/version"
+require "capybara/screenshot/diff/os"
+require "capybara/screenshot/diff/browser_helpers"
+require "capybara/screenshot/diff/utils"
+require "capybara/screenshot/diff/image_compare"
+require "capybara_screenshot_diff/snap_manager"
+require "capybara_screenshot_diff/snap"
+require "capybara/screenshot/diff/screenshoter"
+require "capybara/screenshot/diff/stable_screenshoter"
+require "capybara/screenshot/diff/vcs"
+require "capybara/screenshot/diff/area_calculator"
+require "capybara/screenshot/diff/image_preprocessor"
+require "capybara/screenshot/diff/annotation_service"
+require "capybara_screenshot_diff/screenshot_namer"
+require "capybara_screenshot_diff/screenshot_assertion"
+require "capybara_screenshot_diff/attempts_reporter"
+require "capybara/screenshot/diff/screenshot_matcher"
+require "capybara/screenshot/diff/reporters/default"
+
+require "capybara_screenshot_diff/error_with_filtered_backtrace"
+
+module CapybaraScreenshotDiff
+  # RED_RGBA / ORANGE_RGBA moved to SnapDiff (snap_diff/annotation_service)
+  # so the bare "snap_diff" entry gets them too; the old names resolve via
+  # snap_diff/legacy_shims with a deprecation warning.
+
+  class CapybaraScreenshotDiffError < SnapDiff::ErrorWithFilteredBacktrace; end
+
+  class ExpectationNotMet < CapybaraScreenshotDiffError; end
+
+  class UnstableImage < CapybaraScreenshotDiffError; end
+
+  class WindowSizeMismatchError < SnapDiff::ErrorWithFilteredBacktrace; end
+end
+
+require "capybara_screenshot_diff/dsl"
+
+# Eager, not autoload: several lib/snap_diff/* units above (Os,
+# Screenshoter, ...) reopen `module SnapDiff` while loading, which cancels
+# any registered `autoload :SnapDiff` before it ever fires (Ruby resolves
+# the constant the first time anything reopens it, autoload or not) --
+# so SnapDiff.start/.compare/.config would silently never be defined
+# without this. Safe to do eagerly, unlike before this file's units
+# moved: snap_diff.rb no longer requires this file back (it only needs
+# the leaf config_legacy.rb + image_compare.rb), so there is no cycle.
+require "snap_diff"

data/lib/snap_diff/annotation_service.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module SnapDiff
+  # Annotation colors, defined here (not in the capybara_screenshot_diff
+  # umbrella) so they resolve in processes that only `require "snap_diff"`.
+  RED_RGBA = [255, 0, 0, 255].freeze
+  ORANGE_RGBA = [255, 192, 0, 255].freeze
+
+  # Draws diff/skip-area rectangles and the heatmap overlay for a Difference,
+  # and saves the resulting images to their `.diff.*` / `.heatmap.diff.*` paths.
+  #
+  # Extracted from Reporters::Default (ADR-004 PR 7) so the reporter only
+  # builds error messages; this class owns all image annotation work.
+  class AnnotationService
+    attr_reader :annotated_image_path, :annotated_base_image_path, :heatmap_diff_path
+
+    def initialize(difference)
+      @difference = difference
+
+      comparison = difference.comparison
+      ext = comparison.new_image_path.extname.delete_prefix(".")
+      screenshot_format = 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}")
+    end
+
+    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 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.diff_mask
+    end
+
+    def save_annotation_for(image, image_path)
+      image = annotate_difference(image, difference.region)
+      image = annotate_skip_areas(image, difference.comparison.skip_area) if difference.comparison.skip_area
+
+      save(image, image_path.to_path)
+    end
+
+    def annotate_difference(image, region)
+      driver.draw_rectangles([image], region, RED_RGBA, offset: 1).first
+    end
+
+    def annotate_skip_areas(image, skip_areas)
+      skip_areas.reduce(image) do |memo, region|
+        driver.draw_rectangles([memo], region, ORANGE_RGBA).first
+      end
+    end
+
+    def save(image, image_path)
+      driver.save_image_to(image, image_path.to_s)
+    end
+
+    private
+
+    attr_reader :difference
+
+    def save_heatmap_diff
+      merged_image = driver.merge(new_image, base_image)
+      highlighted_mask = driver.highlight_mask(difference.diff_mask, merged_image, color: RED_RGBA)
+
+      save(highlighted_mask, heatmap_diff_path.to_path)
+    end
+
+    def base_image
+      difference.comparison.base_image
+    end
+
+    def new_image
+      difference.comparison.new_image
+    end
+
+    def driver
+      @_driver ||= difference.comparison.driver
+    end
+  end
+end

data/lib/snap_diff/area_calculator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Region has not moved yet (ADR-004 v2 scoping: it's already unnamespaced,
+# no v2.0 move needed).
+require "capybara/screenshot/diff/region"
+
+module SnapDiff
+  class AreaCalculator
+    def initialize(crop_coordinates, skip_area)
+      @crop_coordinates = crop_coordinates
+      @skip_area = skip_area
+    end
+
+    def calculate_crop
+      return @_calculated_crop if defined?(@_calculated_crop)
+      return @_calculated_crop = nil unless @crop_coordinates
+
+      # TODO: Move out from this class, this should be done on before screenshot and should not depend on Browser
+      @crop_coordinates = BrowserHelpers.bounds_for_css(@crop_coordinates).first if @crop_coordinates.is_a?(String)
+      @_calculated_crop = Region.from_edge_coordinates(*@crop_coordinates)
+    end
+
+    # Cast skip areas params into Region
+    # and if there is crop then makes absolute coordinates to eb relative to crop top left corner
+    def calculate_skip_area
+      return nil unless @skip_area
+
+      crop_region = calculate_crop
+      skip_area = Array(@skip_area)
+
+      css_selectors, coords_list = skip_area.compact.partition { |region| region.is_a? String }
+      regions, coords_list = coords_list.partition { |region| region.is_a? Region }
+
+      regions.concat(build_regions_for(BrowserHelpers.bounds_for_css(*css_selectors))) unless css_selectors.empty?
+      regions.concat(build_regions_for(coords_list.flatten.each_slice(4))) unless coords_list.empty?
+
+      regions.compact!
+
+      if crop_region
+        regions
+          .map! { |region| crop_region.find_relative_intersect(region) }
+          .filter! { |region| region&.present? }
+      end
+
+      regions
+    end
+
+    private
+
+    def build_regions_for(coordinates)
+      coordinates
+        .map { |entry| Region.from_edge_coordinates(*entry) }
+        .tap { |region| region.compact! }
+    end
+  end
+end

data/lib/snap_diff/attempts_reporter.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+require "snap_diff/comparison"
+
+module SnapDiff
+  class AttemptsReporter
+    def initialize(snapshot, comparison_options, stability_options = {})
+      @snapshot = snapshot
+      @comparison_options = comparison_options
+      @wait = stability_options[:wait]
+    end
+
+    def generate
+      attempts_screenshot_paths = @snapshot.find_attempts_paths
+
+      annotate_attempts(attempts_screenshot_paths)
+
+      "Could not get stable screenshot within #{@wait}s:\n#{attempts_screenshot_paths.join("\n")}"
+    end
+
+    def build_comparison_for(attempt_path, previous_attempt_path)
+      Comparison.new(attempt_path, previous_attempt_path, @comparison_options)
+    end
+
+    private
+
+    def annotate_attempts(attempts_screenshot_paths)
+      previous_file = nil
+      attempts_screenshot_paths.reverse_each do |file_name|
+        if previous_file && File.exist?(previous_file)
+          attempts_comparison = build_comparison_for(file_name, previous_file)
+
+          if attempts_comparison.different?
+            FileUtils.mv(attempts_comparison.reporter.annotated_base_image_path, previous_file, force: true)
+          else
+            warn "[capybara-screenshot-diff] Some attempts was stable, but mistakenly marked as not: " \
+                   "#{previous_file} and #{file_name} are equal"
+          end
+
+          FileUtils.rm(attempts_comparison.reporter.annotated_image_path, force: true)
+        end
+
+        previous_file = file_name
+      end
+
+      previous_file
+    end
+  end
+end

data/lib/snap_diff/browser_helpers.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# Region has not moved yet (ADR-004 v2 scoping: it's already unnamespaced,
+# no v2.0 move needed) so this is an absolute require, not require_relative.
+require "capybara/screenshot/diff/region"
+
+module SnapDiff
+  module BrowserHelpers
+    def self.resize_window_if_needed
+      if ::Capybara::Screenshot.respond_to?(:window_size) && ::Capybara::Screenshot.window_size
+        resize_to(::Capybara::Screenshot.window_size)
+      end
+    end
+
+    def self.resize_to(window_size)
+      if session.driver.respond_to?(:resize)
+        session.driver.resize(*window_size)
+      elsif BrowserHelpers.selenium?
+        session.driver.browser.manage.window.resize_to(*window_size)
+      end
+    end
+
+    def self.selenium?
+      current_capybara_driver_class <= Capybara::Selenium::Driver
+    end
+
+    def self.window_size_is_wrong?(expected_window_size = nil)
+      selenium? && expected_window_size &&
+        session.driver.browser.manage.window.size != ::Selenium::WebDriver::Dimension.new(*expected_window_size)
+    end
+
+    def self.bounds_for_css(*css_selectors)
+      css_selectors.reduce([]) do |regions, selector|
+        regions.concat(all_visible_regions_for(selector))
+      end
+    end
+
+    IMAGE_WAIT_SCRIPT = <<~JS
+      function pending_image() {
+        const images = document.images
+        for (var i = 0; i < images.length; i++) {
+          if (!images[i].complete && images[i].loading !== "lazy") {
+              return images[i].src
+          }
+        }
+        return false
+      }(window)
+    JS
+
+    HIDE_CARET_SCRIPT = <<~JS
+      if (!document.getElementById('csdHideCaretStyle')) {
+        let style = document.createElement('style');
+        style.setAttribute('id', 'csdHideCaretStyle');
+        document.head.appendChild(style);
+        let styleSheet = style.sheet;
+        styleSheet.insertRule("* { caret-color: transparent !important; }", 0);
+      }
+    JS
+
+    def self.hide_caret
+      session.execute_script(HIDE_CARET_SCRIPT)
+    end
+
+    DISABLE_ANIMATIONS_SCRIPT = <<~JS
+      if (!document.getElementById('csdDisableAnimationsStyle')) {
+        let style = document.createElement('style');
+        style.setAttribute('id', 'csdDisableAnimationsStyle');
+        style.textContent = '*, *::before, *::after { animation-duration: 0s !important; animation-delay: 0s !important; transition-duration: 0s !important; transition-delay: 0s !important; }';
+        document.head.appendChild(style);
+      }
+    JS
+
+    def self.disable_animations
+      session.execute_script(DISABLE_ANIMATIONS_SCRIPT)
+    end
+
+    FIND_ACTIVE_ELEMENT_SCRIPT = <<~JS
+      function activeElement(){
+        const ae = document.activeElement;
+        if (ae.nodeName === "INPUT" || ae.nodeName === "TEXTAREA") {
+          ae.blur();
+          return ae;
+        }
+        return null;
+      }(window);
+    JS
+
+    def self.blur_from_focused_element
+      session.evaluate_script(FIND_ACTIVE_ELEMENT_SCRIPT)
+    end
+
+    GET_BOUNDING_CLIENT_RECT_SCRIPT = <<~JS
+      [
+        this.getBoundingClientRect().left,
+        this.getBoundingClientRect().top,
+        this.getBoundingClientRect().right,
+        this.getBoundingClientRect().bottom
+      ]
+    JS
+
+    def self.all_visible_regions_for(selector)
+      BrowserHelpers.session.all(selector, visible: true).map { |el| region_for(el) }
+    end
+
+    def self.region_for(element)
+      element.evaluate_script(GET_BOUNDING_CLIENT_RECT_SCRIPT).map { |point| point.negative? ? 0 : point.ceil.to_i }
+    end
+
+    def self.session
+      Capybara.current_session
+    end
+
+    def self.pending_image_to_load
+      BrowserHelpers.session.evaluate_script(IMAGE_WAIT_SCRIPT)
+    end
+
+    def self.current_capybara_driver_class
+      session.driver.class
+    end
+  end
+end

data/lib/snap_diff/capture/viewport.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "../browser_helpers"
+
+module SnapDiff
+  module Capture
+    # Per-capture viewport preparation seam.
+    #
+    # Called exactly once per capture, before the screenshoter runs and outside
+    # any stability retry loop. Today it only validates the window size
+    # (raise-only, never resizes) — the same guard ScreenshotMatcher carried
+    # inline before. v3 hangs scroll-position preservation and element-anchored
+    # capture off this seam via the +anchor+ parameter without touching callers.
+    module Viewport
+      module_function
+
+      # @param expected_window_size [Array(Integer, Integer), nil] the configured window size
+      # @param anchor [Object, nil] reserved for v3 (scroll preservation /
+      #   element-anchored capture); accepted but unused today.
+      # @raise [CapybaraScreenshotDiff::WindowSizeMismatchError] if the browser
+      #   window does not match the expected size.
+      def prepare!(expected_window_size, anchor: nil)
+        return unless BrowserHelpers.window_size_is_wrong?(expected_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: #{expected_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
+  end
+end

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