snap_diff-capybara 2.0.0.beta2 → 2.0.0.beta4

data/lib/snap_diff/deprecation.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+# SnapDiff.silence_deprecations? -- the one switch that silences BOTH halves
+# of the story -- lives in snap_diff/removal.rb, not here: the other half
+# (the driver features 2.1 removes) is announced from core files that outlive
+# this one, and they cannot depend on a file the same deletion removes.
+require "snap_diff/removal"
+
 module SnapDiff
   # @api private
   #
@@ -25,26 +31,98 @@ module SnapDiff
     # caller who has customized +Warning+ behavior.
     MUTEX = Mutex.new
     @seen = {}
+    @notified = false
+    @notice_suppressed = false
+    @canonical_entry = false
+
+    # The ONE line a v1 user gets, whichever door they came through. Most of
+    # the v1 surface cannot warn per use -- the config accessors are plain
+    # delegators and the eager aliases never reach const_missing -- so
+    # without this a 2.x app is completely silent right up to the bare
+    # NameError it gets on 2.1. Deliberately generic and once per process:
+    # an actionable signal, not per-call stderr noise.
+    MIGRATION_NOTICE =
+      "[snap_diff deprecation] This process uses the v1 `Capybara::Screenshot*` / " \
+      "`CapybaraScreenshotDiff*` API. It still works in 2.0 and is REMOVED in 2.1 -- " \
+      "see docs/UPGRADING.md for the SnapDiff replacements. Silence with " \
+      "`SnapDiff.silence_deprecations = true` or SNAP_DIFF_SILENCE_DEPRECATIONS=1. " \
+      "(shown once per process)"
 
     class << self
+      # Emit {MIGRATION_NOTICE}, exactly once per process. Called from every
+      # v1 entry that can be hooked: the const_missing shims (via {.warn}),
+      # the generated legacy config accessors, and `include
+      # Capybara::Screenshot[::Diff]`.
+      # @return [void]
+      def notice
+        return if @notified || @notice_suppressed || SnapDiff.silence_deprecations?
+
+        first_time = MUTEX.synchronize { @notified ? false : (@notified = true) }
+        Kernel.warn(MIGRATION_NOTICE) if first_time
+      end
+
+      # @api private
+      #
+      # Called at the TOP of every v1-NAMED entry file, before that file's
+      # own requires. Requiring one of those paths IS use of the v1 API,
+      # and it is the ONE door a suite that merely calls `screenshot` goes
+      # through: every other door ({LEGACY_DOORS} in the probe test) needs
+      # the user to call something, which is how beta3 shipped a v1-only
+      # app that produced zero deprecation output.
+      #
+      # Position matters. The marker must run before the file's requires,
+      # because lib/capybara-screenshot-diff.rb reaches the canonical entry
+      # point below on its way in, and a marker placed after that require
+      # would be swallowed by {canonical_entry_point!}.
+      # @return [void]
+      def legacy_entry_point!
+        notice unless @canonical_entry
+      end
+
+      # @api private
+      #
+      # Claimed by lib/snap_diff-capybara.rb -- the canonical gem-name
+      # entry -- which loads the v1 umbrella itself. Without this, "the v1
+      # files got loaded" would be indistinguishable from "a v1 user", and
+      # every `gem "snap_diff-capybara"` app would be told to migrate off
+      # an API it never touched.
+      # @return [void]
+      def canonical_entry_point!
+        @canonical_entry = true
+      end
+
+      # @api private
+      #
+      # Suppresses {MIGRATION_NOTICE} for the rest of the process, without
+      # touching the per-constant warnings. For hosts that ARE the v1
+      # surface rather than users of it -- this gem's own test suite, which
+      # configures through `Capybara::Screenshot.*` by design and would
+      # otherwise print the notice on every run. Deliberately survives
+      # {reset!}, which exists to give a single test a clean slate.
+      # @return [void]
+      def suppress_migration_notice!
+        MUTEX.synchronize { @notice_suppressed = true }
+      end
+
       # Emit a deprecation warning for +subject+, exactly once per unique
-      # +subject+ per process.
+      # +subject+ per process -- preceded, the first time round, by
+      # {MIGRATION_NOTICE}.
       #
       # @param subject [String] the deprecated old-namespace name being
       #   referenced, e.g. "Capybara::Screenshot::Diff::ImageCompare"
       # @param replacement [String] the new-namespace name to use instead
-      # @param category [Symbol] what kind of thing moved, for the human
-      #   reading the message (e.g. :constant, :config)
       # @return [void]
-      def warn(subject, replacement, category:)
+      def warn(subject, replacement)
         return if SnapDiff.silence_deprecations?
 
+        notice
+
         first_time = MUTEX.synchronize do
           @seen.key?(subject) ? false : (@seen[subject] = true)
         end
         return unless first_time
 
-        Kernel.warn(message_for(subject, replacement, category, caller_locations(1)))
+        Kernel.warn(message_for(subject, replacement, caller_locations(1)))
       end
 
       # @api private
@@ -54,13 +132,16 @@ module SnapDiff
       # the suite.
       # @return [void]
       def reset!
-        MUTEX.synchronize { @seen.clear }
+        MUTEX.synchronize do
+          @seen.clear
+          @notified = false
+        end
       end
 
       private
 
-      def message_for(subject, replacement, category, locations)
-        message = "[snap_diff deprecation] `#{subject}` is deprecated (#{category}); " \
+      def message_for(subject, replacement, locations)
+        message = "[snap_diff deprecation] `#{subject}` is deprecated (constant); " \
           "use `#{replacement}` instead."
         origin = origin_for(locations)
         origin ? "#{message} (called from #{origin})" : message
@@ -79,24 +160,4 @@ module SnapDiff
       end
     end
   end
-
-  class << self
-    # @api private
-    attr_accessor :silence_deprecations
-
-    # @api private
-    #
-    # @return [Boolean] true if deprecation warnings should be suppressed,
-    #   either via the {silence_deprecations} accessor or the
-    #   SNAP_DIFF_SILENCE_DEPRECATIONS env var (truthy = "1"/"true").
-    def silence_deprecations?
-      !!silence_deprecations || truthy_env?(ENV["SNAP_DIFF_SILENCE_DEPRECATIONS"])
-    end
-
-    private
-
-    def truthy_env?(value)
-      %w[1 true].include?(value.to_s.downcase)
-    end
-  end
 end

data/lib/snap_diff/driver.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "snap_diff/removal"
+
 module SnapDiff
   # Shared default behavior for image-processing drivers.
   #
@@ -10,6 +12,22 @@ module SnapDiff
   module Driver
     PNG_EXTENSION = ".png"
 
+    # Including this mixin is what makes a custom driver a driver, so it is
+    # where a custom-driver author can be told that 2.1 removes the whole
+    # abstraction. Scoped to drivers that are NOT the gem's own two: both
+    # bundled drivers include it themselves, and warning there would fire on
+    # every plain vips setup -- about code the user does not own.
+    def self.included(base)
+      return if base.name.to_s.start_with?("SnapDiff::")
+
+      Removal.warn_once(
+        :driver_mixin,
+        "`include SnapDiff::Driver` (in #{base.name || base.inspect}) is REMOVED in 2.1: the " \
+        "driver abstraction goes away and libvips becomes the only backend, so custom drivers " \
+        "stop working. There is no replacement -- see docs/drivers.md."
+      )
+    end
+
     def same_dimension?(comparison)
       dimension(comparison.base_image) == dimension(comparison.new_image)
     end

data/lib/snap_diff/drivers/vips_driver.rb

@@ -18,6 +18,17 @@ module SnapDiff
     class VipsDriver
       include SnapDiff::Driver
 
+      # libvips caches loader operations keyed on filename + mtime, and mtime
+      # has ONE-SECOND resolution -- so overwriting a path and re-reading it
+      # within the same second hands back the PREVIOUS image. This gem does
+      # exactly that: the screenshoter writes `<name>.png`,
+      # `checkout_base_screenshot` writes `<name>.base.png` from VCS, and the
+      # comparison then reads both.
+      #
+      # `revalidate: true` tells the loader to skip the cached result (libvips
+      # 8.15+).
+      REVALIDATE = Vips.at_least_libvips?(8, 15) ? {revalidate: true}.freeze : {}.freeze
+
       def find_difference_region(comparison)
         new_image, base_image, options = comparison.new_image, comparison.base_image, comparison.options
 
@@ -86,7 +97,7 @@ module SnapDiff
       end
 
       def from_file(filename)
-        result = ::Vips::Image.new_from_file(filename.to_s)
+        result = ::Vips::Image.new_from_file(filename.to_s, **REVALIDATE)
 
         result = result.colourspace(:srgb) if result.bands < 3
         result = result.bandjoin(255) if result.bands == 3
@@ -115,11 +126,6 @@ module SnapDiff
       private
 
       class << self
-        def difference_area(old_image, new_image, color_distance: 0)
-          mask = difference_mask(new_image, old_image, color_distance)
-          difference_area_size_by(mask)
-        end
-
         def difference_area_size_by(difference_mask)
           diff_mask = difference_mask == 0
           diff_mask.hist_find.to_a[0][0].max

data/lib/snap_diff/drivers.rb

@@ -1,6 +1,16 @@
 # frozen_string_literal: true
 
+require "snap_diff/removal"
+
 module SnapDiff
+  # utils.rb requires THIS file at its top. Requiring it back at load time
+  # made Ruby shout "circular require considered harmful" under $VERBOSE --
+  # which Rake::TestTask sets by default, i.e. every standard Rails/Minitest
+  # suite. Autoload breaks the cycle without narrowing the surface: nothing
+  # here touches Utils until a method runs, and requiring this file still
+  # leaves SnapDiff::Utils resolvable exactly as the eager require did.
+  autoload :Utils, "snap_diff/utils"
+
   # Compare two images and determine if they are equal, different, or within some comparison
   # range considering color values and difference area size.
   module Drivers
@@ -11,24 +21,96 @@ module SnapDiff
       Utils.find_driver_class_for(driver_option).new
     end
 
+    # @api private
+    #
+    # The registry itself, unannounced: driver name => driver class, filled
+    # lazily by Utils.find_driver_class_for and mutated in place. The gem's
+    # own reads go through HERE rather than through .loaded, so the removal
+    # warning below stays a signal about USER code -- a gem that warns at
+    # itself teaches people to ignore its warnings.
+    def self.registry
+      @registry ||= {}
+    end
+
     # Canonical driver-class cache (ADR-008 step 5b, ex
     # Capybara::Screenshot::Diff::LOADED_DRIVERS): driver name => driver
-    # class, filled lazily by Utils.find_driver_class_for. Mutated in
-    # place -- including by user registration through the legacy constant,
-    # which legacy_shims pins as an EAGER same-object alias of this hash
-    # (a lazy copy would silently drop such registrations).
+    # class. Mutated in place -- including by user registration through the
+    # legacy constant, which legacy_shims pins as an EAGER same-object alias
+    # of this hash (a lazy copy would silently drop such registrations).
+    #
+    # THE documented custom-driver registration point (docs/snapdiff.md), so
+    # a custom-driver author has to hear that 2.1 takes it away.
     def self.loaded
-      @loaded ||= {}
+      Removal.warn_once(
+        :drivers_loaded,
+        "`SnapDiff::Drivers.loaded` is REMOVED in 2.1 together with the rest of the driver " \
+        "abstraction (`SnapDiff::Driver`, `SnapDiff::Drivers.available`, `driver: :auto`): " \
+        "libvips becomes the only backend and custom drivers are no longer supported. " \
+        "See docs/drivers.md."
+      )
+      registry
     end
 
-    # Canonical read API for the detected-drivers list. The value itself
-    # stays on Capybara::Screenshot::Diff::AVAILABLE_DRIVERS (assigned in
-    # config_legacy.rb at load time, exactly when detection historically
-    # ran); this reads it live rather than caching, because that constant
-    # is the published stubbing point (image_compare_test stubs it to []
-    # to exercise the no-drivers error path).
+    # Which image drivers this process can actually load, in preference
+    # order. Tries the gem first and falls back to `require`, cleaning up
+    # the half-defined constant a failed native load leaves behind.
+    def self.detect_available
+      result = []
+      begin
+        result << :vips if defined?(Vips) || require("vips")
+      rescue LoadError
+        # vips not present
+        Object.send(:remove_const, :Vips) if defined?(Vips)
+      end
+      begin
+        result << :chunky_png if defined?(ChunkyPNG) || require("chunky_png")
+      rescue LoadError
+        # chunky_png not present
+        Object.send(:remove_const, :ChunkyPNG) if defined?(ChunkyPNG)
+      end
+      result
+    end
+
+    # Canonical home of the detected-drivers list (3.0 readiness: it used
+    # to live only on Capybara::Screenshot::Diff::AVAILABLE_DRIVERS, so
+    # `require "snap_diff/drivers"` alone left .available raising
+    # NameError). Detection runs HERE, at this file's load, and the legacy
+    # constant is now an eager same-object alias of this one.
+    AVAILABLE_DRIVERS = detect_available.freeze
+
+    # The driver classes are documented names (the legacy
+    # `...::Drivers::VipsDriver` path is a same-object alias of this one), so
+    # naming one has to work without a prior require. Autoload rather than
+    # require: naming one must not cost every process the vips/chunky_png
+    # load, and Utils.find_driver_class_for still requires them explicitly.
+    #
+    # Gated on AVAILABLE_DRIVERS, which is why these sit BELOW it. Declaring
+    # them unconditionally made `const_defined?(:VipsDriver)` true on a box
+    # without ruby-vips (neither driver gem is a runtime dependency), so the
+    # documented v1 pattern `Diff.driver = :vips if defined?(...VipsDriver)`
+    # took the branch and then blew up on const_get. v1.12.0 loaded
+    # vips_driver.rb only from find_driver_class_for, so `defined?` was nil
+    # there -- this keeps that.
+    autoload :ChunkyPNGDriver, "snap_diff/drivers/chunky_png_driver" if AVAILABLE_DRIVERS.include?(:chunky_png)
+    autoload :VipsDriver, "snap_diff/drivers/vips_driver" if AVAILABLE_DRIVERS.include?(:vips)
+
+    # Canonical read API for the list above. Reads the constant live rather
+    # than caching, because the constant is the published stubbing point
+    # (image_compare_test stubs it to [] to exercise the no-drivers error
+    # path).
+    #
+    # Detection only exists because there is a choice of backend to detect;
+    # 2.1 removes the choice, so it warns. The gem's own callers read
+    # AVAILABLE_DRIVERS directly -- same value, same stubbing point, no
+    # warning at itself.
     def self.available
-      Capybara::Screenshot::Diff::AVAILABLE_DRIVERS
+      Removal.warn_once(
+        :drivers_available,
+        "`SnapDiff::Drivers.available` is REMOVED in 2.1: with libvips the only backend there " \
+        "is nothing left to detect. Require the `ruby-vips` gem instead of branching on this " \
+        "list. See docs/drivers.md."
+      )
+      AVAILABLE_DRIVERS
     end
   end
 end

data/lib/snap_diff/dsl.rb

@@ -1,18 +1,24 @@
 # frozen_string_literal: true
 
-# No require of "capybara_screenshot_diff" here: every Capybara::Screenshot
-# reference below is inside a method body, resolved lazily at call time, not
-# at this file's own load time -- so this unit has no eager dependency on
-# the umbrella entry point, and requiring it here would create a require
-# cycle back to capybara_screenshot_diff.rb (which requires this file's
-# old-path forwarder).
+# The canonical entry point. Everything a user is told to require under
+# snap_diff/ (this file, snap_diff/integrations/*, snap_diff/static) routes
+# through here, so this one line is what makes SnapDiff.configure/.start/
+# .compare/::VERSION -- and the dual-install guard -- present no matter
+# which of those paths the user picked.
+require "snap_diff"
+
+# Must NOT require "capybara_screenshot_diff": that would cycle back here via
+# this file's old-path forwarder. Nothing from the v1 trees is required here
+# at all (3.0 readiness): the three requires below used to point at their
+# capybara/screenshot/diff/* forwarders, which made this unit depend on the
+# compatibility tree it is meant to replace.
 # DSL includes Capybara::DSL directly below, so it needs the base gem
 # loaded regardless of what pulled this file in.
 require "capybara/dsl"
-require "capybara/screenshot/diff/config_legacy"
-require "capybara/screenshot/diff/drivers"
+require "snap_diff/config"
+require "snap_diff/drivers"
 require "snap_diff/comparison"
-require "capybara/screenshot/diff/screenshot_matcher"
+require "snap_diff/screenshot_matcher"
 require_relative "screenshot_namer"
 require_relative "screenshot_assertion"
 
@@ -27,11 +33,11 @@ module SnapDiff
     include Capybara::DSL
 
     def screenshot_section(name)
-      screenshot_namer.section = name
+      SnapDiff.session.screenshot_namer.section = name
     end
 
     def screenshot_group(name)
-      screenshot_namer.group = name
+      SnapDiff.session.screenshot_namer.group = name
     end
 
     # Takes a screenshot and compares it against a baseline image.
@@ -45,7 +51,7 @@ module SnapDiff
     # @param name [String] The base name of the screenshot, used to generate the filename.
     # @param skip_stack_frames [Integer] The number of stack frames to skip when reporting errors.
     # @param options [Hash] Additional options for taking the screenshot and comparison.
-    # @option options [Boolean] :delayed (Capybara::Screenshot::Diff.delayed)
+    # @option options [Boolean] :delayed (SnapDiff.config.delayed)
     #   Whether to validate the screenshot immediately or delay validation.
     # @option options [Array<Integer>] :crop [left, top, right, bottom] Edge coordinates to crop the screenshot to.
     # @option options [Array<Array<Integer>>] :skip_area Array of [left, top, right, bottom] edge coordinates to ignore.
@@ -58,23 +64,40 @@ module SnapDiff
     # @option options [Numeric] :shift_distance_limit Maximum allowed shift distance for pixels.
     # @option options [Numeric] :area_size_limit Maximum allowed difference area size in pixels.
     # @option options [Symbol] :driver (:auto) The image processing driver to use (:auto, :chunky_png, :vips).
+    # @yield Optional readiness block: work that must happen before the page
+    #   is captured -- settling lazy-loaded images, `document.fonts.ready`,
+    #   waiting on a widget. Runs AFTER the `active?` guard and before the
+    #   capture, exactly once per assertion (not once per stability
+    #   attempt), and an error raised inside it propagates unchanged.
+    #
+    #   The point is not ergonomics -- while screenshots are on, the block
+    #   does nothing a line above the call could not. The point is what
+    #   happens when they are OFF: this method returns at the guard above,
+    #   so a preceding `preload_all_images` still costs its browser
+    #   round-trips while the block costs nothing. Readiness work belongs
+    #   inside the same switch as the capture it serves.
     # @return [Boolean] True if the screenshot was successfully captured and processed.
     # @raise [SnapDiff::ExpectationNotMet] If comparison fails and immediate validation is enabled.
     # @raise [SnapDiff::UnstableImage] If the image comparison is unstable.
     # @raise [SnapDiff::WindowSizeMismatchError] If the window size doesn't match expectations.
     def assert_matches_screenshot(name, skip_stack_frames: 0, **options)
-      return false unless Capybara::Screenshot.active?
+      return false unless SnapDiff.config.active?
+
+      yield if block_given?
 
       # Get the full name with section and group information
       full_name = SnapDiff.session.screenshot_namer.full_name(name)
 
-      # Build the screenshot assertion
-      assertion = build_screenshot_assertion(full_name, options, skip_stack_frames: skip_stack_frames + 1)
+      # Build the screenshot assertion; the actual comparison is deferred
+      # until ScreenshotAssertion#validate! runs.
+      assertion = SnapDiff::ScreenshotMatcher
+        .new(full_name, options)
+        .build_screenshot_assertion(skip_stack_frames: skip_stack_frames + 1)
 
       return false unless assertion
 
       # Determine if validation should be delayed or immediate
-      delayed = options.fetch(:delayed, Capybara::Screenshot::Diff.delayed)
+      delayed = options.fetch(:delayed, SnapDiff.config.delayed)
 
       if delayed
         SnapDiff.session.add_assertion(assertion)
@@ -87,22 +110,28 @@ module SnapDiff
 
     # Convenience wrapper around {#assert_matches_screenshot} and {#capture_screenshot}.
     # @param compare [Boolean] When false, only captures the screenshot without comparing it to a baseline.
+    # @yield Forwarded to whichever of the two it delegates to. A delegator
+    #   that swallowed the block would give the user a readiness block that
+    #   silently never runs.
     # @see #assert_matches_screenshot
     # @see #capture_screenshot
-    def screenshot(name, skip_stack_frames: 0, compare: true, **options)
+    def screenshot(name, skip_stack_frames: 0, compare: true, **options, &readiness)
       if compare
-        assert_matches_screenshot(name, skip_stack_frames: skip_stack_frames + 1, **options)
+        assert_matches_screenshot(name, skip_stack_frames: skip_stack_frames + 1, **options, &readiness)
       else
-        capture_screenshot(name, **options)
+        capture_screenshot(name, **options, &readiness)
       end
     end
 
     # Captures a screenshot without comparing it to a baseline.
     # @param name [String] The base name of the screenshot, used to generate the filename.
     # @param options [Hash] Additional options for taking the screenshot. See {#assert_matches_screenshot}.
+    # @yield Optional readiness block. See {#assert_matches_screenshot}.
     # @return [Boolean] True if the screenshot was successfully captured.
     def capture_screenshot(name, **options)
-      return false unless Capybara::Screenshot.active?
+      return false unless SnapDiff.config.active?
+
+      yield if block_given?
 
       full_name = SnapDiff.session.screenshot_namer.full_name(name)
       SnapDiff::ScreenshotMatcher.new(full_name, options).capture
@@ -113,31 +142,8 @@ module SnapDiff
     # Asserts the current page has no visual changes from the baseline.
     # Override in your base test class to add project-specific behavior
     # (e.g., waiting for Turbo, default skip areas).
-    def assert_no_screenshot_changes(name, skip_stack_frames: 0, **opts)
-      assert_matches_screenshot(name, skip_stack_frames: skip_stack_frames + 1, **opts)
-    end
-
-    private
-
-    # Builds a screenshot assertion object that can be validated immediately or later.
-    #
-    # This method constructs a screenshot assertion that encapsulates the comparison logic.
-    # The actual comparison is deferred until {ScreenshotAssertion#validate!} is called.
-    #
-    # @param name [String] The full name of the screenshot, including any section/group context.
-    # @param options [Hash] Options for screenshot taking and comparison.
-    #   See {#assert_matches_screenshot} for available options.
-    # @param skip_stack_frames [Integer] Number of stack frames to skip for error reporting.
-    # @return [ScreenshotAssertion, nil] The assertion object or nil if no assertion is needed.
-    # @see ScreenshotAssertion
-    def build_screenshot_assertion(name, options, skip_stack_frames: 0)
-      SnapDiff::ScreenshotMatcher
-        .new(name, options)
-        .build_screenshot_assertion(skip_stack_frames: skip_stack_frames + 1)
-    end
-
-    def screenshot_namer
-      SnapDiff.session.screenshot_namer
+    def assert_no_screenshot_changes(name, skip_stack_frames: 0, **opts, &readiness)
+      assert_matches_screenshot(name, skip_stack_frames: skip_stack_frames + 1, **opts, &readiness)
     end
   end
 end

data/lib/snap_diff/errors.rb

@@ -8,6 +8,12 @@ require "snap_diff/error_with_filtered_backtrace"
 # shims, because rescue clauses and defined?/const_defined? feature
 # detection in adopter code must keep behaving exactly as before
 # (const_defined? never triggers const_missing).
+#
+# Error is the catch-all docs/snapdiff.md advertises: EVERY error this gem
+# raises inherits it, so `rescue SnapDiff::Error` really does catch them all
+# (pinned by test/unit/errors_alias_test.rb, which discovers the classes
+# rather than listing them). ErrorWithFilteredBacktrace is plumbing, not a
+# second root.
 module SnapDiff
   class Error < ErrorWithFilteredBacktrace; end
 
@@ -15,5 +21,5 @@ module SnapDiff
 
   class UnstableImage < Error; end
 
-  class WindowSizeMismatchError < ErrorWithFilteredBacktrace; end
+  class WindowSizeMismatchError < Error; end
 end

data/lib/snap_diff/integrations/cucumber.rb

@@ -8,7 +8,7 @@ require "snap_diff/reporting"
 World(::SnapDiff::DSL)
 
 Before do
-  Capybara::Screenshot::Diff.delayed = false
+  SnapDiff.config.delayed = false
   SnapDiff::BrowserHelpers.resize_window_if_needed
 end
 

data/lib/snap_diff/integrations/minitest.rb

@@ -8,14 +8,21 @@ require_relative "../dsl"
 require "snap_diff/screenshot_assertion"
 require "snap_diff/reporting"
 
-used_deprecated_entrypoint = caller.any? do |path|
-  path.include?("capybara-screenshot-diff.rb") || path.include?("capybara/screenshot/diff.rb")
-end
-
-if used_deprecated_entrypoint
+# Only the v1 NAMESPACE entry is a deprecated choice: requiring
+# "capybara/screenshot/diff" is a line in the user's own file, and changing
+# it is the fix. The gem-NAME file (lib/capybara-screenshot-diff.rb) is not:
+# `Bundler.require` requires the gem's own name, so it loads for everyone
+# with the gem in their Gemfile whatever they require explicitly -- keying
+# the warning off it shouted at every user on every run, with no action
+# available to silence it. See test/legacy/minitest_activation_warning_test.rb.
+#
+# Silenceable through the documented switch (SnapDiff.silence_deprecations /
+# SNAP_DIFF_SILENCE_DEPRECATIONS): it was a bare Kernel#warn, so the one knob
+# the docs offer did not reach it.
+if !SnapDiff.silence_deprecations? && caller.any? { |path| path.include?("capybara/screenshot/diff.rb") }
   warn <<~MSG
-    [DEPRECATION] The default activation of `capybara_screenshot_diff/minitest` will be removed.
-                  Please `require "capybara_screenshot_diff/minitest"` explicitly.
+    [DEPRECATION] `require "capybara/screenshot/diff"` activates the Minitest assertions for you; that will be removed.
+                  Please `require "snap_diff/integrations/minitest"` explicitly.
   MSG
 end
 
@@ -24,8 +31,20 @@ module SnapDiff
     module Assertions
       include ::SnapDiff::DSL
 
+      # The `if` is the whole point (issue #270). `super` returns false
+      # immediately when screenshots are disabled -- nothing captured,
+      # nothing compared -- so counting unconditionally reported
+      # `1 runs, 1 assertions, 0 failures` over a test that asserted
+      # nothing at all.
+      #
+      # Getting the count right hands the alarm to Rails for free: it
+      # prepends ActiveSupport::Testing::TestsWithoutAssertions into every
+      # ActiveSupport::TestCase (test_case.rb:205), which warns
+      # "Test is missing assertions: `test_x`" on exactly the tests whose
+      # sole assertion was a disabled screenshot -- and stays quiet for
+      # tests that assert something else.
       def assert_matches_screenshot(*args, skip_stack_frames: 0, **opts)
-        self.assertions += 1
+        self.assertions += 1 if SnapDiff.config.active?
 
         super(*args, skip_stack_frames: skip_stack_frames + 1, **opts)
       rescue ::SnapDiff::ExpectationNotMet => e
@@ -66,4 +85,21 @@ module SnapDiff
   end
 end
 
-::Minitest.after_run { SnapDiff::Reporting.finalize! } if ::Minitest.respond_to?(:after_run)
+# Under Rails' `parallelize(workers: N)` the tests run in forked children
+# that never reach `after_run`, so the report and the summary line were
+# lost on every suite past the parallelization threshold (issue #258).
+# Registering the worker-side hook has to happen before `parallelize`
+# forks; with `Bundler.require` this file loads before
+# ActiveSupport::TestCase exists, so try now and again when it appears.
+unless SnapDiff::Reporting.install_parallel_hooks!
+  if defined?(::ActiveSupport) && ::ActiveSupport.respond_to?(:on_load)
+    ::ActiveSupport.on_load(:active_support_test_case) { SnapDiff::Reporting.install_parallel_hooks! }
+  end
+end
+
+if ::Minitest.respond_to?(:after_run)
+  ::Minitest.after_run do
+    SnapDiff::Reporting.merge_parallel_fragments!
+    SnapDiff::Reporting.finalize!
+  end
+end

data/lib/snap_diff/integrations/rspec.rb

@@ -9,6 +9,17 @@ require "snap_diff/reporting"
 RSpec::Matchers.define :match_screenshot do |name, **options|
   description { "match screenshot '#{name}'" }
 
+  # The literal `true` is deliberate, not the Minitest miscount of issue
+  # #270. `assert_matches_screenshot` returns false when screenshots are
+  # disabled, and returning that here would FAIL the example for a config
+  # switch the user set on purpose. A real mismatch does not come back as
+  # false either -- it raises SnapDiff::ExpectationNotMet, or is deferred
+  # to the append_after hook below.
+  #
+  # There is nothing to hand off to the way Minitest hands off to Rails'
+  # TestsWithoutAssertions: RSpec has no assertion count, so a disabled
+  # screenshot leaves an example that passed having checked nothing, and
+  # only the end-of-run `0 verified` line can see it.
   match do |_page|
     assert_matches_screenshot(name, **options)
     true