capybara-screenshot-diff 1.13.0 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d2139e98f2c24b265a13882b8faf30282f5ef519dcbb77907f5d69d8f565606
-  data.tar.gz: 9302c796f95734c4ec4383f926c0aad03630caed8505f1d8fc815fe11bdb3c61
+  metadata.gz: dba172cde687794eeedbffe4c4112d58ed5c4e2fcac5cdaf93b84827396e832d
+  data.tar.gz: a6b45b9bfc4ff349b506c7045f54392101c1bbfecda7b51475758fd2ee1536c0
 SHA512:
-  metadata.gz: b072316d36fe69af44d3f318ba2d24968e9e0b377f85842c9a21d29aeb4ae7375a6b5b02c4842c9f3d9eb3115ed4fbcc33edff6c3b74b8ce788069d2301da95a
-  data.tar.gz: 30389f03f593e74c888a2d9de77717f1c839ad8ce41539ef0e6633b5dcff609ed546d7ed5279b3ab7ac9c86c53ed6608872e5b28a70663c7c2aef7c0974fcdf5
+  metadata.gz: afc332553b0bdafe8a47d82376b83b866bcd25144132f6e6ba481e41b03fd113ea74cf25f1decfcff8397664b1d4e2469abbfd21bebfde2a2c42f332ca0220dc
+  data.tar.gz: 1bd843fa71d17a0eac95bf1674a8d76352a8fe8c93c581840f9a50f63106edd40c5964b25ac36add805c6baf4129138e01aca5f73df30b34646fb1c2814adacd

data/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v1.14.0] - 2026-08-22
+
+### Added
+- **`SnapDiff` namespace aliases** — `SnapDiff::Comparison`, `SnapDiff.compare`, and `SnapDiff.start` provide a forward-looking entry point onto the existing `Capybara::Screenshot::Diff` API, no behavior changes ([#166](https://github.com/snap-diff/snap_diff-capybara/issues/166))
+
+### Fixed
+- **Standalone require path** — `require "capybara_screenshot_diff"` (or `require "snap_diff"`) followed by `Diff.compare` no longer raises `NameError` for the missing drivers require ([#194](https://github.com/snap-diff/snap_diff-capybara/pull/194))
+
+### Internal
+- Merged `DifferenceFinder` into `ImageCompare` (ADR-004 step) ([#192](https://github.com/snap-diff/snap_diff-capybara/pull/192))
+- Extracted `AnnotationService` from `Reporters::Default`; full public surface preserved via delegation ([#193](https://github.com/snap-diff/snap_diff-capybara/pull/193))
+- Consolidated `pending_if_new` teardown logic into one shared helper across Minitest/RSpec/Cucumber adapters ([#197](https://github.com/snap-diff/snap_diff-capybara/pull/197))
+- Test-suite driver-coverage banner and CI guard against silently missing drivers ([#198](https://github.com/snap-diff/snap_diff-capybara/pull/198))
+
+---
+
 ## [v1.13.0] - 2026-08-22
 
 ### Added

data/docs/RELEASE_PREP.md

@@ -1,24 +1,23 @@
-# Release Preparation — v1.13.0
+# Release Preparation — v1.14.0
 
 ## Summary
 
-Issue #191 API decoupling: `assert_matches_screenshot` becomes the primary
-assertion method, plus a capture-only API and opt-in pending-instead-of-pass
-for missing baselines.
+SnapDiff namespace aliases (ADR-004 PR 9), standalone-require fix, and three
+internal consolidation refactors (ADR-004 PR 2/PR 7, teardown logic).
 
 ## Release Checklist
 
 ### Pre-Release
 
-- [x] Update version to `1.13.0`
-- [x] Run tests: `bundle exec rake test:unit` (235 runs, 0 failures)
+- [x] Update version to `1.14.0`
+- [x] Run tests: `bundle exec rake test:unit` (green)
 - [x] Update CHANGELOG.md
 
 ### Release (One Click)
 
 1. Push to GitHub
 2. Go to [Actions → Release](https://github.com/snap-diff/snap_diff-capybara/actions/workflows/release.yml)
-3. Click **Run workflow**, enter `1.13.0`
+3. Click **Run workflow**, enter `1.14.0`
 4. Workflow will: test → tag → publish to RubyGems → create GitHub Release
 
 ### Post-Release
@@ -28,15 +27,18 @@ for missing baselines.
 
 ## What Changed
 
-### New Features
-- `capture_screenshot` DSL method — capture without comparing or asserting
-- `compare:` option on `screenshot` — `compare: false` captures only
-- `Capybara::Screenshot::Diff.pending_if_new` — mark tests skipped in teardown
-  when a screenshot has no committed baseline (Minitest, RSpec, and Cucumber)
+### Added
+- `SnapDiff` namespace aliases — `SnapDiff::Comparison`, `SnapDiff.compare`,
+  `SnapDiff.start` (additive; deprecations deferred to v2.0)
 
-### Behavior Changes
-- `assert_matches_screenshot` is now the primary assertion method; `screenshot`
-  remains as a convenience wrapper and is safe to override in user test classes —
-  the gem no longer calls it internally ([#191](https://github.com/snap-diff/snap_diff-capybara/issues/191))
+### Fixed
+- Standalone `require "capybara_screenshot_diff"` + `Diff.compare` no longer
+  raises `NameError` (missing drivers require)
+
+### Internal
+- `DifferenceFinder` merged into `ImageCompare`; `AnnotationService` extracted
+  from `Reporters::Default` (public surface preserved); `pending_if_new`
+  teardown consolidated across the three framework adapters; driver-coverage
+  banner + CI guard in the test suite
 
 See [CHANGELOG.md](../CHANGELOG.md) for full details.

data/docs/UPGRADING.md

@@ -1,6 +1,91 @@
-# Upgrading to v1.12.0
+# Upgrading
 
-## Overview
+## Upgrading to v1.13.0
+
+### Overview
+
+Version 1.13.0 is a **minor release** clarifying API terminology and adding new capture methods. No breaking changes — your existing code continues to work.
+
+**Estimated upgrade time:** 0 minutes (no action required for most users)
+
+---
+
+### Quick Upgrade Path (Most Users)
+
+```ruby
+# In your Gemfile
+gem 'capybara-screenshot-diff', '~> 1.13.0'
+```
+
+```bash
+bundle update capybara-screenshot-diff
+bundle exec rake test
+```
+
+**That's it!** Existing `screenshot` calls work unchanged. New methods available if needed.
+
+---
+
+### What Changed
+
+#### API Clarification: Primary Method is `assert_matches_screenshot`
+
+**v1.12.0 and earlier:** `screenshot` was the primary method  
+**v1.13.0+:** `assert_matches_screenshot` is the primary method
+
+**Action required:** None. `screenshot` continues to work as-is.
+
+The method names now better reflect their behavior:
+- `assert_matches_screenshot(name)` — takes screenshot and asserts it matches baseline
+- `screenshot(name, compare: true)` — convenience wrapper (same behavior as above when `compare: true`)
+- `capture_screenshot(name)` — new: captures without asserting
+
+```ruby
+# All three work and are safe to use:
+assert_matches_screenshot "homepage"                # Primary: explicit intent
+screenshot "homepage"                               # Shorthand (familiar)
+screenshot "homepage", compare: false               # Capture only
+capture_screenshot "homepage"                       # Also capture only
+```
+
+**Safe to override:** You can safely define your own `screenshot` method in your test base class — the gem's implementation won't interfere.
+
+---
+
+### New: `capture_screenshot` Method
+
+Capture without comparing to baseline:
+
+```ruby
+capture_screenshot "dynamic_page"  # No assertion
+```
+
+Equivalent to: `screenshot "dynamic_page", compare: false`
+
+---
+
+### New: `Diff.pending_if_new` Helper
+
+Mark baseline-less tests pending instead of failing during initial CI runs:
+
+```ruby
+# In test_helper.rb — before running tests
+Capybara::Screenshot::Diff.pending_if_new = true
+```
+
+**CI requirement:** When using `pending_if_new`, ensure CI is configured with `fail_if_new: false` (see [Configuration Reference](configuration.md#quick-setup)):
+
+```ruby
+Capybara::Screenshot::Diff.configure do |screenshot, diff|
+  diff.fail_if_new = false  # Allow baselines to be added
+end
+```
+
+---
+
+## Upgrading to v1.12.0
+
+### Overview
 
 Version 1.12.0 is a **minor release** with new features, performance improvements, and default behavior changes. This guide will help you upgrade smoothly.
 

data/docs/architecture.md

@@ -100,7 +100,7 @@ The comparison engine uses a **layered optimization strategy** to balance speed
 - `quick_equal?` is designed for fast rejection — it early-returns as soon as a difference is found
 - `different?` triggers the full comparison if not already processed
 - `processed` guarantees the comparison is complete and returns the result with all metadata
-- The `DifferenceFinder` handles the actual pixel analysis, delegating to the driver
+- `ImageCompare#analyze_difference` handles the actual pixel analysis, delegating to the driver
 
 ### 5. Drivers (`lib/capybara/screenshot/diff/drivers/`)
 
@@ -257,7 +257,6 @@ lib/
     image_compare.rb                           # Layered comparison engine
     comparison.rb                              # Comparison value object
     difference.rb                              # Difference result value object
-    difference_finder.rb                       # Core diff analysis logic
     image_preprocessor.rb                      # Pre-processing (skip areas, median filter)
     area_calculator.rb                         # Crop/skip area coordinate resolution
     region.rb                                  # Bounding box region value object

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Capybara::Screenshot::Diff
+  # Draws diff/skip-area rectangles and the heatmap overlay for a Difference,
+  # and saves the resulting images to their `.diff.*` / `.heatmap.diff.*` paths.
+  #
+  # Extracted from Reporters::Default (ADR-004 PR 7) so the reporter only
+  # builds error messages; this class owns all image annotation work.
+  class AnnotationService
+    attr_reader :annotated_image_path, :annotated_base_image_path, :heatmap_diff_path
+
+    def initialize(difference)
+      @difference = difference
+
+      comparison = difference.comparison
+      ext = comparison.new_image_path.extname.delete_prefix(".")
+      screenshot_format = 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}")
+    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 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
+    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)
+    end
+
+    def annotate_difference(image, region)
+      driver.draw_rectangles([image], region, CapybaraScreenshotDiff::RED_RGBA, offset: 1).first
+    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
+    end
+
+    def save(image, image_path)
+      driver.save_image_to(image, image_path.to_s)
+    end
+
+    private
+
+    attr_reader :difference
+
+    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
+
+    def driver
+      @_driver ||= difference.comparison.driver
+    end
+  end
+end

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/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.13.0"
+      VERSION = "1.14.0"
     end
   end
 end

data/lib/capybara_screenshot_diff/cucumber.rb

@@ -10,9 +10,8 @@ Before do
 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.")
+  if !scenario.failed? && (msg = CapybaraScreenshotDiff.pending_screenshots_message)
+    skip_this_scenario(msg)
   end
 ensure
   CapybaraScreenshotDiff.reset

data/lib/capybara_screenshot_diff/minitest.rb

@@ -36,9 +36,8 @@ module CapybaraScreenshotDiff
         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."
+        if (msg = CapybaraScreenshotDiff.pending_screenshots_message)
+          skip(msg)
         end
       rescue CapybaraScreenshotDiff::ExpectationNotMet => e
         assertion = ::Minitest::Assertion.new(e)

data/lib/capybara_screenshot_diff/rspec.rb

@@ -36,9 +36,8 @@ RSpec.configure do |config|
         CapybaraScreenshotDiff.verify
 
         # Never mask a real failure with a pending marker.
-        if example.exception.nil? && 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."
+        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) }

data/lib/capybara_screenshot_diff/screenshot_assertion.rb

@@ -158,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"

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.13.0
+  version: 1.14.0
 platform: ruby
 authors:
 - Uwe Kubosch
@@ -98,12 +98,12 @@ files:
 - 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
@@ -134,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

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