capybara-screenshot-diff 1.15.1 → 2.0.0.beta1

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

@@ -1,56 +1,7 @@
 # frozen_string_literal: true
 
-module Capybara
-  module Screenshot
-    module Diff
-      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
-  end
-end
+# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Diff::AreaCalculator
+# now resolves lazily via snap_diff/legacy_shims' const_missing, with a
+# deprecation warning pointing at SnapDiff::AreaCalculator.
+require "snap_diff/area_calculator"
+require "snap_diff/legacy_shims"

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

@@ -1,121 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "region"
-
-module Capybara
-  module Screenshot
-    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
-end
+# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::BrowserHelpers now
+# resolves lazily via snap_diff/legacy_shims' const_missing, with a
+# deprecation warning pointing at SnapDiff::BrowserHelpers.
+require "snap_diff/browser_helpers"
+require "snap_diff/legacy_shims"

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# Legacy Capybara::Screenshot / Capybara::Screenshot::Diff mattr_accessor
+# config module, extracted out of capybara_screenshot_diff.rb so it is a
+# leaf: it can be required by both capybara_screenshot_diff.rb (the old
+# umbrella entry point) and snap_diff.rb (the canonical entry point)
+# without either of *those* requiring the other back.
+#
+# Why this file has to exist at all: several lib/snap_diff/* units
+# (Screenshoter, SnapManager, Utils) are referenced here at class-body
+# eval time (mattr_accessor default blocks, AVAILABLE_DRIVERS) rather
+# than at call time, so they must be real, already-loaded classes before
+# this module body runs. Since v2 step 6 they are pulled in and referenced
+# under their canonical SnapDiff names: the old-name aliases are lazy
+# const_missing shims that emit deprecation warnings, and the gem's own
+# code must stay warning-free. Everything else this module references
+# (Os, Comparison) is referenced only inside method bodies, resolved
+# lazily at call time by whichever entry point loaded them.
+require "snap_diff/screenshoter"
+require "snap_diff/snap_manager"
+require "snap_diff/utils"
+
+module Capybara
+  module Screenshot
+    mattr_accessor :add_driver_path
+    mattr_accessor :add_os_path
+    mattr_accessor(:blur_active_element) { true }
+    mattr_accessor :enabled
+    mattr_accessor(:hide_caret) { true }
+    mattr_accessor :disable_animations
+    mattr_reader(:root) { (defined?(Rails) && defined?(Rails.root) && Rails.root) || Pathname(".").expand_path }
+    mattr_accessor :stability_time_limit
+    mattr_accessor :window_size
+    mattr_accessor(:save_path) { "doc/screenshots" }
+    mattr_accessor(:use_lfs)
+    mattr_accessor(:screenshot_format) { "png" }
+    mattr_accessor(:capybara_screenshot_options) { {} }
+
+    class << self
+      def root=(path)
+        @@root = Pathname(path).expand_path
+      end
+
+      def active?
+        enabled || (enabled.nil? && Diff.enabled)
+      end
+
+      def screenshot_area
+        parts = [Screenshot.save_path]
+        parts << SnapDiff::Os.name if Screenshot.add_os_path
+        parts << Capybara.current_driver.to_s if Screenshot.add_driver_path
+        File.join(*parts)
+      end
+
+      def screenshot_area_abs
+        root / screenshot_area
+      end
+    end
+
+    # Module to track screenshot changes
+    module Diff
+      mattr_accessor(:delayed) { true }
+      mattr_accessor :area_size_limit
+      mattr_accessor(:fail_if_new) { !ENV["CI"].nil? && !ENV["CI"].empty? }
+      mattr_accessor(:pending_if_new) { false }
+      mattr_accessor(:fail_on_difference) { true }
+      mattr_accessor :color_distance_limit
+      mattr_accessor(:enabled) { true }
+      mattr_accessor :shift_distance_limit
+      mattr_accessor :skip_area
+      mattr_accessor(:driver) { :auto }
+      mattr_accessor :tolerance
+      mattr_accessor :perceptual_threshold
+
+      mattr_accessor(:screenshoter) { SnapDiff::Screenshoter }
+      mattr_accessor(:manager) { SnapDiff::SnapManager }
+
+      AVAILABLE_DRIVERS = SnapDiff::Utils.detect_available_drivers.freeze
+
+      # Configure screenshot and diff settings in one block.
+      #
+      #   Capybara::Screenshot::Diff.configure do |screenshot, diff|
+      #     screenshot.window_size = [1280, 1024]
+      #     screenshot.stability_time_limit = 1
+      #     diff.driver = :vips
+      #     diff.tolerance = 0.0005
+      #   end
+      def self.configure
+        yield Screenshot, self
+      end
+
+      def self.compare(baseline_path, current_path, **options)
+        SnapDiff::Comparison.new(current_path, baseline_path, default_options.merge(options))
+      end
+
+      def self.default_options
+        {
+          area_size_limit: area_size_limit,
+          color_distance_limit: color_distance_limit,
+          driver: driver,
+          screenshot_format: Screenshot.screenshot_format,
+          capybara_screenshot_options: Screenshot.capybara_screenshot_options,
+          perceptual_threshold: perceptual_threshold,
+          shift_distance_limit: shift_distance_limit,
+          skip_area: skip_area,
+          stability_time_limit: Screenshot.stability_time_limit,
+          tolerance: tolerance || ((driver == :vips) ? 0.001 : nil),
+          wait: Capybara.default_max_wait_time
+        }
+      end
+    end
+  end
+end

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

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
 
-require "capybara_screenshot_diff/cucumber"
+require "snap_diff/integrations/cucumber"

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

@@ -1,104 +1,8 @@
 # frozen_string_literal: true
 
-require "json"
-
-module Capybara
-  module Screenshot
-    module Diff
-      # Represents a difference between 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.
-      # Represents a difference between two images
-      class Difference < 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)
-          Difference.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
-
-        def inspect
-          to_h.to_json
-        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
-  end
-end
+# Forwarder (ADR-004 v2 step 6): the comparison-result value object lives at
+# SnapDiff::ComparisonResult (ex-Difference); the old name now resolves
+# lazily via snap_diff/legacy_shims' const_missing, with a deprecation
+# warning.
+require "snap_diff/comparison_result"
+require "snap_diff/legacy_shims"

data/lib/capybara/screenshot/diff/drivers/base_driver.rb

@@ -1,41 +1,9 @@
 # frozen_string_literal: true
 
-require "capybara/screenshot/diff/difference"
-
-module Capybara
-  module Screenshot
-    module Diff
-      # Compare two images and determine if they are equal, different, or within some comparison
-      # range considering color values and difference area size.
-      module Drivers
-        class BaseDriver
-          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
-    end
-  end
-end
+# BaseDriver was dissolved into the SnapDiff::Driver mixin (ADR-004 v2
+# step 4); since step 6 the old name resolves lazily via
+# snap_diff/legacy_shims' const_missing, with a deprecation warning.
+# Note it is now a module -- `class MyDriver < BaseDriver` becomes
+# `include SnapDiff::Driver`.
+require "snap_diff/driver"
+require "snap_diff/legacy_shims"