capybara-screenshot-diff 1.13.0 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d2139e98f2c24b265a13882b8faf30282f5ef519dcbb77907f5d69d8f565606
-  data.tar.gz: 9302c796f95734c4ec4383f926c0aad03630caed8505f1d8fc815fe11bdb3c61
+  metadata.gz: e22999718673e3e7cec926c524deedb3e3d0ead26e7c8350b777f5a453f02ad6
+  data.tar.gz: 1c10e980fb7787a493c763ddc3ee8f1a7ada5180af7277e389b24761a359f68d
 SHA512:
-  metadata.gz: b072316d36fe69af44d3f318ba2d24968e9e0b377f85842c9a21d29aeb4ae7375a6b5b02c4842c9f3d9eb3115ed4fbcc33edff6c3b74b8ce788069d2301da95a
-  data.tar.gz: 30389f03f593e74c888a2d9de77717f1c839ad8ce41539ef0e6633b5dcff609ed546d7ed5279b3ab7ac9c86c53ed6608872e5b28a70663c7c2aef7c0974fcdf5
+  metadata.gz: 6a3328839042af4d915150aba0c135d52f99074b9c31a69bdf9f6ff7e2b5a4c2c352b94f767ed9ec24f517c232257d1111bce1db3f019a668b8b4ba5314b09b1
+  data.tar.gz: 30c9cabdbabf2823c7fe77b4b825f7d59d0e3a8b49d373544eabb3ad171bee58d9ca8e57c6555b93254e7f04d0aa04075dd84839f4623151ae818efdd020845d

data/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.15.0] - 2026-08-22
+
+### Added
+- **`SnapDiff::Config`** — one flat object consolidating all 27 settings behind `SnapDiff.config` / `SnapDiff.configure { |config| ... }`; purely additive, the existing accessors stay canonical and both views share one source of truth ([#200](https://github.com/snap-diff/snap_diff-capybara/pull/200))
+
+### Fixed
+- **`pending_if_new` no longer masks real failures** — a raising Minitest `teardown` or a raising RSpec `after` hook registered before the gem could previously be reported as a skipped/pending test with exit 0; the pending marker now defers until the framework's teardown chain has run and yields to any failure. Known residual: an RSpec `config.append_after` registered after this gem still runs later than the gem's hook — require the gem last if you use appended after-hooks ([#203](https://github.com/snap-diff/snap_diff-capybara/pull/203))
+- **`BacktraceFilter` path-boundary matching** — a custom `lib_directory` of `/app/lib` no longer also filters locations under `/app/library` ([#202](https://github.com/snap-diff/snap_diff-capybara/pull/202))
+
+### Internal
+- Failure-masking guard tests for the `pending_if_new` teardown paths via subprocess RSpec runs ([#199](https://github.com/snap-diff/snap_diff-capybara/pull/199))
+- Hygiene pass — skip-area/VCS-baseline and `BacktraceFilter` guard tests, entry-point forwarder dedupe, `Comparison` and `BacktraceFilter` merged into their sole consumers (−2 files, constant paths preserved) ([#201](https://github.com/snap-diff/snap_diff-capybara/pull/201))
+
+---
+
+## [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.15.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.
+Additive `SnapDiff::Config`, two failure-masking fixes in the `pending_if_new`
+teardown paths, a `BacktraceFilter` boundary fix, and an internal hygiene pass.
 
 ## 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.15.0`
+- [x] Run tests: `bundle exec rake test:unit` (267 runs, 0 failures)
 - [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.15.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::Config` — flat, additive consolidation of all 27 settings
+  (`SnapDiff.config` / `SnapDiff.configure`); old accessors stay canonical
 
-### 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
+- `pending_if_new` no longer converts real teardown/after-hook failures into
+  pending tests (Minitest defers to `after_teardown`; RSpec uses `append_after`;
+  known residual for consumer `append_after` hooks documented)
+- `BacktraceFilter` custom `lib_directory` matches on a path boundary
+
+### Internal
+- Guard tests for failure masking and skip-area/VCS-baseline regressions;
+  two files merged into sole consumers (constant paths preserved)
 
 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/`)
 
@@ -239,7 +239,6 @@ lib/
     screenshot_assertion.rb                    # Assertion + registry objects
     attempts_reporter.rb                       # Debug reporting for unstable captures
     error_with_filtered_backtrace.rb           # Error with filtered stack
-    backtrace_filter.rb                        # Library/gem frame filtering
     reporters/
       html.rb                                  # Interactive HTML report reporter
       templates/report.html.erb                # HTML report template
@@ -255,9 +254,7 @@ lib/
     stable_screenshoter.rb                     # Stability detection wrapper
     screenshot_matcher.rb                      # Orchestrator for capture + compare
     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

@@ -3,9 +3,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
@@ -13,6 +13,13 @@ module Capybara
     module Diff
       LOADED_DRIVERS = {}
 
+      # Holds the two images (and their paths/options/driver) being compared.
+      class Comparison < Struct.new(:new_image, :base_image, :options, :driver, :new_image_path, :base_image_path)
+        def skip_area
+          options[:skip_area]
+        end
+      end
+
       # Handles comparison of two images with a focus on performance and accuracy.
       #
       # This class implements a multi-layered optimization strategy for image comparison:
@@ -36,6 +43,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 +57,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 +95,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 +120,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 +140,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.15.0"
     end
   end
 end

data/lib/capybara/screenshot/diff.rb

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
 
-require "capybara_screenshot_diff/minitest"
+require "capybara-screenshot-diff"

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/error_with_filtered_backtrace.rb

@@ -1,8 +1,25 @@
 # frozen_string_literal: true
 
-require "capybara_screenshot_diff/backtrace_filter"
-
 module CapybaraScreenshotDiff
+  class BacktraceFilter
+    LIB_DIRECTORY = File.expand_path(File.join(File.dirname(__FILE__), "..")) + File::SEPARATOR
+
+    def initialize(lib_directory = LIB_DIRECTORY)
+      # Trailing separator keeps the prefix match on a directory boundary,
+      # so "/app/lib" does not also reject "/app/library".
+      @lib_directory = lib_directory.end_with?(File::SEPARATOR) ? lib_directory : lib_directory + File::SEPARATOR
+    end
+
+    # Filters out any backtrace lines originating from the library directory or from gems such as ActiveSupport, Minitest, and Railties
+    # @param backtrace [Array<String>]
+    # @return [Array<String>]
+    def filtered(backtrace)
+      backtrace
+        .reject { |location| File.expand_path(location).start_with?(@lib_directory) }
+        .reject { |l| l =~ /gems\/(activesupport|minitest|railties)/ }
+    end
+  end
+
   # @private
   class ErrorWithFilteredBacktrace < StandardError
     # @private

data/lib/capybara_screenshot_diff/minitest.rb

@@ -36,10 +36,10 @@ 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."
-        end
+        # Computed here (before teardown/reset), but the actual `skip` is
+        # deferred to `after_teardown` so a real error raised by the user's
+        # `teardown` isn't masked by a pending skip recorded before it ran.
+        @capybara_screenshot_diff_pending_message = CapybaraScreenshotDiff.pending_screenshots_message
       rescue CapybaraScreenshotDiff::ExpectationNotMet => e
         assertion = ::Minitest::Assertion.new(e)
         assertion.set_backtrace(e.backtrace)
@@ -47,6 +47,16 @@ module CapybaraScreenshotDiff
       ensure
         CapybaraScreenshotDiff.reset
       end
+
+      def after_teardown
+        super
+
+        # Never mask a real failure (from `verify` above or from the user's
+        # own `teardown`) with a pending marker.
+        if failures.empty? && (msg = @capybara_screenshot_diff_pending_message)
+          skip(msg)
+        end
+      end
     end
   end
 end

data/lib/capybara_screenshot_diff/rspec.rb

@@ -30,15 +30,29 @@ RSpec.configure do |config|
     end
   end
 
-  config.after do |example|
+  # `append_after` (as opposed to the default `after`, which prepends) adds
+  # this hook to the *end* of the after-hook chain regardless of when it's
+  # registered relative to the user's own `after`/`config.after` hooks. RSpec
+  # runs `after(:each)` hooks in reverse registration order, so a plain
+  # `config.after` here would run BEFORE a user hook registered earlier in
+  # their own spec_helper (before this file was required) -- and if that
+  # later-running user hook raises, its exception gets folded into
+  # `pending_exception` instead of `example.exception`, silently masking the
+  # failure behind our pending skip. `append_after` runs after the full user
+  # after-chain no matter the registration order, closing that gap.
+  config.append_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? && 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."
+        # Never mask a real failure with a pending marker. Kept as
+        # defense-in-depth: `append_after` observes failures from plain
+        # `after`/`prepend_after` user hooks, but appended hooks run FIFO,
+        # so a user `append_after` registered after this gem still runs
+        # later than us — RSpec has no "run absolutely last" construct.
+        # Mitigation for such consumers: require this gem last.
+        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/config.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# The MAPPING below references the legacy modules, so they must be loaded first.
+require "capybara_screenshot_diff"
+
+module SnapDiff
+  # Flat, additive consolidation of every existing
+  # +Capybara::Screenshot+ / +Capybara::Screenshot::Diff+ +mattr_accessor+
+  # setting behind one object: <tt>SnapDiff.config.<em>attr</em></tt>.
+  #
+  # Storage ownership: the OLD mattr_accessors remain the single source of
+  # truth. Config holds no state of its own -- every reader/writer defined
+  # from {MAPPING} simply forwards to the existing accessor. This is
+  # deliberate, not just simplest: several of those accessors carry default
+  # logic with observable timing (+fail_if_new+ derives its default from
+  # +ENV["CI"]+, +root+ falls back to +Rails.root+) that Rails' +mattr_accessor+
+  # evaluates once, at class-body-eval time, when +capybara_screenshot_diff.rb+
+  # first loads. Re-implementing that logic here -- even faithfully -- would
+  # mean evaluating it again, at a different moment (Config#new time), which
+  # is exactly the kind of "when defaults are evaluated" divergence the v2
+  # consolidation must not introduce. Delegating sidesteps the question
+  # entirely: Config never evaluates a default, it only ever forwards to
+  # whichever accessor already owns one. Bidirectional consistency (a write
+  # through either the old accessor or Config is visible through the other)
+  # falls out for free, because both paths read and write the exact same
+  # class-variable-backed storage.
+  class Config
+    # config attr name => [owning module, mattr_accessor name].
+    #
+    # The two names differ only for +screenshot_enabled+:
+    # +Capybara::Screenshot.enabled+ and +Capybara::Screenshot::Diff.enabled+
+    # are independent settings (see +Capybara::Screenshot.active?+, which
+    # reads both) that happen to share a bare name in their own modules. A
+    # flat Config can't expose two attributes both called +enabled+, so the
+    # Screenshot-side one is renamed here; Diff's keeps the bare +enabled+
+    # name since it's the one most existing configuration touches directly.
+    MAPPING = {
+      # Capybara::Screenshot
+      add_driver_path: [Capybara::Screenshot, :add_driver_path],
+      add_os_path: [Capybara::Screenshot, :add_os_path],
+      blur_active_element: [Capybara::Screenshot, :blur_active_element],
+      screenshot_enabled: [Capybara::Screenshot, :enabled],
+      hide_caret: [Capybara::Screenshot, :hide_caret],
+      disable_animations: [Capybara::Screenshot, :disable_animations],
+      root: [Capybara::Screenshot, :root],
+      stability_time_limit: [Capybara::Screenshot, :stability_time_limit],
+      window_size: [Capybara::Screenshot, :window_size],
+      save_path: [Capybara::Screenshot, :save_path],
+      use_lfs: [Capybara::Screenshot, :use_lfs],
+      screenshot_format: [Capybara::Screenshot, :screenshot_format],
+      capybara_screenshot_options: [Capybara::Screenshot, :capybara_screenshot_options],
+      # Capybara::Screenshot::Diff
+      delayed: [Capybara::Screenshot::Diff, :delayed],
+      area_size_limit: [Capybara::Screenshot::Diff, :area_size_limit],
+      fail_if_new: [Capybara::Screenshot::Diff, :fail_if_new],
+      pending_if_new: [Capybara::Screenshot::Diff, :pending_if_new],
+      fail_on_difference: [Capybara::Screenshot::Diff, :fail_on_difference],
+      color_distance_limit: [Capybara::Screenshot::Diff, :color_distance_limit],
+      enabled: [Capybara::Screenshot::Diff, :enabled],
+      shift_distance_limit: [Capybara::Screenshot::Diff, :shift_distance_limit],
+      skip_area: [Capybara::Screenshot::Diff, :skip_area],
+      driver: [Capybara::Screenshot::Diff, :driver],
+      tolerance: [Capybara::Screenshot::Diff, :tolerance],
+      perceptual_threshold: [Capybara::Screenshot::Diff, :perceptual_threshold],
+      screenshoter: [Capybara::Screenshot::Diff, :screenshoter],
+      manager: [Capybara::Screenshot::Diff, :manager]
+    }.freeze
+
+    MAPPING.each do |name, (mod, mattr)|
+      define_method(name) { mod.public_send(mattr) }
+      define_method(:"#{name}=") { |value| mod.public_send(:"#{mattr}=", value) }
+    end
+  end
+end

data/lib/snap_diff.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "capybara_screenshot_diff"
+require "snap_diff/config"
+
+# 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
+
+  # v1-style configuration: yields the two existing mattr_accessor holders
+  # (+Capybara::Screenshot+, +Capybara::Screenshot::Diff+) exactly as
+  # +Capybara::Screenshot::Diff.configure+ always has. Kept byte-for-byte
+  # identical to +Diff.configure+ for existing callers migrating namespaces
+  # without changing call shape.
+  #
+  #   SnapDiff.start do |screenshot, diff|
+  #     screenshot.window_size = [1280, 1024]
+  #     diff.tolerance = 0.0005
+  #   end
+  def self.start(&block)
+    Capybara::Screenshot::Diff.configure(&block)
+  end
+
+  # Forward-looking configuration: yields the single consolidated
+  # {SnapDiff::Config} object instead of the two old holders. Same
+  # underlying storage as +start+ / the old mattr_accessors -- this is a
+  # different *shape* of the same settings, not a second source of truth.
+  #
+  #   SnapDiff.configure do |config|
+  #     config.window_size = [1280, 1024]
+  #     config.tolerance = 0.0005
+  #   end
+  def self.configure
+    yield config
+  end
+
+  # The single consolidated settings object. See {SnapDiff::Config}.
+  def self.config
+    @config ||= Config.new
+  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.15.0
 platform: ruby
 authors:
 - Uwe Kubosch
@@ -98,12 +98,11 @@ 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
@@ -121,7 +120,6 @@ files:
 - lib/capybara/screenshot/diff/version.rb
 - lib/capybara_screenshot_diff.rb
 - lib/capybara_screenshot_diff/attempts_reporter.rb
-- lib/capybara_screenshot_diff/backtrace_filter.rb
 - lib/capybara_screenshot_diff/cucumber.rb
 - lib/capybara_screenshot_diff/dsl.rb
 - lib/capybara_screenshot_diff/error_with_filtered_backtrace.rb
@@ -134,6 +132,8 @@ files:
 - lib/capybara_screenshot_diff/snap.rb
 - lib/capybara_screenshot_diff/snap_manager.rb
 - lib/capybara_screenshot_diff/static.rb
+- lib/snap_diff.rb
+- lib/snap_diff/config.rb
 homepage: https://github.com/snap-diff/snap_diff-capybara
 licenses:
 - MIT

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

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-module Capybara::Screenshot::Diff
-  class Comparison < Struct.new(:new_image, :base_image, :options, :driver, :new_image_path, :base_image_path)
-    def skip_area
-      options[:skip_area]
-    end
-  end
-end

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

data/lib/capybara_screenshot_diff/backtrace_filter.rb

@@ -1,20 +0,0 @@
-# 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