snap_diff-capybara 0.0.1 → 2.0.0.beta1

data/lib/snap_diff/drivers/vips_driver.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+begin
+  require "vips"
+rescue LoadError => e
+  raise 'Required ruby-vips gem is missing. Add `gem "ruby-vips"` to Gemfile' if e.message.match?(/vips/i)
+  raise
+end
+
+require "snap_diff/driver"
+require "snap_diff/drivers"
+require "snap_diff/comparison_result"
+# Defines SnapDiff::RED_RGBA, the highlight_mask default color.
+require "snap_diff/annotation_service"
+
+module SnapDiff
+  module Drivers
+    class VipsDriver
+      include SnapDiff::Driver
+
+      def find_difference_region(comparison)
+        new_image, base_image, options = comparison.new_image, comparison.base_image, comparison.options
+
+        diff_mask = if options[:perceptual_threshold]
+          self.class.perceptual_difference_mask(base_image, new_image, options[:perceptual_threshold])
+        else
+          self.class.difference_mask(base_image, new_image, options[:color_distance_limit])
+        end
+        region = self.class.difference_region_by(diff_mask)
+        # TODO: schedule research when we got this case for VIPs
+        # region = nil if region && region_covers_entire_image?(region, base_image)
+
+        result = ComparisonResult.new(region, {}, comparison)
+
+        unless result.blank?
+          result.meta[:difference_level] = difference_level(diff_mask, base_image) if comparison.options[:tolerance]
+          result.meta[:diff_mask] = diff_mask
+        end
+
+        result
+      end
+
+      def crop(region, i)
+        i.crop(*region.to_top_left_corner_coordinates)
+      rescue Vips::Error => e
+        warn(
+          "[capybara-screenshot-diff] Crop has been failed for " \
+            "{ region: #{region.to_top_left_corner_coordinates.inspect}, image: #{dimension(i).join("x")} }"
+        )
+        raise e
+      end
+
+      def filter_image_with_median(image, median_filter_window_size)
+        image.median(median_filter_window_size)
+      end
+
+      def add_black_box(memo, region)
+        return memo unless region
+
+        memo.draw_rect([0, 0, 0, 0], *region.to_top_left_corner_coordinates, fill: true)
+      end
+
+      def difference_level(diff_mask, old_img, _region = nil)
+        self.class.difference_area_size_by(diff_mask).to_f / image_area_size(old_img)
+      end
+
+      MAX_FILENAME_LENGTH = 200
+
+      # Vips could not work with the same file. Per each process we require to create new file
+      def save_image_to(image, filename)
+        # Dir::Tmpname will happily produce tempfile names that are too long for most unix filesystems,
+        # which leads to "unix error: File name too long". Apply a limit to avoid this.
+        limited_filename = filename.to_s[-MAX_FILENAME_LENGTH..] || filename.to_s
+        ::Dir::Tmpname.create([limited_filename, PNG_EXTENSION]) do |tmp_image_filename|
+          image.write_to_file(tmp_image_filename)
+          FileUtils.mv(tmp_image_filename, filename)
+        end
+      end
+
+      def resize_image_to(image, new_width, new_height)
+        image.resize(new_width.to_f / image.width, vscale: new_height.to_f / image.height)
+      end
+
+      def load_images(old_file_name, new_file_name)
+        [from_file(old_file_name), from_file(new_file_name)]
+      end
+
+      def from_file(filename)
+        result = ::Vips::Image.new_from_file(filename.to_s)
+
+        result = result.colourspace(:srgb) if result.bands < 3
+        result = result.bandjoin(255) if result.bands == 3
+
+        result
+      end
+
+      def draw_rectangles(images, region, rgba, offset: 0)
+        images.map do |image|
+          image.draw_rect(rgba, region.left - offset, region.top - offset, region.width + (offset * 2), region.height + (offset * 2))
+        end
+      end
+
+      def same_pixels?(comparison)
+        (comparison.new_image == comparison.base_image).min == 255
+      end
+
+      def merge(new_image, base_image)
+        base_image.composite2(new_image, :over)
+      end
+
+      def highlight_mask(diff_mask, merged_image, color: SnapDiff::RED_RGBA)
+        diff_mask.ifthenelse(color, merged_image * 0.75)
+      end
+
+      private
+
+      class << self
+        def difference_area(old_image, new_image, color_distance: 0)
+          mask = difference_mask(new_image, old_image, color_distance)
+          difference_area_size_by(mask)
+        end
+
+        def difference_area_size_by(difference_mask)
+          diff_mask = difference_mask == 0
+          diff_mask.hist_find.to_a[0][0].max
+        end
+
+        def difference_mask(base_image, new_image, color_distance = nil)
+          result = (new_image - base_image).abs
+          color_distance ? result > color_distance : result
+        end
+
+        def perceptual_difference_mask(base_image, new_image, threshold = 2.0)
+          color_diff = perceptual_color_diff(base_image, new_image) > threshold
+          alpha_diff = alpha_channel_diff(base_image, new_image)
+          alpha_diff ? (color_diff | alpha_diff) : color_diff
+        end
+
+        def perceptual_color_diff(base_image, new_image)
+          base_rgb = (base_image.bands > 3) ? base_image.extract_band(0, n: 3) : base_image
+          new_rgb = (new_image.bands > 3) ? new_image.extract_band(0, n: 3) : new_image
+          base_lab = base_rgb.colourspace(:lab)
+          new_lab = new_rgb.colourspace(:lab)
+          base_lab.dE00(new_lab)
+        rescue Vips::Error
+          base_lab.dE76(new_lab)
+        end
+
+        def alpha_channel_diff(base_image, new_image)
+          return unless base_image.bands > 3 && new_image.bands > 3
+
+          (base_image.extract_band(3) - new_image.extract_band(3)).abs > 0
+        end
+
+        def difference_region_by(diff_mask)
+          columns, rows = diff_mask.bandor.project
+
+          left = columns.profile[1].min
+          right = columns.width - columns.flip(:horizontal).profile[1].min
+
+          top = rows.profile[0].min
+          bottom = rows.height - rows.flip(:vertical).profile[0].min
+
+          return nil if right < left || bottom < top
+
+          Region.from_edge_coordinates(left, top, right, bottom)
+        end
+      end
+    end
+  end
+end

data/lib/snap_diff/drivers.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SnapDiff
+  # Compare two images and determine if they are equal, different, or within some comparison
+  # range considering color values and difference area size.
+  module Drivers
+    def self.for(driver_options = {})
+      driver_option = driver_options.is_a?(Hash) ? driver_options.fetch(:driver, :chunky_png) : driver_options
+      return driver_option unless driver_option.is_a?(Symbol)
+
+      Utils.find_driver_class_for(driver_option).new
+    end
+  end
+end

data/lib/snap_diff/dsl.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+# No require of "capybara_screenshot_diff" here: every Capybara::Screenshot
+# / CapybaraScreenshotDiff reference below is inside a method body, resolved
+# lazily at call time, not at this file's own load time -- so this unit has
+# no eager dependency on the umbrella entry point, and requiring it here
+# would create a require cycle back to capybara_screenshot_diff.rb (which
+# requires this file's old-path forwarder).
+# DSL includes Capybara::DSL directly below, so it needs the base gem
+# loaded regardless of what pulled this file in.
+require "capybara/dsl"
+require "capybara/screenshot/diff/config_legacy"
+require "capybara/screenshot/diff/drivers"
+require "snap_diff/comparison"
+require "capybara/screenshot/diff/screenshot_matcher"
+require_relative "screenshot_namer"
+require_relative "screenshot_assertion"
+
+module SnapDiff
+  # DSL for taking screenshots and making assertions in Capybara tests.
+  # This module provides methods for taking screenshots, comparing them against baselines,
+  # and managing the comparison process with various configuration options.
+  #
+  # The DSL is designed to be included in your test context (e.g., RSpec, Minitest)
+  # to provide screenshot comparison capabilities.
+  module DSL
+    include Capybara::DSL
+
+    def screenshot_section(name)
+      screenshot_namer.section = name
+    end
+
+    def screenshot_group(name)
+      screenshot_namer.group = name
+    end
+
+    # Takes a screenshot and compares it against a baseline image.
+    #
+    # The method follows a layered optimization strategy for comparison:
+    # 1. First checks if screenshot functionality is active
+    # 2. Builds a full screenshot name using the current context
+    # 3. Creates a screenshot assertion object
+    # 4. Either validates immediately or defers validation based on options
+    #
+    # @param name [String] The base name of the screenshot, used to generate the filename.
+    # @param skip_stack_frames [Integer] The number of stack frames to skip when reporting errors.
+    # @param options [Hash] Additional options for taking the screenshot and comparison.
+    # @option options [Boolean] :delayed (Capybara::Screenshot::Diff.delayed)
+    #   Whether to validate the screenshot immediately or delay validation.
+    # @option options [Array<Integer>] :crop [left, top, right, bottom] Edge coordinates to crop the screenshot to.
+    # @option options [Array<Array<Integer>>] :skip_area Array of [left, top, right, bottom] edge coordinates to ignore.
+    # @option options [Numeric] :tolerance (0.001 for :vips driver) Color tolerance for comparison.
+    #   Represents the maximum allowed ratio of different pixels (0.0-1.0 scale).
+    # @option options [Numeric] :color_distance_limit Maximum allowed color distance between pixels.
+    #   Uses Euclidean RGBA distance (0-510 scale). Mutually exclusive with :perceptual_threshold.
+    # @option options [Numeric] :perceptual_threshold Maximum perceptual color difference (CIE dE00).
+    #   Uses human perception-based scale (0-100+). VIPS only. Takes priority over :color_distance_limit if both set.
+    # @option options [Numeric] :shift_distance_limit Maximum allowed shift distance for pixels.
+    # @option options [Numeric] :area_size_limit Maximum allowed difference area size in pixels.
+    # @option options [Symbol] :driver (:auto) The image processing driver to use (:auto, :chunky_png, :vips).
+    # @return [Boolean] True if the screenshot was successfully captured and processed.
+    # @raise [CapybaraScreenshotDiff::ExpectationNotMet] If comparison fails and immediate validation is enabled.
+    # @raise [CapybaraScreenshotDiff::UnstableImage] If the image comparison is unstable.
+    # @raise [CapybaraScreenshotDiff::WindowSizeMismatchError] If the window size doesn't match expectations.
+    def assert_matches_screenshot(name, skip_stack_frames: 0, **options)
+      return false unless Capybara::Screenshot.active?
+
+      # Get the full name with section and group information
+      full_name = CapybaraScreenshotDiff.screenshot_namer.full_name(name)
+
+      # Build the screenshot assertion
+      assertion = build_screenshot_assertion(full_name, options, skip_stack_frames: skip_stack_frames + 1)
+
+      return false unless assertion
+
+      # Determine if validation should be delayed or immediate
+      delayed = options.fetch(:delayed, Capybara::Screenshot::Diff.delayed)
+
+      if delayed
+        CapybaraScreenshotDiff.add_assertion(assertion)
+      else
+        assertion.validate!
+      end
+
+      true
+    end
+
+    # Convenience wrapper around {#assert_matches_screenshot} and {#capture_screenshot}.
+    # @param compare [Boolean] When false, only captures the screenshot without comparing it to a baseline.
+    # @see #assert_matches_screenshot
+    # @see #capture_screenshot
+    def screenshot(name, skip_stack_frames: 0, compare: true, **options)
+      if compare
+        assert_matches_screenshot(name, skip_stack_frames: skip_stack_frames + 1, **options)
+      else
+        capture_screenshot(name, **options)
+      end
+    end
+
+    # Captures a screenshot without comparing it to a baseline.
+    # @param name [String] The base name of the screenshot, used to generate the filename.
+    # @param options [Hash] Additional options for taking the screenshot. See {#assert_matches_screenshot}.
+    # @return [Boolean] True if the screenshot was successfully captured.
+    def capture_screenshot(name, **options)
+      return false unless Capybara::Screenshot.active?
+
+      full_name = CapybaraScreenshotDiff.screenshot_namer.full_name(name)
+      SnapDiff::ScreenshotMatcher.new(full_name, options).capture
+
+      true
+    end
+
+    # Asserts the current page has no visual changes from the baseline.
+    # Override in your base test class to add project-specific behavior
+    # (e.g., waiting for Turbo, default skip areas).
+    def assert_no_screenshot_changes(name, skip_stack_frames: 0, **opts)
+      assert_matches_screenshot(name, skip_stack_frames: skip_stack_frames + 1, **opts)
+    end
+
+    private
+
+    # Builds a screenshot assertion object that can be validated immediately or later.
+    #
+    # This method constructs a screenshot assertion that encapsulates the comparison logic.
+    # The actual comparison is deferred until {ScreenshotAssertion#validate!} is called.
+    #
+    # @param name [String] The full name of the screenshot, including any section/group context.
+    # @param options [Hash] Options for screenshot taking and comparison.
+    #   See {#assert_matches_screenshot} for available options.
+    # @param skip_stack_frames [Integer] Number of stack frames to skip for error reporting.
+    # @return [ScreenshotAssertion, nil] The assertion object or nil if no assertion is needed.
+    # @see ScreenshotAssertion
+    def build_screenshot_assertion(name, options, skip_stack_frames: 0)
+      SnapDiff::ScreenshotMatcher
+        .new(name, options)
+        .build_screenshot_assertion(skip_stack_frames: skip_stack_frames + 1)
+    end
+
+    def screenshot_namer
+      CapybaraScreenshotDiff.screenshot_namer
+    end
+  end
+end

data/lib/snap_diff/error_with_filtered_backtrace.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SnapDiff
+  class BacktraceFilter
+    LIB_DIRECTORY = File.expand_path(File.join(File.dirname(__FILE__), "..")) + File::SEPARATOR
+
+    def initialize(lib_directory = LIB_DIRECTORY)
+      # Trailing separator keeps the prefix match on a directory boundary,
+      # so "/app/lib" does not also reject "/app/library".
+      @lib_directory = lib_directory.end_with?(File::SEPARATOR) ? lib_directory : lib_directory + File::SEPARATOR
+    end
+
+    # Filters out any backtrace lines originating from the library directory or from gems such as ActiveSupport, Minitest, and Railties
+    # @param backtrace [Array<String>]
+    # @return [Array<String>]
+    def filtered(backtrace)
+      backtrace
+        .reject { |location| File.expand_path(location).start_with?(@lib_directory) }
+        .reject { |l| l =~ /gems\/(activesupport|minitest|railties)/ }
+    end
+  end
+
+  # @private
+  class ErrorWithFilteredBacktrace < StandardError
+    # @private
+    def initialize(message = nil, backtrace = [])
+      super(message)
+      filter = BacktraceFilter.new
+      set_backtrace(filter.filtered(backtrace))
+    end
+  end
+end

data/lib/snap_diff/image_preprocessor.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module SnapDiff
+  # Handles image preprocessing operations (skip_area and median filtering)
+  #
+  # This class applies preprocessing filters to images before comparison,
+  # such as masking specific regions (skip_area) or applying noise reduction.
+  # It's designed to work with either direct image objects or with options.
+  class ImagePreprocessor
+    attr_reader :driver, :options
+
+    def initialize(driver, options = {})
+      @driver = driver
+      @options = options
+    end
+
+    # Process a comparison object directly
+    # This allows reusing the comparison's existing options
+    # @param [Comparison] comparison the comparison object
+    # @return [Comparison] the comparison object
+    def process_comparison(comparison)
+      # Process both images
+      comparison.base_image = process_image(comparison.base_image, comparison.base_image_path)
+      comparison.new_image = process_image(comparison.new_image, comparison.new_image_path)
+
+      comparison
+    end
+
+    private
+
+    def process_image(image, path)
+      result = image
+      result = apply_skip_area(result) if skip_area
+      result = apply_median_filter(result, path) if median_filter_window_size
+      result
+    end
+
+    def apply_skip_area(image)
+      skip_area.reduce(image) do |result, region|
+        driver.add_black_box(result, region)
+      end
+    end
+
+    def apply_median_filter(image, path)
+      if driver.supports?(:filter_image_with_median)
+        driver.filter_image_with_median(image, median_filter_window_size)
+      else
+        warn_about_skipped_median_filter(path)
+        image
+      end
+    end
+
+    def warn_about_skipped_median_filter(path)
+      warn(
+        "[capybara-screenshot-diff] Median filter has been skipped for #{path} " \
+        "because it is not supported by #{driver.class}"
+      )
+    end
+
+    def skip_area
+      options[:skip_area]
+    end
+
+    def median_filter_window_size
+      options[:median_filter_window_size]
+    end
+  end
+end

data/lib/snap_diff/integrations/cucumber.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# See the matching comment in integrations/minitest.rb.
+require_relative "../dsl"
+require "capybara_screenshot_diff/screenshot_assertion"
+
+World(::SnapDiff::DSL)
+
+Before do
+  Capybara::Screenshot::Diff.delayed = false
+  SnapDiff::BrowserHelpers.resize_window_if_needed
+end
+
+After do |scenario|
+  if !scenario.failed? && (msg = CapybaraScreenshotDiff.pending_screenshots_message)
+    skip_this_scenario(msg)
+  end
+ensure
+  CapybaraScreenshotDiff.reset
+end
+
+AfterAll { CapybaraScreenshotDiff.finalize_reporters! }

data/lib/snap_diff/integrations/minitest.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "minitest"
+require_relative "../dsl"
+# The CapybaraScreenshotDiff.verify/.reset/.pending_screenshots_message/
+# .finalize_reporters! calls below need the registry singleton machinery,
+# which lives in the *old* capybara_screenshot_diff/screenshot_assertion.rb
+# file (deliberately not moved -- see that file's own comment) and is no
+# longer pulled in transitively by requiring dsl.rb alone.
+require "capybara_screenshot_diff/screenshot_assertion"
+
+used_deprecated_entrypoint = caller.any? do |path|
+  path.include?("capybara-screenshot-diff.rb") || path.include?("capybara/screenshot/diff.rb")
+end
+
+if used_deprecated_entrypoint
+  warn <<~MSG
+    [DEPRECATION] The default activation of `capybara_screenshot_diff/minitest` will be removed.
+                  Please `require "capybara_screenshot_diff/minitest"` explicitly.
+  MSG
+end
+
+module SnapDiff
+  module Minitest
+    module Assertions
+      include ::SnapDiff::DSL
+
+      def assert_matches_screenshot(*args, skip_stack_frames: 0, **opts)
+        self.assertions += 1
+
+        super(*args, skip_stack_frames: skip_stack_frames + 1, **opts)
+      rescue ::CapybaraScreenshotDiff::ExpectationNotMet => e
+        raise ::Minitest::Assertion, e.message
+      end
+
+      def setup
+        super
+        ::SnapDiff::BrowserHelpers.resize_window_if_needed
+      end
+
+      def before_teardown
+        super
+        CapybaraScreenshotDiff.verify
+
+        # Computed here (before teardown/reset), but the actual `skip` is
+        # deferred to `after_teardown` so a real error raised by the user's
+        # `teardown` isn't masked by a pending skip recorded before it ran.
+        @capybara_screenshot_diff_pending_message = CapybaraScreenshotDiff.pending_screenshots_message
+      rescue CapybaraScreenshotDiff::ExpectationNotMet => e
+        assertion = ::Minitest::Assertion.new(e)
+        assertion.set_backtrace(e.backtrace)
+        failures << assertion
+      ensure
+        CapybaraScreenshotDiff.reset
+      end
+
+      def after_teardown
+        super
+
+        # Never mask a real failure (from `verify` above or from the user's
+        # own `teardown`) with a pending marker.
+        if failures.empty? && (msg = @capybara_screenshot_diff_pending_message)
+          skip(msg)
+        end
+      end
+    end
+  end
+end
+
+::Minitest.after_run { CapybaraScreenshotDiff.finalize_reporters! } if ::Minitest.respond_to?(:after_run)

data/lib/snap_diff/integrations/rspec.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+require_relative "../dsl"
+# See the matching comment in integrations/minitest.rb.
+require "capybara_screenshot_diff/screenshot_assertion"
+
+RSpec::Matchers.define :match_screenshot do |name, **options|
+  description { "match screenshot '#{name}'" }
+
+  match do |_page|
+    assert_matches_screenshot(name, **options)
+    true
+  end
+
+  failure_message do
+    "Expected page to match screenshot '#{name}'"
+  end
+
+  failure_message_when_negated do
+    "Expected page not to match screenshot '#{name}'"
+  end
+end
+
+RSpec.configure do |config|
+  config.include SnapDiff::DSL, type: :feature
+  config.include SnapDiff::DSL, type: :system
+
+  config.before do
+    if self.class.include?(SnapDiff::DSL)
+      SnapDiff::BrowserHelpers.resize_window_if_needed
+    end
+  end
+
+  # `append_after` (as opposed to the default `after`, which prepends) adds
+  # this hook to the *end* of the after-hook chain regardless of when it's
+  # registered relative to the user's own `after`/`config.after` hooks. RSpec
+  # runs `after(:each)` hooks in reverse registration order, so a plain
+  # `config.after` here would run BEFORE a user hook registered earlier in
+  # their own spec_helper (before this file was required) -- and if that
+  # later-running user hook raises, its exception gets folded into
+  # `pending_exception` instead of `example.exception`, silently masking the
+  # failure behind our pending skip. `append_after` runs after the full user
+  # after-chain no matter the registration order, closing that gap.
+  config.append_after do |example|
+    if self.class.include?(SnapDiff::DSL)
+      begin
+        CapybaraScreenshotDiff.verify
+
+        # Never mask a real failure with a pending marker. Kept as
+        # defense-in-depth: `append_after` observes failures from plain
+        # `after`/`prepend_after` user hooks, but appended hooks run FIFO,
+        # so a user `append_after` registered after this gem still runs
+        # later than us — RSpec has no "run absolutely last" construct.
+        # Mitigation for such consumers: require this gem last.
+        if example.exception.nil? && (msg = CapybaraScreenshotDiff.pending_screenshots_message)
+          skip(msg)
+        end
+      rescue CapybaraScreenshotDiff::ExpectationNotMet => e
+        raise RSpec::Expectations::ExpectationNotMetError.new(e.message).tap { |ex| ex.set_backtrace(e.backtrace) }
+      ensure
+        CapybaraScreenshotDiff.reset
+      end
+    end
+  end
+
+  config.after(:suite) { CapybaraScreenshotDiff.finalize_reporters! }
+end