capybara-screenshot-diff 1.10.3 → 1.12.0

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Screenshot
+    module Diff
+      # 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
+  end
+end

data/lib/capybara/screenshot/diff/reporters/default.rb

@@ -8,7 +8,8 @@ module Capybara::Screenshot::Diff
       def initialize(difference)
         @difference = difference
 
-        screenshot_format = difference.comparison.options[:screenshot_format] || comparison.new_image_path.extname.slice(1..-1)
+        ext = comparison.new_image_path.extname.delete_prefix(".")
+        screenshot_format = difference.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}")
@@ -32,6 +33,7 @@ module Capybara::Screenshot::Diff
       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 build_error_for_different_dimensions
@@ -45,27 +47,23 @@ module Capybara::Screenshot::Diff
       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.meta[:diff_mask]
+        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.skip_area) if difference.skip_area
+        image = annotate_skip_areas(image, difference.comparison.skip_area) if difference.comparison.skip_area
 
         save(image, image_path.to_path)
       end
 
-      DIFF_COLOR = [255, 0, 0, 255].freeze
-
       def annotate_difference(image, region)
-        driver.draw_rectangles([image], region, DIFF_COLOR, offset: 1).first
+        driver.draw_rectangles([image], region, CapybaraScreenshotDiff::RED_RGBA, offset: 1).first
       end
 
-      SKIP_COLOR = [255, 192, 0, 255].freeze
-
       def annotate_skip_areas(image, skip_areas)
         skip_areas.reduce(image) do |memo, region|
-          driver.draw_rectangles([memo], region, SKIP_COLOR).first
+          driver.draw_rectangles([memo], region, CapybaraScreenshotDiff::ORANGE_RGBA).first
         end
       end
 
@@ -80,7 +78,8 @@ module Capybara::Screenshot::Diff
           "(#{difference.inspect})",
           image_path.to_path,
           annotated_base_image_path.to_path,
-          annotated_image_path.to_path
+          annotated_image_path.to_path,
+          heatmap_diff_path.to_path
         ].join(NEW_LINE)
       end
 
@@ -88,7 +87,7 @@ module Capybara::Screenshot::Diff
 
       def save_heatmap_diff
         merged_image = driver.merge(new_image, base_image)
-        highlighted_mask = driver.highlight_mask(difference.meta[:diff_mask], merged_image, color: DIFF_COLOR)
+        highlighted_mask = driver.highlight_mask(difference.diff_mask, merged_image, color: CapybaraScreenshotDiff::RED_RGBA)
 
         save(highlighted_mask, heatmap_diff_path.to_path)
       end

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

@@ -21,37 +21,80 @@ module Capybara
           @snapshot = CapybaraScreenshotDiff::SnapManager.snapshot(screenshot_full_name, @screenshot_format)
         end
 
-        def build_screenshot_matches_job
-          # TODO: Move this into screenshot stage, in order to re-evaluate coordinates after page updates
-          return if BrowserHelpers.window_size_is_wrong?(Screenshot.window_size)
+        def build_screenshot_assertion(skip_stack_frames: 0)
+          check_window_size!
+          prepare_screenshot_options
+          check_base_screenshot
 
-          # TODO: Move this into screenshot stage, in order to re-evaluate coordinates after page updates
+          capture_options, comparison_options = extract_capture_and_comparison_options!(driver_options)
+
+          capture_screenshot(capture_options, comparison_options)
+
+          # Pre-computation: No need to compare without base screenshot
+          # NOTE: Consider to return PreValid Assertion Value Object with hard coded valid result
+          return unless need_to_compare?
+
+          create_screenshot_assertion(skip_stack_frames + 1, comparison_options)
+        end
+
+        private
+
+        def need_to_compare?
+          @snapshot.base_path.exist?
+        end
+
+        def check_window_size!
+          if BrowserHelpers.window_size_is_wrong?(Screenshot.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: #{Screenshot.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
+
+        def prepare_screenshot_options
           area_calculator = AreaCalculator.new(driver_options.delete(:crop), driver_options[:skip_area])
-          driver_options[:crop] = area_calculator.calculate_crop
 
-          # TODO: Move this into screenshot stage, in order to re-evaluate coordinates after page updates
-          # Allow nil or single or multiple areas
+          driver_options[:crop] = area_calculator.calculate_crop
           driver_options[:skip_area] = area_calculator.calculate_skip_area
           driver_options[:driver] = Drivers.for(driver_options[:driver])
+        end
 
+        def check_base_screenshot
           @snapshot.checkout_base_screenshot
 
-          # When fail_if_new is true no need to create screenshot if base screenshot is missing
-          return if Capybara::Screenshot::Diff.fail_if_new && !@snapshot.base_path.exist?
-
-          capture_options, comparison_options = extract_capture_and_comparison_options!(driver_options)
-
-          # Load new screenshot from Browser
-          take_comparison_screenshot(capture_options, comparison_options, @snapshot)
-
-          # Pre-computation: No need to compare without base screenshot
-          return unless @snapshot.base_path.exist?
+          if Capybara::Screenshot::Diff.fail_if_new && !@snapshot.base_path.exist?
+            raise CapybaraScreenshotDiff::ExpectationNotMet.new(<<~ERROR.chomp, caller)
+              No existing screenshot found for #{@snapshot.base_path}!
+              To record baselines: RECORD_SCREENSHOTS=1 bundle exec rake test
+              To allow new screenshots: Capybara::Screenshot::Diff.fail_if_new = false
+            ERROR
+          end
+        end
 
-          # Add comparison job in the queue
-          [screenshot_full_name, ImageCompare.new(@snapshot.path, @snapshot.base_path, comparison_options)]
+        def capture_screenshot(capture_options, comparison_options)
+          screenshoter = if capture_options[:stability_time_limit]
+            StableScreenshoter.new(capture_options, comparison_options)
+          else
+            Diff.screenshoter.new(capture_options, comparison_options)
+          end
+          screenshoter.take_comparison_screenshot(@snapshot)
         end
 
-        private
+        def create_screenshot_assertion(skip_stack_frames, comparison_options)
+          assertion = CapybaraScreenshotDiff::ScreenshotAssertion.new(screenshot_full_name)
+          assertion.caller = caller(skip_stack_frames + 1)
+          assertion.compare = ImageCompare.new(@snapshot.path, @snapshot.base_path, comparison_options)
+          assertion
+        end
 
         def extract_capture_and_comparison_options!(driver_options = {})
           [
@@ -68,22 +111,6 @@ module Capybara
             driver_options
           ]
         end
-
-        # Try to get screenshot from browser.
-        # On `stability_time_limit` it checks that page stop updating by comparison several screenshot attempts
-        # On reaching `wait` limit then it has been failed. On failing we annotate screenshot attempts to help to debug
-        def take_comparison_screenshot(capture_options, comparison_options, snapshot = nil)
-          screenshoter = build_screenshoter_for(capture_options, comparison_options)
-          screenshoter.take_comparison_screenshot(snapshot)
-        end
-
-        def build_screenshoter_for(capture_options, comparison_options = {})
-          if capture_options[:stability_time_limit]
-            StableScreenshoter.new(capture_options, comparison_options)
-          else
-            Diff.screenshoter.new(capture_options, comparison_options[:driver])
-          end
-        end
       end
     end
   end

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

@@ -8,9 +8,11 @@ module Capybara
     class Screenshoter
       attr_reader :capture_options, :driver
 
-      def initialize(capture_options, driver)
+      # @param capture_options [Hash] Options for capturing (window_size, wait, etc.)
+      # @param comparison_options [Hash] Options for image comparison (driver, tolerance, etc.)
+      def initialize(capture_options, comparison_options = {})
         @capture_options = capture_options
-        @driver = driver
+        @driver = Diff::Drivers.for(comparison_options)
       end
 
       def crop
@@ -30,7 +32,7 @@ module Capybara
       # On reaching `wait` limit then it has been failed. On failing we annotate screenshot attempts to help to debug
       def take_comparison_screenshot(snapshot)
         capture_screenshot_at(snapshot)
-        snapshot.cleanup_attempts
+        snapshot.cleanup_attempts!
       end
 
       PNG_EXTENSION = ".png"
@@ -70,9 +72,8 @@ module Capybara
 
         blurred_input = BrowserHelpers.blur_from_focused_element if Screenshot.blur_active_element
 
-        if Screenshot.hide_caret
-          BrowserHelpers.hide_caret
-        end
+        BrowserHelpers.hide_caret if Screenshot.hide_caret
+        BrowserHelpers.disable_animations if Screenshot.disable_animations
 
         blurred_input
       end
@@ -86,7 +87,7 @@ module Capybara
           break unless pending_image
 
           if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline_at
-            raise CapybaraScreenshotDiff::ExpectationNotMet, "Images have not been loaded after #{timeout}s: #{pending_image.inspect}"
+            raise CapybaraScreenshotDiff::ExpectationNotMet.new("Images have not been loaded after #{timeout}s: #{pending_image.inspect}", caller)
           end
 
           sleep 0.025
@@ -101,7 +102,7 @@ module Capybara
         # Load saved screenshot and pre-process it
         process_screenshot(tmpfile.path, screenshot_path)
       ensure
-        File.unlink(tmpfile) if tmpfile
+        tmpfile&.close!
       end
 
       def capture_screenshot_at(snapshot)

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"
+      VERSION = "1.12.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,5 @@ Before do
   Capybara::Screenshot::Diff.delayed = false
   Capybara::Screenshot::BrowserHelpers.resize_window_if_needed
 end
+
+AfterAll { CapybaraScreenshotDiff.finalize_reporters! }

data/lib/capybara_screenshot_diff/dsl.rb

@@ -1,18 +1,113 @@
 # 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 optionally 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 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
+
+    # Alias for backward compatibility with older test suites.
+    # @see #screenshot
+    alias_method :assert_matches_screenshot, :screenshot
+
+    # 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)
+      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 {#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

@@ -22,7 +22,7 @@ module CapybaraScreenshotDiff
       def 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
@@ -39,7 +39,7 @@ module CapybaraScreenshotDiff
         CapybaraScreenshotDiff.verify
       rescue CapybaraScreenshotDiff::ExpectationNotMet => e
         assertion = ::Minitest::Assertion.new(e)
-        assertion.set_backtrace []
+        assertion.set_backtrace(e.backtrace)
         failures << assertion
       ensure
         CapybaraScreenshotDiff.reset
@@ -47,3 +47,5 @@ module CapybaraScreenshotDiff
     end
   end
 end
+
+::Minitest.after_run { CapybaraScreenshotDiff.finalize_reporters! } if ::Minitest.respond_to?(:after_run)