capybara-screenshot-diff 1.15.0 → 2.0.0.alpha1

data/lib/capybara_screenshot_diff/static.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
 
-require "rack/files"
-require "capybara_screenshot_diff/minitest"
+require "snap_diff/static"
 
 module CapybaraScreenshotDiff
-  def self.serve(directory, root: Dir.pwd)
-    Capybara.app = Rack::Files.new(directory)
-    Capybara::Screenshot.root = root
+  def self.serve(...)
+    SnapDiff.serve(...)
   end
 end

data/lib/capybara_screenshot_diff.rb

@@ -1,121 +1,50 @@
 # frozen_string_literal: true
 
-# Lazy load: snap_diff.rb requires this file, so eagerly `require`-ing it
-# here would be circular. `autoload` defers the load until SnapDiff is
-# first referenced, by which point this file has already finished loading.
-autoload :SnapDiff, "snap_diff"
-
 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 = [255, 0, 0, 255].freeze
-  ORANGE_RGBA = [255, 192, 0, 255].freeze
+  # 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 < ErrorWithFilteredBacktrace; end
+  class CapybaraScreenshotDiffError < SnapDiff::ErrorWithFilteredBacktrace; end
 
   class ExpectationNotMet < CapybaraScreenshotDiffError; end
 
   class UnstableImage < CapybaraScreenshotDiffError; end
 
-  class WindowSizeMismatchError < ErrorWithFilteredBacktrace; end
+  class WindowSizeMismatchError < SnapDiff::ErrorWithFilteredBacktrace; end
 end
 
-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 << 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) { Screenshoter }
-      mattr_accessor(:manager) { CapybaraScreenshotDiff::SnapManager }
-
-      AVAILABLE_DRIVERS = 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)
-        ImageCompare.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
+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