capybara-screenshot-diff 1.10.3.1 → 1.13.0

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

@@ -25,8 +25,7 @@ module Capybara
 
           @comparison_options = comparison_options
 
-          driver = Diff::Drivers.for(@comparison_options)
-          @screenshoter = Diff.screenshoter.new(capture_options.except(:stability_time_limit), driver)
+          @screenshoter = Diff.screenshoter.new(capture_options.except(:stability_time_limit), @comparison_options)
         end
 
         # Takes a comparison screenshot ensuring page stability
@@ -51,7 +50,7 @@ module Capybara
           snapshot.commit_last_attempt
 
           # cleanup all previous attempts
-          snapshot.cleanup_attempts
+          snapshot.cleanup_attempts!
         end
 
         def take_stable_screenshot(snapshot)
@@ -59,16 +58,15 @@ module Capybara
           deadline_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + wait
 
           # Cleanup all previous attempts for sure
-          snapshot.cleanup_attempts
-
-          0.step do |i|
-            # FIXME: it should be wait, and wait should be replaced with stability_time_limit
-            sleep(stability_time_limit) unless i == 0 # test prev_attempt_path is nil
+          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
 
@@ -100,7 +98,7 @@ module Capybara
           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, attempts_reporter.generate
+          raise CapybaraScreenshotDiff::UnstableImage.new(attempts_reporter.generate, caller)
         end
       end
     end

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "open3"
 require_relative "os"
 
 module Capybara
@@ -7,64 +8,30 @@ module Capybara
     module Diff
       module Vcs
         def self.checkout_vcs(root, screenshot_path, checkout_path)
-          if svn?(root)
-            restore_svn_revision(screenshot_path, checkout_path)
-          else
-            restore_git_revision(screenshot_path, checkout_path, root: root)
-          end
-        end
-
-        def self.svn?(root)
-          (root / ".svn").exist?
-        end
-
-        SILENCE_ERRORS = Os::ON_WINDOWS ? "2>nul" : "2>/dev/null"
-
-        def self.restore_git_revision(screenshot_path, checkout_path = screenshot_path, root:)
-          vcs_file_path = screenshot_path.relative_path_from(root)
-          redirect_target = "#{checkout_path} #{SILENCE_ERRORS}"
-          show_command = "git show HEAD~0:./#{vcs_file_path}"
-
-          Dir.chdir(root) do
-            if Screenshot.use_lfs
-              system("#{show_command} > #{checkout_path}.tmp #{SILENCE_ERRORS}", exception: !!ENV["DEBUG"])
-
-              `git lfs smudge < #{checkout_path}.tmp > #{redirect_target}` if $CHILD_STATUS == 0
-
-              File.delete "#{checkout_path}.tmp"
-            else
-              system("#{show_command} > #{redirect_target}", exception: !!ENV["DEBUG"])
+          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
-          end
-
-          if $CHILD_STATUS != 0
-            checkout_path.delete if checkout_path.exist?
-            false
+            File.delete(tmp_path) if File.exist?(tmp_path)
           else
-            true
+            success = system("git", "-C", root_path, "show", "HEAD:#{vcs_file_path}", out: checkout_path.to_s, err: File::NULL)
           end
-        end
 
-        def self.restore_svn_revision(screenshot_path, checkout_path)
-          committed_file_name = screenshot_path + "../.svn/text-base/" + "#{screenshot_path.basename}.svn-base"
-          if committed_file_name.exist?
-            FileUtils.cp(committed_file_name, checkout_path)
-            return true
-          end
-
-          svn_info = `svn info #{screenshot_path} #{SILENCE_ERRORS}`
-          unless svn_info.empty?
-            wc_root = svn_info.slice(/(?<=Working Copy Root Path: ).*$/)
-            checksum = svn_info.slice(/(?<=Checksum: ).*$/)
-
-            if checksum
-              committed_file_name = "#{wc_root}/.svn/pristine/#{checksum[0..1]}/#{checksum}.svn-base"
-              FileUtils.cp(committed_file_name, checkout_path)
-              return true
-            end
+          unless success
+            checkout_path.delete if checkout_path.exist?
+            return false
           end
 
-          false
+          true
         end
       end
     end

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

@@ -3,7 +3,7 @@
 module Capybara
   module Screenshot
     module Diff
-      VERSION = "1.10.3.1"
+      VERSION = "1.13.0"
     end
   end
 end

data/lib/capybara_screenshot_diff/backtrace_filter.rb

@@ -0,0 +1,20 @@
+# 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)
+      @lib_directory = lib_directory
+    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
+end

data/lib/capybara_screenshot_diff/cucumber.rb

@@ -8,3 +8,14 @@ Before do
   Capybara::Screenshot::Diff.delayed = false
   Capybara::Screenshot::BrowserHelpers.resize_window_if_needed
 end
+
+After do |scenario|
+  if !scenario.failed? && Capybara::Screenshot::Diff.pending_if_new && CapybaraScreenshotDiff.new_screenshots_present?
+    names = CapybaraScreenshotDiff.new_screenshots
+    skip_this_scenario("No baseline for: #{names.join(", ")}. Commit the captured screenshots to record them.")
+  end
+ensure
+  CapybaraScreenshotDiff.reset
+end
+
+AfterAll { CapybaraScreenshotDiff.finalize_reporters! }

data/lib/capybara_screenshot_diff/dsl.rb

@@ -1,18 +1,134 @@
 # frozen_string_literal: true
 
 require "capybara_screenshot_diff"
-require "capybara/screenshot/diff/test_methods"
-require_relative "screenshot_assertion"
+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"
 
 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
-    include Capybara::Screenshot::Diff::TestMethods
 
-    alias_method :_screenshot, :screenshot
-    def screenshot(name, **args)
-      assertion = CapybaraScreenshotDiff::ScreenshotAssertion.new(name, **args) { _screenshot(name, **args) }
-      CapybaraScreenshotDiff.add_assertion(assertion)
+    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
 end

data/lib/capybara_screenshot_diff/error_with_filtered_backtrace.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "capybara_screenshot_diff/backtrace_filter"
+
+module CapybaraScreenshotDiff
+  # @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/capybara_screenshot_diff/minitest.rb

@@ -19,16 +19,14 @@ module CapybaraScreenshotDiff
     module Assertions
       include ::CapybaraScreenshotDiff::DSL
 
-      def screenshot(*args, skip_stack_frames: 0, **opts)
+      def assert_matches_screenshot(*args, skip_stack_frames: 0, **opts)
         self.assertions += 1
 
-        super(*args, skip_stack_frames: skip_stack_frames + 3, **opts)
+        super(*args, skip_stack_frames: skip_stack_frames + 1, **opts)
       rescue ::CapybaraScreenshotDiff::ExpectationNotMet => e
         raise ::Minitest::Assertion, e.message
       end
 
-      alias_method :assert_matches_screenshot, :screenshot
-
       def setup
         super
         ::Capybara::Screenshot::BrowserHelpers.resize_window_if_needed
@@ -37,9 +35,14 @@ module CapybaraScreenshotDiff
       def before_teardown
         super
         CapybaraScreenshotDiff.verify
+
+        if ::Capybara::Screenshot::Diff.pending_if_new && CapybaraScreenshotDiff.new_screenshots_present?
+          names = CapybaraScreenshotDiff.new_screenshots
+          skip "No baseline for: #{names.join(", ")}. Commit the captured screenshots to record them."
+        end
       rescue CapybaraScreenshotDiff::ExpectationNotMet => e
         assertion = ::Minitest::Assertion.new(e)
-        assertion.set_backtrace []
+        assertion.set_backtrace(e.backtrace)
         failures << assertion
       ensure
         CapybaraScreenshotDiff.reset
@@ -47,3 +50,5 @@ module CapybaraScreenshotDiff
     end
   end
 end
+
+::Minitest.after_run { CapybaraScreenshotDiff.finalize_reporters! } if ::Minitest.respond_to?(:after_run)

data/lib/capybara_screenshot_diff/reporters/html.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "base64"
+require "erb"
+require "fileutils"
+require "pathname"
+require "json"
+
+module CapybaraScreenshotDiff
+  module Reporters
+    class HTML
+      attr_reader :failures, :total
+
+      def initialize(output_path: nil, embed_images: false)
+        @explicit_output_path = output_path
+        @embed_images = embed_images
+        @failures = []
+        @total = 0
+        @finalized = false
+        @mutex = Mutex.new
+      end
+
+      def record(assertions)
+        return if @finalized
+
+        failures = []
+        total = 0
+
+        assertions.each do |assertion|
+          compare = assertion.compare
+          next unless compare
+
+          total += 1
+          next unless compare.difference&.different?
+
+          failures << failure_entry_for(assertion.name, compare)
+        rescue => e
+          warn "[snap_diff] Reporter skipped '#{assertion.name}': #{e.message}" if ENV["DEBUG"]
+        end
+
+        @mutex.synchronize do
+          return if @finalized
+          @total += total
+          @failures.concat(failures)
+        end
+      end
+
+      def finalize
+        @mutex.synchronize do
+          return if @finalized
+          return if failures.empty?
+
+          write_report
+          @finalized = true
+          output_path
+        end
+      end
+
+      def output_path
+        @output_path ||= Pathname.new(@explicit_output_path || self.class.default_output_path)
+      end
+
+      def passed = total - failures.size
+      def failed = failures.size
+
+      def summary
+        return if total.zero?
+
+        screenshots_label = (total == 1) ? "1 screenshot" : "#{total} screenshots"
+
+        if failures.empty?
+          "[snap_diff] #{screenshots_label} compared, no failures."
+        else
+          failures_label = (failures.size == 1) ? "1 failure" : "#{failures.size} failures"
+          "[snap_diff] #{screenshots_label} compared, #{failures_label}. Report: #{output_path}"
+        end
+      end
+
+      def render
+        ERB.new(File.read(self.class.template_path)).result(binding)
+      end
+
+      def self.template_path
+        File.expand_path("templates/report.html.erb", __dir__)
+      end
+
+      def self.default_output_path
+        root = Capybara::Screenshot.root || Pathname.pwd
+        root / Capybara::Screenshot.save_path / "snap_diff_report.html"
+      end
+
+      private
+
+      def failure_entry_for(name, compare)
+        difference = compare.difference
+        {
+          name: name,
+          original: resolve_image(compare.base_image_path),
+          new: resolve_image(compare.image_path),
+          base_diff: resolve_image(compare.reporter.annotated_base_image_path),
+          diff: resolve_image(compare.reporter.annotated_image_path),
+          heatmap: resolve_image(compare.reporter.heatmap_diff_path),
+          diff_level: difference.ratio && (difference.ratio * 100).round(2),
+          area_size: difference.region_area_size,
+          max_color_distance: difference.meta[:max_color_distance]&.round(1)
+        }
+      end
+
+      def resolve_image(path)
+        return unless path
+
+        pathname = Pathname.new(path).expand_path
+        return unless pathname.exist?
+
+        @embed_images ? data_uri(pathname) : pathname.relative_path_from(output_path.dirname.expand_path).to_s
+      end
+
+      def data_uri(pathname)
+        ext = pathname.extname.delete_prefix(".")
+        mime = (ext == "webp") ? "image/webp" : "image/png"
+        "data:#{mime};base64,#{Base64.strict_encode64(pathname.binread)}"
+      end
+
+      def write_report
+        FileUtils.mkdir_p(output_path.dirname)
+        File.write(output_path, render)
+      end
+    end
+  end
+end
+
+# Auto-register reporter.
+# Framework adapters (Minitest, RSpec, Cucumber) call finalize_reporters! via native hooks.
+# For custom frameworks, call CapybaraScreenshotDiff.finalize_reporters! manually.
+unless CapybaraScreenshotDiff.reporters.any?(CapybaraScreenshotDiff::Reporters::HTML)
+  CapybaraScreenshotDiff.reporters << CapybaraScreenshotDiff::Reporters::HTML.new(embed_images: !!ENV["CI"])
+end