capybara-screenshot-diff 1.15.0 → 2.0.0.alpha1

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

@@ -1,106 +1,7 @@
 # frozen_string_literal: true
 
-module Capybara
-  module Screenshot
-    module Diff
-      class StableScreenshoter
-        STABILITY_OPTIONS = [:stability_time_limit, :wait]
-
-        attr_reader :stability_time_limit, :wait
-
-        # Initializes a new instance of StableScreenshoter
-        #
-        # This method sets up a new screenshoter with specific capture and comparison options. It validates the presence of
-        # `:stability_time_limit` and `:wait` in capture options and ensures that `:stability_time_limit` is less than or equal to `:wait`.
-        #
-        # @param capture_options [Hash] The options for capturing screenshots, must include `:stability_time_limit` and `:wait`.
-        # @param comparison_options [Hash] The options for comparing screenshots, defaults to `{}`. Same signature as {Capybara::Screenshot::Screenshoter#initialize}.
-        # @raise [ArgumentError] If `:wait` or `:stability_time_limit` are not provided, or if `:stability_time_limit` is greater than `:wait`.
-        def initialize(capture_options, comparison_options = {})
-          @stability_time_limit, @wait = capture_options.fetch_values(*STABILITY_OPTIONS)
-
-          raise ArgumentError, "wait should be provided for stable screenshots" unless wait
-          raise ArgumentError, "stability_time_limit should be provided for stable screenshots" unless stability_time_limit
-          raise ArgumentError, "stability_time_limit (#{stability_time_limit}) should be less or equal than wait (#{wait}) for stable screenshots" unless stability_time_limit <= wait
-
-          @comparison_options = comparison_options
-
-          @screenshoter = Diff.screenshoter.new(capture_options.except(:stability_time_limit), @comparison_options)
-        end
-
-        # Takes a comparison screenshot ensuring page stability
-        #
-        # Attempts to take a stable screenshot of the page by comparing several screenshot attempts until the page stops updating
-        # or the `:wait` limit is reached. If unable to achieve a stable state within the time limit, it annotates the attempts
-        # to aid debugging.
-        #
-        # @param snapshot Snap The snapshot details to take a stable screenshot of.
-        # @return [void]
-        # @raise [RuntimeError] If a stable screenshot cannot be obtained within the specified `:wait` time.
-        def take_comparison_screenshot(snapshot)
-          result = take_stable_screenshot(snapshot)
-
-          # We failed to get stable browser state! Generate difference between attempts to overview moving parts!
-          unless result
-            # FIXME(uwe): Change to store the failure and only report if the test succeeds functionally.
-            annotate_attempts_and_fail!(snapshot)
-          end
-
-          # store success attempt as actual screenshot
-          snapshot.commit_last_attempt
-
-          # cleanup all previous attempts
-          snapshot.cleanup_attempts!
-        end
-
-        def take_stable_screenshot(snapshot)
-          # We try to compare first attempt with checkout version, in order to not run next screenshots
-          deadline_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + wait
-
-          # Cleanup all previous attempts for sure
-          snapshot.cleanup_attempts!
-
-          loop do
-            attempt_next_screenshot(snapshot)
-
-            return true if attempt_successful?(snapshot)
-            return false if timeout?(deadline_at)
-
-            sleep(stability_time_limit)
-          end
-        end
-
-        private
-
-        def attempt_successful?(snapshot)
-          return false unless snapshot.prev_attempt_path
-
-          build_last_attempts_comparison_for(snapshot).quick_equal?
-        rescue ArgumentError
-          false
-        end
-
-        def attempt_next_screenshot(snapshot)
-          @screenshoter.take_screenshot(snapshot.next_attempt_path!)
-        end
-
-        def timeout?(deadline_at)
-          Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline_at
-        end
-
-        def build_last_attempts_comparison_for(snapshot)
-          ImageCompare.new(snapshot.attempt_path, snapshot.prev_attempt_path, @comparison_options)
-        end
-
-        # TODO: Move to the HistoricalReporter
-        def annotate_attempts_and_fail!(snapshot)
-          require "capybara_screenshot_diff/attempts_reporter"
-          attempts_reporter = CapybaraScreenshotDiff::AttemptsReporter.new(snapshot, @comparison_options, {wait: wait, stability_time_limit: stability_time_limit})
-
-          # TODO: Move fail to the queue after tests passed
-          raise CapybaraScreenshotDiff::UnstableImage.new(attempts_reporter.generate, caller)
-        end
-      end
-    end
-  end
-end
+# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Diff::StableScreenshoter
+# now resolves lazily via snap_diff/legacy_shims' const_missing, with a
+# deprecation warning pointing at SnapDiff::StableScreenshoter.
+require "snap_diff/stable_screenshoter"
+require "snap_diff/legacy_shims"

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

@@ -1,42 +1,7 @@
 # frozen_string_literal: true
 
-module Capybara
-  module Screenshot
-    module Diff
-      module Utils
-        def self.detect_available_drivers
-          result = []
-          begin
-            result << :vips if defined?(Vips) || require("vips")
-          rescue LoadError
-            # vips not present
-            Object.send(:remove_const, :Vips) if defined?(Vips)
-          end
-          begin
-            result << :chunky_png if defined?(ChunkyPNG) || require("chunky_png")
-          rescue LoadError
-            # chunky_png not present
-            Object.send(:remove_const, :ChunkyPNG) if defined?(ChunkyPNG)
-          end
-          result
-        end
-
-        def self.find_driver_class_for(driver)
-          driver = AVAILABLE_DRIVERS.first if driver == :auto
-
-          LOADED_DRIVERS[driver] ||=
-            case driver
-            when :chunky_png
-              require "capybara/screenshot/diff/drivers/chunky_png_driver"
-              Drivers::ChunkyPNGDriver
-            when :vips
-              require "capybara/screenshot/diff/drivers/vips_driver"
-              Drivers::VipsDriver
-            else
-              fail "Wrong adapter #{driver.inspect}. Available adapters: #{AVAILABLE_DRIVERS.inspect}"
-            end
-        end
-      end
-    end
-  end
-end
+# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Diff::Utils now
+# resolves lazily via snap_diff/legacy_shims' const_missing, with a
+# deprecation warning pointing at SnapDiff::Utils.
+require "snap_diff/utils"
+require "snap_diff/legacy_shims"

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

@@ -1,39 +1,7 @@
 # frozen_string_literal: true
 
-require "open3"
-require_relative "os"
-
-module Capybara
-  module Screenshot
-    module Diff
-      module Vcs
-        def self.checkout_vcs(root, screenshot_path, checkout_path)
-          root_path = root.to_s
-          git_root, _, status = Open3.capture3("git", "-C", root_path, "rev-parse", "--show-toplevel")
-          return false unless status.success?
-
-          git_root = git_root.chomp
-          vcs_file_path = Pathname.new(screenshot_path).expand_path.relative_path_from(Pathname.new(git_root)).to_s
-
-          if Screenshot.use_lfs
-            tmp_path = "#{checkout_path}.tmp"
-            success = system("git", "-C", root_path, "show", "HEAD:#{vcs_file_path}", out: tmp_path, err: File::NULL)
-            if success
-              system("git", "-C", root_path, "lfs", "smudge", in: tmp_path, out: checkout_path.to_s, err: File::NULL)
-            end
-            File.delete(tmp_path) if File.exist?(tmp_path)
-          else
-            success = system("git", "-C", root_path, "show", "HEAD:#{vcs_file_path}", out: checkout_path.to_s, err: File::NULL)
-          end
-
-          unless success
-            checkout_path.delete if checkout_path.exist?
-            return false
-          end
-
-          true
-        end
-      end
-    end
-  end
-end
+# Forwarder (ADR-004 v2 step 6): Capybara::Screenshot::Diff::Vcs now
+# resolves lazily via snap_diff/legacy_shims' const_missing, with a
+# deprecation warning pointing at SnapDiff::Vcs.
+require "snap_diff/vcs"
+require "snap_diff/legacy_shims"

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

@@ -1,9 +1,15 @@
 # frozen_string_literal: true
 
+require "snap_diff/version"
+
+# Deliberately EAGER and silent (v2 step 6 exception): the gemspec resolves
+# Capybara::Screenshot::Diff::VERSION at build time, so a lazy warning shim
+# would make every `gem build` warn. See snap_diff/legacy_shims.rb for the
+# full exception list.
 module Capybara
   module Screenshot
     module Diff
-      VERSION = "1.15.0"
+      VERSION = SnapDiff::VERSION
     end
   end
 end

data/lib/capybara_screenshot_diff/attempts_reporter.rb

@@ -1,49 +1,7 @@
 # frozen_string_literal: true
 
-require "capybara/screenshot/diff/image_compare"
-
-module CapybaraScreenshotDiff
-  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)
-      Capybara::Screenshot::Diff::ImageCompare.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
+# Forwarder (ADR-004 v2 step 6): CapybaraScreenshotDiff::AttemptsReporter now
+# resolves lazily via snap_diff/legacy_shims' const_missing, with a
+# deprecation warning pointing at SnapDiff::AttemptsReporter.
+require "snap_diff/attempts_reporter"
+require "snap_diff/legacy_shims"

data/lib/capybara_screenshot_diff/cucumber.rb

@@ -1,20 +1,8 @@
 # frozen_string_literal: true
 
-require "capybara_screenshot_diff/dsl"
+# Legacy entry point: pre-move, this path transitively loaded the whole gem
+# (via dsl -> umbrella). Preserve that contract for consumers who require
+# only this file.
+require "capybara_screenshot_diff"
 
-World(::CapybaraScreenshotDiff::DSL)
-
-Before do
-  Capybara::Screenshot::Diff.delayed = false
-  Capybara::Screenshot::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! }
+require "snap_diff/integrations/cucumber"

data/lib/capybara_screenshot_diff/dsl.rb

@@ -1,134 +1,12 @@
 # frozen_string_literal: true
 
-require "capybara_screenshot_diff"
-require "capybara/screenshot/diff/drivers"
-require "capybara/screenshot/diff/image_compare"
-require "capybara/screenshot/diff/screenshot_matcher"
-require "capybara_screenshot_diff/screenshot_namer"
-require "capybara_screenshot_diff/screenshot_assertion"
+require "snap_diff/dsl"
 
+# Deliberately EAGER and silent (v2 step 6 exception): DSL is an advertised
+# entry-point constant probed with Object.const_defined? by
+# support_load_probe_test.rb, and const_defined? never triggers
+# const_missing -- a lazy shim would break that contract. See
+# snap_diff/legacy_shims.rb for the full exception list.
 module CapybaraScreenshotDiff
-  # 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)
-      Capybara::Screenshot::Diff::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)
-      Capybara::Screenshot::Diff::ScreenshotMatcher
-        .new(name, options)
-        .build_screenshot_assertion(skip_stack_frames: skip_stack_frames + 1)
-    end
-
-    def screenshot_namer
-      CapybaraScreenshotDiff.screenshot_namer
-    end
-  end
+  DSL = SnapDiff::DSL
 end

data/lib/capybara_screenshot_diff/error_with_filtered_backtrace.rb

@@ -1,32 +1,8 @@
 # frozen_string_literal: true
 
-module CapybaraScreenshotDiff
-  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
+# Forwarder (ADR-004 v2 step 6): CapybaraScreenshotDiff::BacktraceFilter and
+# CapybaraScreenshotDiff::ErrorWithFilteredBacktrace now resolve lazily via
+# snap_diff/legacy_shims' const_missing, with deprecation warnings pointing
+# at their SnapDiff:: replacements.
+require "snap_diff/error_with_filtered_backtrace"
+require "snap_diff/legacy_shims"

data/lib/capybara_screenshot_diff/minitest.rb

@@ -1,64 +1,14 @@
 # frozen_string_literal: true
 
-require "minitest"
-require "capybara_screenshot_diff/dsl"
+# Legacy entry point: pre-move, this path transitively loaded the whole gem
+# (via dsl -> umbrella). Preserve that contract for consumers who require
+# only this file.
+require "capybara_screenshot_diff"
 
-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
+require "snap_diff/integrations/minitest"
 
 module CapybaraScreenshotDiff
   module Minitest
-    module Assertions
-      include ::CapybaraScreenshotDiff::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
-        ::Capybara::Screenshot::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
+    Assertions = SnapDiff::Minitest::Assertions
   end
 end
-
-::Minitest.after_run { CapybaraScreenshotDiff.finalize_reporters! } if ::Minitest.respond_to?(:after_run)