capybara-screenshot-diff 1.14.0 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dba172cde687794eeedbffe4c4112d58ed5c4e2fcac5cdaf93b84827396e832d
-  data.tar.gz: a6b45b9bfc4ff349b506c7045f54392101c1bbfecda7b51475758fd2ee1536c0
+  metadata.gz: e22999718673e3e7cec926c524deedb3e3d0ead26e7c8350b777f5a453f02ad6
+  data.tar.gz: 1c10e980fb7787a493c763ddc3ee8f1a7ada5180af7277e389b24761a359f68d
 SHA512:
-  metadata.gz: afc332553b0bdafe8a47d82376b83b866bcd25144132f6e6ba481e41b03fd113ea74cf25f1decfcff8397664b1d4e2469abbfd21bebfde2a2c42f332ca0220dc
-  data.tar.gz: 1bd843fa71d17a0eac95bf1674a8d76352a8fe8c93c581840f9a50f63106edd40c5964b25ac36add805c6baf4129138e01aca5f73df30b34646fb1c2814adacd
+  metadata.gz: 6a3328839042af4d915150aba0c135d52f99074b9c31a69bdf9f6ff7e2b5a4c2c352b94f767ed9ec24f517c232257d1111bce1db3f019a668b8b4ba5314b09b1
+  data.tar.gz: 30c9cabdbabf2823c7fe77b4b825f7d59d0e3a8b49d373544eabb3ad171bee58d9ca8e57c6555b93254e7f04d0aa04075dd84839f4623151ae818efdd020845d

data/CHANGELOG.md

@@ -5,6 +5,21 @@ 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

data/docs/RELEASE_PREP.md

@@ -1,23 +1,23 @@
-# Release Preparation — v1.14.0
+# Release Preparation — v1.15.0
 
 ## Summary
 
-SnapDiff namespace aliases (ADR-004 PR 9), standalone-require fix, and three
-internal consolidation refactors (ADR-004 PR 2/PR 7, teardown logic).
+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.14.0`
-- [x] Run tests: `bundle exec rake test:unit` (green)
+- [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.14.0`
+3. Click **Run workflow**, enter `1.15.0`
 4. Workflow will: test → tag → publish to RubyGems → create GitHub Release
 
 ### Post-Release
@@ -28,17 +28,17 @@ internal consolidation refactors (ADR-004 PR 2/PR 7, teardown logic).
 ## What Changed
 
 ### Added
-- `SnapDiff` namespace aliases — `SnapDiff::Comparison`, `SnapDiff.compare`,
-  `SnapDiff.start` (additive; deprecations deferred to v2.0)
+- `SnapDiff::Config` — flat, additive consolidation of all 27 settings
+  (`SnapDiff.config` / `SnapDiff.configure`); old accessors stay canonical
 
 ### Fixed
-- Standalone `require "capybara_screenshot_diff"` + `Diff.compare` no longer
-  raises `NameError` (missing drivers require)
+- `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
-- `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
+- 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/architecture.md

@@ -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,7 +254,6 @@ 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
     image_preprocessor.rb                      # Pre-processing (skip areas, median filter)
     area_calculator.rb                         # Crop/skip area coordinate resolution

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

@@ -3,7 +3,6 @@
 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"
@@ -14,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:

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

@@ -3,7 +3,7 @@
 module Capybara
   module Screenshot
     module Diff
-      VERSION = "1.14.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/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,9 +36,10 @@ module CapybaraScreenshotDiff
         super
         CapybaraScreenshotDiff.verify
 
-        if (msg = CapybaraScreenshotDiff.pending_screenshots_message)
-          skip(msg)
-        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)
@@ -46,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,12 +30,27 @@ 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.
+        # 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

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "capybara_screenshot_diff"
+require "snap_diff/config"
 
 # Forward-looking namespace for the gem, per ADR-004.
 #
@@ -14,7 +15,35 @@ module SnapDiff
     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.14.0
+  version: 1.15.0
 platform: ruby
 authors:
 - Uwe Kubosch
@@ -101,7 +101,6 @@ files:
 - 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/drivers.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
@@ -135,6 +133,7 @@ files:
 - 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/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