capybara-screenshot-diff 1.12.0 → 1.14.0

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

@@ -4,8 +4,9 @@ require "pathname"
 require "fileutils"
 
 require "capybara/screenshot/diff/comparison"
+require "capybara/screenshot/diff/difference"
+require "capybara/screenshot/diff/drivers"
 require "capybara/screenshot/diff/image_preprocessor"
-require "capybara/screenshot/diff/difference_finder"
 require "capybara/screenshot/diff/reporters/default"
 
 module Capybara
@@ -36,6 +37,8 @@ module Capybara
       # - Only performing expensive operations when absolutely necessary
       # - Maintaining high accuracy for complex comparisons
       class ImageCompare
+        TOLERABLE_OPTIONS = [:tolerance, :color_distance_limit, :shift_distance_limit, :area_size_limit].freeze
+
         attr_reader :driver, :driver_options
         attr_reader :image_path, :base_image_path
         attr_reader :difference, :error_message
@@ -48,6 +51,7 @@ module Capybara
 
           @driver_options = options.freeze
           @driver = Drivers.for(@driver_options)
+          @without_tolerable_options = (driver_options.keys & TOLERABLE_OPTIONS).empty?
         end
 
         # Performs a quick comparison of two image files.
@@ -85,7 +89,7 @@ module Capybara
         #   - `false` if the images are considered identical
         #
         # @see #processed
-        # @see DifferenceFinder
+        # @see #analyze_difference
         def different?
           processed.difference.different?
         end
@@ -110,8 +114,8 @@ module Capybara
 
         private
 
-        def difference_finder
-          @difference_finder ||= DifferenceFinder.new(driver, driver_options)
+        def without_tolerable_options?
+          @without_tolerable_options
         end
 
         def load_images_and_build_comparison(base_path, new_path, options)
@@ -130,8 +134,41 @@ module Capybara
           # Create comparison with preprocessed images
           comparison = load_comparison(base_image_path, image_path, driver_options)
 
-          # Use difference finder to analyze the comparison
-          difference_finder.call(comparison, quick_mode: quick_mode)
+          analyze_difference(comparison, quick_mode: quick_mode)
+        end
+
+        # Analyzes the comparison and determines if images are different.
+        #
+        # @param comparison [Comparison] The comparison object containing images to analyze.
+        # @param quick_mode [Boolean] When true, performs minimal checks and returns early.
+        #   In quick mode, returns [is_equal, difference] where:
+        #   - is_equal is true if images are considered equal
+        #   - difference is a Difference object or nil
+        #   When false, returns a Difference object directly.
+        # @return [Array, Difference] Result format depends on quick_mode parameter.
+        def analyze_difference(comparison, quick_mode: true)
+          # Handle dimension differences
+          unless driver.same_dimension?(comparison)
+            result = Difference.build_null(comparison, comparison.base_image_path, comparison.new_image_path, {different_dimensions: true})
+            return quick_mode ? [false, result] : result
+          end
+
+          # Handle identical pixels
+          if driver.same_pixels?(comparison)
+            result = Difference.build_null(comparison, comparison.base_image_path, comparison.new_image_path)
+            return quick_mode ? [true, result] : result
+          end
+
+          # Handle early return for non-tolerable options
+          if quick_mode && without_tolerable_options?
+            return [false, nil]
+          end
+
+          # Process difference region
+          region = driver.find_difference_region(comparison)
+
+          # Only create a proper difference object if we've completed the comparison
+          quick_mode ? [!region.different?, region] : region
         end
 
         def difference=(new_difference)

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

@@ -1,18 +1,27 @@
 # frozen_string_literal: true
 
+require "capybara/screenshot/diff/annotation_service"
+
 module Capybara::Screenshot::Diff
   module Reporters
     class Default
-      attr_reader :annotated_image_path, :annotated_base_image_path, :heatmap_diff_path, :difference
+      attr_reader :difference
 
       def initialize(difference)
         @difference = difference
+        @annotation_service = AnnotationService.new(difference)
+      end
+
+      def annotated_image_path
+        annotation_service.annotated_image_path
+      end
 
-        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}")
+      def annotated_base_image_path
+        annotation_service.annotated_base_image_path
+      end
+
+      def heatmap_diff_path
+        annotation_service.heatmap_diff_path
       end
 
       def generate
@@ -31,44 +40,35 @@ module Capybara::Screenshot::Diff
       end
 
       def clean_tmp_files
-        annotated_base_image_path.unlink if annotated_base_image_path.exist?
-        annotated_image_path.unlink if annotated_image_path.exist?
-        heatmap_diff_path.unlink if heatmap_diff_path.exist?
-      end
-
-      def build_error_for_different_dimensions
-        change_msg = [comparison.base_image, comparison.new_image]
-          .map { |image| driver.dimension(image).join("x") }
-          .join(" => ")
-
-        "Dimensions have changed: #{change_msg}\n#{base_image_path.to_path}\n#{image_path.to_path}"
+        annotation_service.clean_tmp_files
       end
 
       def annotate_and_save_images
-        save_annotation_for(new_image, annotated_image_path)
-        save_annotation_for(base_image, annotated_base_image_path)
-        save_heatmap_diff if difference.diff_mask
+        annotation_service.annotate_and_save_images
       end
 
       def save_annotation_for(image, image_path)
-        image = annotate_difference(image, difference.region)
-        image = annotate_skip_areas(image, difference.comparison.skip_area) if difference.comparison.skip_area
-
-        save(image, image_path.to_path)
+        annotation_service.save_annotation_for(image, image_path)
       end
 
       def annotate_difference(image, region)
-        driver.draw_rectangles([image], region, CapybaraScreenshotDiff::RED_RGBA, offset: 1).first
+        annotation_service.annotate_difference(image, region)
       end
 
       def annotate_skip_areas(image, skip_areas)
-        skip_areas.reduce(image) do |memo, region|
-          driver.draw_rectangles([memo], region, CapybaraScreenshotDiff::ORANGE_RGBA).first
-        end
+        annotation_service.annotate_skip_areas(image, skip_areas)
       end
 
       def save(image, image_path)
-        driver.save_image_to(image, image_path.to_s)
+        annotation_service.save(image, image_path)
+      end
+
+      def build_error_for_different_dimensions
+        change_msg = [comparison.base_image, comparison.new_image]
+          .map { |image| driver.dimension(image).join("x") }
+          .join(" => ")
+
+        "Dimensions have changed: #{change_msg}\n#{base_image_path.to_path}\n#{image_path.to_path}"
       end
 
       NEW_LINE = "\n"
@@ -85,20 +85,7 @@ module Capybara::Screenshot::Diff
 
       private
 
-      def save_heatmap_diff
-        merged_image = driver.merge(new_image, base_image)
-        highlighted_mask = driver.highlight_mask(difference.diff_mask, merged_image, color: CapybaraScreenshotDiff::RED_RGBA)
-
-        save(highlighted_mask, heatmap_diff_path.to_path)
-      end
-
-      def base_image
-        difference.comparison.base_image
-      end
-
-      def new_image
-        difference.comparison.new_image
-      end
+      attr_reader :annotation_service
 
       def base_image_path
         comparison.base_image_path

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

@@ -32,11 +32,25 @@ module Capybara
 
           # 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?
+          unless need_to_compare?
+            CapybaraScreenshotDiff.record_new_screenshot(screenshot_full_name)
+            return
+          end
 
           create_screenshot_assertion(skip_stack_frames + 1, comparison_options)
         end
 
+        # Captures a screenshot without comparing it to a baseline.
+        def capture
+          check_window_size!
+          prepare_screenshot_options
+
+          capture_options, comparison_options = extract_capture_and_comparison_options!(driver_options)
+
+          @snapshot.manager.create_output_directory_for(@snapshot.path)
+          capture_screenshot(capture_options, comparison_options)
+        end
+
         private
 
         def need_to_compare?

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

@@ -14,7 +14,7 @@ module Capybara
         # `: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, nil] The options for comparing screenshots, defaults to `nil` which uses `Diff.default_options`.
+        # @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)

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

@@ -3,7 +3,7 @@
 module Capybara
   module Screenshot
     module Diff
-      VERSION = "1.12.0"
+      VERSION = "1.14.0"
     end
   end
 end

data/lib/capybara_screenshot_diff/cucumber.rb

@@ -9,4 +9,12 @@ Before do
   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! }

data/lib/capybara_screenshot_diff/dsl.rb

@@ -25,7 +25,7 @@ module CapybaraScreenshotDiff
       screenshot_namer.group = name
     end
 
-    # Takes a screenshot and optionally compares it against a baseline image.
+    # 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
@@ -53,7 +53,7 @@ module CapybaraScreenshotDiff
     # @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)
+    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
@@ -76,15 +76,36 @@ module CapybaraScreenshotDiff
       true
     end
 
-    # Alias for backward compatibility with older test suites.
-    # @see #screenshot
-    alias_method :assert_matches_screenshot, :screenshot
+    # 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)
-      screenshot(name, skip_stack_frames: skip_stack_frames + 1, **opts)
+      assert_matches_screenshot(name, skip_stack_frames: skip_stack_frames + 1, **opts)
     end
 
     private
@@ -96,7 +117,7 @@ module CapybaraScreenshotDiff
     #
     # @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.
+    #   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

data/lib/capybara_screenshot_diff/minitest.rb

@@ -19,7 +19,7 @@ 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 + 1, **opts)
@@ -27,8 +27,6 @@ module CapybaraScreenshotDiff
         raise ::Minitest::Assertion, e.message
       end
 
-      alias_method :assert_matches_screenshot, :screenshot
-
       def setup
         super
         ::Capybara::Screenshot::BrowserHelpers.resize_window_if_needed
@@ -37,6 +35,10 @@ module CapybaraScreenshotDiff
       def before_teardown
         super
         CapybaraScreenshotDiff.verify
+
+        if (msg = CapybaraScreenshotDiff.pending_screenshots_message)
+          skip(msg)
+        end
       rescue CapybaraScreenshotDiff::ExpectationNotMet => e
         assertion = ::Minitest::Assertion.new(e)
         assertion.set_backtrace(e.backtrace)

data/lib/capybara_screenshot_diff/rspec.rb

@@ -7,7 +7,7 @@ RSpec::Matchers.define :match_screenshot do |name, **options|
   description { "match screenshot '#{name}'" }
 
   match do |_page|
-    screenshot(name, **options)
+    assert_matches_screenshot(name, **options)
     true
   end
 
@@ -30,10 +30,15 @@ RSpec.configure do |config|
     end
   end
 
-  config.after do
+  config.after do |example|
     if self.class.include?(CapybaraScreenshotDiff::DSL)
       begin
         CapybaraScreenshotDiff.verify
+
+        # Never mask a real failure with a pending marker.
+        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

data/lib/capybara_screenshot_diff/screenshot_assertion.rb

@@ -65,10 +65,11 @@ module CapybaraScreenshotDiff
   end
 
   class AssertionRegistry
-    attr_reader :assertions, :screenshot_namer
+    attr_reader :assertions, :screenshot_namer, :new_screenshots
 
     def initialize
       @assertions = []
+      @new_screenshots = []
       @screenshot_namer = CapybaraScreenshotDiff::ScreenshotNamer.new
     end
 
@@ -84,6 +85,14 @@ module CapybaraScreenshotDiff
       !@assertions.empty?
     end
 
+    def record_new_screenshot(name)
+      @new_screenshots.push(name)
+    end
+
+    def new_screenshots_present?
+      !@new_screenshots.empty?
+    end
+
     def verify(screenshots = CapybaraScreenshotDiff.assertions)
       return unless ::Capybara::Screenshot.active? && ::Capybara::Screenshot::Diff.fail_on_difference
 
@@ -102,6 +111,7 @@ module CapybaraScreenshotDiff
 
     def reset
       @assertions.clear
+      @new_screenshots.clear
       @screenshot_namer = CapybaraScreenshotDiff::ScreenshotNamer.new
     end
   end
@@ -120,6 +130,9 @@ module CapybaraScreenshotDiff
     def_delegator :registry, :assertions
     def_delegator :registry, :assertions_present?
     def_delegator :registry, :failed_assertions
+    def_delegator :registry, :record_new_screenshot
+    def_delegator :registry, :new_screenshots
+    def_delegator :registry, :new_screenshots_present?
     def reset
       notify_reporters(registry.assertions)
       registry.reset
@@ -145,6 +158,17 @@ module CapybaraScreenshotDiff
     def_delegator :registry, :screenshot_namer
     def_delegator :registry, :verify
 
+    # Message to skip the test with when a new screenshot has no baseline yet
+    # and `pending_if_new` is enabled. Adapters call this after verifying
+    # screenshots, and skip the test with the returned message when present.
+    #
+    # @return [String, nil] the pending message, or nil when there is nothing to report
+    def pending_screenshots_message
+      return unless ::Capybara::Screenshot::Diff.pending_if_new && new_screenshots_present?
+
+      "No baseline for: #{new_screenshots.join(", ")}. Commit the captured screenshots to record them."
+    end
+
     private
 
     def notify_reporters(assertions)

data/lib/capybara_screenshot_diff.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# Lazy load: snap_diff.rb requires this file, so eagerly `require`-ing it
+# here would be circular. `autoload` defers the load until SnapDiff is
+# first referenced, by which point this file has already finished loading.
+autoload :SnapDiff, "snap_diff"
+
 require "capybara/dsl"
 require "capybara/screenshot/diff/version"
 require "capybara/screenshot/diff/utils"
@@ -65,6 +70,7 @@ module Capybara
       mattr_accessor(:delayed) { true }
       mattr_accessor :area_size_limit
       mattr_accessor(:fail_if_new) { !ENV["CI"].nil? && !ENV["CI"].empty? }
+      mattr_accessor(:pending_if_new) { false }
       mattr_accessor(:fail_on_difference) { true }
       mattr_accessor :color_distance_limit
       mattr_accessor(:enabled) { true }

data/lib/snap_diff.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "capybara_screenshot_diff"
+
+# Forward-looking namespace for the gem, per ADR-004.
+#
+# These are pure additive aliases onto the existing
+# +Capybara::Screenshot::Diff+ API — no behavior changes, no deprecation
+# warnings. See ADR-004 for the full migration plan.
+module SnapDiff
+  Comparison = Capybara::Screenshot::Diff::ImageCompare
+
+  def self.compare(...)
+    Capybara::Screenshot::Diff.compare(...)
+  end
+
+  def self.start(&block)
+    Capybara::Screenshot::Diff.configure(&block)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capybara-screenshot-diff
 version: !ruby/object:Gem::Version
-  version: 1.12.0
+  version: 1.14.0
 platform: ruby
 authors:
 - Uwe Kubosch
@@ -77,29 +77,33 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- CODE_OF_CONDUCT.md
 - LICENSE.txt
 - Rakefile
 - capybara-screenshot-diff.gemspec
 - docs/RELEASE_PREP.md
 - docs/UPGRADING.md
+- docs/architecture.md
 - docs/ci-integration.md
 - docs/configuration.md
 - docs/docker-testing.md
 - docs/drivers.md
 - docs/framework-setup.md
+- docs/images/snap_diff_annotated.png
 - docs/images/snap_diff_web_ui.png
+- docs/migration-guide.md
 - docs/organization.md
 - docs/reporters.md
 - docs/thread_safety.md
 - gems.rb
 - lib/capybara-screenshot-diff.rb
 - lib/capybara/screenshot/diff.rb
+- lib/capybara/screenshot/diff/annotation_service.rb
 - lib/capybara/screenshot/diff/area_calculator.rb
 - lib/capybara/screenshot/diff/browser_helpers.rb
 - lib/capybara/screenshot/diff/comparison.rb
 - lib/capybara/screenshot/diff/cucumber.rb
 - lib/capybara/screenshot/diff/difference.rb
-- lib/capybara/screenshot/diff/difference_finder.rb
 - lib/capybara/screenshot/diff/drivers.rb
 - lib/capybara/screenshot/diff/drivers/base_driver.rb
 - lib/capybara/screenshot/diff/drivers/chunky_png_driver.rb
@@ -130,6 +134,7 @@ files:
 - lib/capybara_screenshot_diff/snap.rb
 - lib/capybara_screenshot_diff/snap_manager.rb
 - lib/capybara_screenshot_diff/static.rb
+- lib/snap_diff.rb
 homepage: https://github.com/snap-diff/snap_diff-capybara
 licenses:
 - MIT
@@ -149,7 +154,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Track your GUI changes with diff assertions
 test_files: []

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

@@ -1,97 +0,0 @@
-# frozen_string_literal: true
-
-require "capybara/screenshot/diff/comparison"
-require "capybara/screenshot/diff/difference"
-
-module Capybara
-  module Screenshot
-    module Diff
-      # Analyzes image differences with configurable tolerance levels.
-      #
-      # This class implements the core comparison logic for detecting visual differences
-      # between images while accounting for various tolerances and optimizations.
-      #
-      # The comparison process follows these steps:
-      # 1. Dimension Check (Fastest)
-      #    - Compares image dimensions first for quick rejection
-      #    - Different dimensions always indicate a difference
-      #
-      # 2. Pixel Equality Check (Fast)
-      #    - Performs bitwise comparison if dimensions match
-      #    - Returns immediately if images are exactly identical
-      #
-      # 3. Tolerant Comparison (Slower)
-      #    - Only runs if quick checks don't determine equality
-      #    - Respects configured tolerances for color and shift differences
-      #    - Can ignore specific regions (skip_area)
-      #    - Considers anti-aliasing and sub-pixel rendering differences
-      #
-      # The class is designed to be stateless and thread-safe, with all configuration
-      # passed in through the constructor.
-      class DifferenceFinder
-        TOLERABLE_OPTIONS = [:tolerance, :color_distance_limit, :shift_distance_limit, :area_size_limit].freeze
-
-        attr_reader :driver, :options
-
-        # Creates a new DifferenceFinder instance.
-        #
-        # @param driver [Drivers::Base] The image processing driver to use.
-        #   Must implement the driver interface expected by DifferenceFinder.
-        # @param options [Hash] Configuration options for the comparison:
-        #   @option options [Numeric] :tolerance (0.001) Color tolerance threshold (0.0-1.0).
-        #   @option options [Numeric] :color_distance_limit Maximum allowed color distance.
-        #   @option options [Numeric] :shift_distance_limit Maximum allowed shift distance.
-        #   @option options [Numeric] :area_size_limit Maximum allowed difference area size.
-        #   @option options [Array<Array>] :skip_area Regions to exclude from comparison.
-        def initialize(driver, options)
-          @driver = driver
-          @options = options
-          @without_tolerable_options = (options.keys & TOLERABLE_OPTIONS).empty?
-        end
-
-        # Analyzes the comparison and determines if images are different.
-        #
-        # @param comparison [Comparison] The comparison object containing images to analyze.
-        # @param quick_mode [Boolean] When true, performs minimal checks and returns early.
-        #   In quick mode, returns [is_equal, difference] where:
-        #   - is_equal is true if images are considered equal
-        #   - difference is a Difference object or nil
-        #   When false, returns a Difference object directly.
-        # @return [Array, Difference] Result format depends on quick_mode parameter.
-        # @raise [ArgumentError] If the comparison object is invalid.
-        def call(comparison, quick_mode: true)
-          # Process the comparison and return result
-
-          # Handle dimension differences
-          unless driver.same_dimension?(comparison)
-            result = Difference.build_null(comparison, comparison.base_image_path, comparison.new_image_path, {different_dimensions: true})
-            return quick_mode ? [false, result] : result
-          end
-
-          # Handle identical pixels
-          if driver.same_pixels?(comparison)
-            result = Difference.build_null(comparison, comparison.base_image_path, comparison.new_image_path)
-            return quick_mode ? [true, result] : result
-          end
-
-          # Handle early return for non-tolerable options
-          if quick_mode && without_tolerable_options?
-            return [false, nil]
-          end
-
-          # Process difference region
-          region = driver.find_difference_region(comparison)
-
-          # Only create a proper difference object if we've completed the comparison
-          quick_mode ? [!region.different?, region] : region
-        end
-
-        private
-
-        def without_tolerable_options?
-          @without_tolerable_options
-        end
-      end
-    end
-  end
-end