snap_diff-capybara 2.0.0.beta2 → 2.0.0.beta4

data/lib/snap_diff/legacy_shims.rb

@@ -1,37 +1,92 @@
 # frozen_string_literal: true
 
+require "snap_diff/comparison"
+require "snap_diff/config"
 require "snap_diff/deprecation"
 require "snap_diff/drivers"
+require "snap_diff/errors"
+require "snap_diff/os"
+require "snap_diff/reporters/default"
+require "snap_diff/version"
 
-# ADR-004 v2 step 6: const_missing-based forwarders for the pre-v2
-# namespaces. Every old-name lookup below resolves -- lazily -- to the exact
+# THE v1 compatibility surface, in one file -- and the whole of it that is
+# code. lib/capybara* is alias-only by contract
+# (legacy_tree_is_alias_only_test.rb) and the canonical core names nothing
+# from it (core_tree_has_no_legacy_deps_test.rb), so this file plus those
+# trees is exactly what 3.0 deletes.
+#
+# Three things live here:
+#   1. the const_missing forwarders for the pre-v2 namespaces (below);
+#   2. CONFIG_MAPPING -- the old mattr_accessor surface, generated as thin
+#      delegators onto SnapDiff.config (which owns the storage);
+#   3. the derived/config forwarders that used to sit in config_legacy.rb
+#      (Screenshot.active?, Diff.configure, SnapDiff.start, ...).
+#
+# 2 and 3 moved here so `require "snap_diff"` can keep offering the full v1
+# surface -- as it always has -- without the core requiring anything from
+# lib/capybara/.
+#
+# const_missing-based forwarders for the pre-v2 namespaces. Every old-name
+# lookup below resolves -- lazily -- to the exact
 # same object as its SnapDiff:: replacement (identity pinned by
 # test/unit/namespace_forwarding_test.rb) and emits a deprecation warning,
 # once per constant per process, silenceable via
 # SnapDiff.silence_deprecations or SNAP_DIFF_SILENCE_DEPRECATIONS=1.
 #
-# Deliberately eager-and-silent exceptions (plain constants, defined by
-# their own forwarder files, never warn):
+# Deliberately eager-and-silent exceptions (plain constants assigned BELOW,
+# never warn individually -- the once-per-process migration notice still
+# fires for the paths that CAN be hooked; see Deprecation.notice):
 #
-# - Capybara::Screenshot::Os and CapybaraScreenshotDiff::DSL (and the
-#   unmapped CapybaraScreenshotDiff::Minitest::Assertions): advertised
-#   entry-point constants probed with Object.const_defined? by
-#   support_load_probe_test.rb -- const_defined? never triggers
-#   const_missing, so a lazy shim would break that contract.
-# - Capybara::Screenshot::Diff::VERSION: the gemspec resolves it at build
-#   time; a lazy shim would make every `gem build` warn.
+# - Capybara::Screenshot::Os: an advertised entry-point constant probed with
+#   Object.const_defined? by support_load_probe_test.rb -- const_defined?
+#   never triggers const_missing, so a lazy shim would break that contract.
+# - Capybara::Screenshot::Diff::VERSION, and ::Comparison (the images
+#   struct): documented user-facing names that adopters feature-detect with
+#   defined?/const_defined?.
+# - Capybara::Screenshot::Diff::Reporters::Default (a documented subclassing
+#   extension point): same reasoning.
+# - The CapybaraScreenshotDiff error classes: rescue-by-old-name and
+#   defined? feature detection must keep behaving exactly as before.
 # - Drivers::ChunkyPNGDriver / Drivers::VipsDriver: real constants on the
 #   shared SnapDiff::Drivers module (the Drivers alias is same-object by
 #   contract), so const_missing can never fire for the leaf names;
-#   resolving them through the old path still warns for ...::Drivers.
+#   resolving them through the old path still warns for ...::Drivers. They
+#   are `autoload`ed there, so naming one loads it.
 # - Diff::LOADED_DRIVERS: user code registers custom drivers by mutating
 #   this hash in place, so it must be the exact same object as the
 #   canonical SnapDiff::Drivers.loaded -- a lazy warn-once shim could not
 #   keep a mutable alias, and warning on a supported registration surface
 #   would be noise. Assigned eagerly below.
-# - Diff::AVAILABLE_DRIVERS: stays a real constant defined by
-#   config_legacy.rb (detection runs at that load moment);
-#   SnapDiff::Drivers.available is the canonical reader.
+# - Diff::AVAILABLE_DRIVERS: stays a real constant, aliased BELOW from the
+#   canonical SnapDiff::Drivers::AVAILABLE_DRIVERS (same object;
+#   SnapDiff::Drivers.available is the canonical reader, and its constant is
+#   the stubbing point -- stubbing this alias only rebinds the alias).
+#
+# All of them are assigned HERE rather than in their own forwarder files
+# under lib/capybara*. Those forwarders are loaded only by the LEGACY entry
+# points, so a partially migrated app -- one that swapped its `require` line
+# for a canonical `snap_diff*` one first, exactly as UPGRADING.md tells it
+# to, and has not renamed its constants yet -- lost every one of them and
+# died on `uninitialized constant Capybara::Screenshot::Os`. This file is
+# required by every entry point, canonical and legacy, so it is the only
+# place the eager exceptions can actually be eager.
+#
+# CapybaraScreenshotDiff::DSL and ::Minitest::Assertions are the two that
+# CANNOT be eager here: snap_diff/dsl requires "snap_diff" (which requires
+# this file), and snap_diff/integrations/minitest pulls in the minitest gem,
+# which no canonical entry point should force on a process. They are mapped
+# lazily below instead, and stay eager under the legacy entry points that
+# load their forwarder files.
+
+# The v1 namespaces, predefined empty so CONFIG_MAPPING can name them at
+# class-body eval time. Everything below reopens them.
+module Capybara
+  module Screenshot
+    module Diff
+    end
+  end
+end
+
 module SnapDiff
   # @api private
   module LegacyShims
@@ -45,20 +100,207 @@ module SnapDiff
         target = mapping[name]
         return super(name) unless target
 
-        Deprecation.warn("#{old_prefix}::#{name}", target, category: :constant)
-        Object.const_get(target)
+        Deprecation.warn("#{old_prefix}::#{name}", target)
+        LegacyShims.resolve("#{old_prefix}::#{name}", target)
+      end
+    end
+
+    # The handful of replacements whose file name does not follow the gem's
+    # own convention (SnapDiff::AreaCalculator -> snap_diff/area_calculator).
+    REQUIRE_PATHS = {
+      "SnapDiff::Minitest::Assertions" => "snap_diff/integrations/minitest"
+    }.freeze
+
+    # Resolving an old name has to LOAD the replacement, not merely name it.
+    # The v1 entry points required the whole gem, so v1 code could say
+    # `Capybara::Screenshot::Diff::Utils` with nothing else required; the
+    # canonical entry points are lean, so the shim used to resolve its
+    # mapping and then die on a bare "uninitialized constant SnapDiff::Utils"
+    # -- an internal name the reader has no way to act on.
+    def self.resolve(old_name, target)
+      require_unit(target) unless Object.const_defined?(target)
+      Object.const_get(target)
+    rescue NameError
+      # Deliberately does NOT advise "reference #{target} directly": we just
+      # failed to load it, so that name does not exist either.
+      raise NameError, "`#{old_name}` maps to `#{target}`, which this process cannot load. " \
+        "See docs/UPGRADING.md for the v1 -> SnapDiff name map."
+    end
+
+    def self.require_unit(target)
+      require(REQUIRE_PATHS[target] || target
+        .gsub("::", "/")
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .downcase)
+    rescue LoadError
+      # No file of its own -- the name lives inside another unit
+      # (SnapDiff::RED_RGBA, ::BacktraceFilter). The const_get above decides
+      # whether it is already loaded.
+    end
+
+    # config attr name => [legacy module, legacy accessor name].
+    # The keys are exactly SnapDiff::Config::SETTINGS; this hash only says
+    # which of the two legacy holders each one used to hang off, and under
+    # what name (only +screenshot_enabled+ differs -- see Config::SETTINGS).
+    CONFIG_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],
+      # New in 2.0 and it has no v1 history, but it is storage on the one
+      # Config like everything else, and the two-views invariant is
+      # all-or-nothing: an unmapped setting is storage the v1 surface cannot
+      # see. Mapping it also means a user still on the old namespace reaches
+      # the accept workflow without migrating first.
+      record: [Capybara::Screenshot::Diff, :record],
+      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
+
+    # Installs the old mattr_accessor surface onto the legacy modules,
+    # delegating to the single storage in SnapDiff.config. mattr_accessor
+    # used to define both singleton and instance accessors (the instance
+    # ones are what `include Capybara::Screenshot::Diff` picks up), so both
+    # are installed. root keeps its historical asymmetry -- readable
+    # everywhere, writable only at module level (it was mattr_reader plus a
+    # custom module-level writer) -- with the Pathname coercion living in
+    # Config#root=.
+    def self.install_config_accessors
+      CONFIG_MAPPING.each do |name, (mod, mattr)|
+        [mod, mod.singleton_class].each do |target|
+          target.define_method(mattr) do
+            Deprecation.notice
+            SnapDiff.config.public_send(name)
+          end
+          next if name == :root && target == mod
+
+          target.define_method(:"#{mattr}=") do |value|
+            Deprecation.notice
+            SnapDiff.config.public_send(:"#{name}=", value)
+          end
+        end
+      end
+    end
+
+    # `include Capybara::Screenshot::Diff` is the third way into the v1
+    # surface (it picks up the instance-level accessors installed above) and
+    # resolves no deprecated constant of its own, so it needs its own hook
+    # for the once-per-process notice.
+    def self.install_include_notice(mod)
+      mod.define_singleton_method(:included) do |base|
+        Deprecation.notice
+        super(base)
       end
     end
   end
 end
 
+SnapDiff::LegacyShims.install_config_accessors
+SnapDiff::LegacyShims.install_include_notice(Capybara::Screenshot)
+SnapDiff::LegacyShims.install_include_notice(Capybara::Screenshot::Diff)
+
+module SnapDiff
+  # v1-style configuration: yields the two legacy accessor holders
+  # (+Capybara::Screenshot+, +Capybara::Screenshot::Diff+) exactly as
+  # +Capybara::Screenshot::Diff.configure+ always has -- and, since ADR-008
+  # step 7b, this is where that yield actually happens; Diff.configure
+  # forwards here. Both names stay identical in call shape.
+  #
+  #   SnapDiff.start do |screenshot, diff|
+  #     screenshot.window_size = [1280, 1024]
+  #     diff.tolerance = 0.0005
+  #   end
+  #
+  # Defined in this file, not snap_diff.rb, because the two holders it
+  # yields ARE the v1 surface: it cannot outlive them. The consolidated
+  # shape, SnapDiff.configure, is the canonical one and lives in the core.
+  def self.start
+    yield Capybara::Screenshot, Capybara::Screenshot::Diff
+  end
+end
+
 module Capybara
   module Screenshot
+    # EAGER same-object alias (see header): the only place it can be eager
+    # for a canonical-only require, which is what a half-migrated app has.
+    Os = SnapDiff::Os
+
+    # Derived config, ex config_legacy.rb: one-line forwarders onto the
+    # canonical implementations in SnapDiff::Config (ADR-008 step 7b).
+    class << self
+      def active?
+        SnapDiff.config.active?
+      end
+
+      def screenshot_area
+        SnapDiff.config.screenshot_area
+      end
+
+      def screenshot_area_abs
+        SnapDiff.config.screenshot_area_abs
+      end
+    end
+
     module Diff
-      # EAGER same-object alias of the canonical driver cache (see header).
-      LOADED_DRIVERS = SnapDiff::Drivers.loaded
+      # EAGER same-object aliases of canonical values (see header for why
+      # each one is eager rather than a warn-once const_missing shim).
+      # .registry, not .loaded: this alias is assigned at load time by the
+      # gem itself, and .loaded announces its own 2.1 removal. Same object
+      # either way -- which is the whole point of the alias.
+      LOADED_DRIVERS = SnapDiff::Drivers.registry
+      AVAILABLE_DRIVERS = SnapDiff::Drivers::AVAILABLE_DRIVERS
+      Comparison = SnapDiff::Comparison::Images
+      VERSION = SnapDiff::VERSION
 
       module Reporters
+        Default = SnapDiff::Reporters::Default
+      end
+
+      # Configure screenshot and diff settings in one block.
+      #
+      #   Capybara::Screenshot::Diff.configure do |screenshot, diff|
+      #     screenshot.window_size = [1280, 1024]
+      #     screenshot.stability_time_limit = 1
+      #     diff.driver = :vips
+      #     diff.tolerance = 0.0005
+      #   end
+      # The bare `yield` (rather than an explicit &block) keeps this
+      # method's published arity byte-identical to what it always had.
+      def self.configure
+        SnapDiff.start { |screenshot, diff| yield screenshot, diff }
+      end
+
+      def self.compare(baseline_path, current_path, **options)
+        SnapDiff.compare(baseline_path, current_path, **options)
+      end
+
+      def self.default_options
+        SnapDiff::Deprecation.notice
+        SnapDiff.config.default_options
       end
     end
   end
@@ -67,6 +309,19 @@ end
 module CapybaraScreenshotDiff
   module Reporters
   end
+
+  # Predefined so the mapping below has a namespace to hang const_missing
+  # on; capybara_screenshot_diff/minitest reopens it with the eager alias.
+  module Minitest
+  end
+
+  # EAGER same-object aliases (see header): rescue-by-old-name and
+  # defined?/const_defined? feature detection must behave as they always
+  # have, under canonical and legacy requires alike.
+  CapybaraScreenshotDiffError = SnapDiff::Error
+  ExpectationNotMet = SnapDiff::ExpectationNotMet
+  UnstableImage = SnapDiff::UnstableImage
+  WindowSizeMismatchError = SnapDiff::WindowSizeMismatchError
 end
 
 SnapDiff::LegacyShims.install(Capybara::Screenshot, "Capybara::Screenshot", {
@@ -84,14 +339,9 @@ SnapDiff::LegacyShims.install(Capybara::Screenshot::Diff, "Capybara::Screenshot:
   ScreenshotMatcher: "SnapDiff::ScreenshotMatcher",
   Drivers: "SnapDiff::Drivers",
   ImageCompare: "SnapDiff::Comparison",
-  Comparison: "SnapDiff::Comparison::Images",
   Difference: "SnapDiff::ComparisonResult"
 }.freeze)
 
-SnapDiff::LegacyShims.install(Capybara::Screenshot::Diff::Reporters, "Capybara::Screenshot::Diff::Reporters", {
-  Default: "SnapDiff::Reporters::Default"
-}.freeze)
-
 SnapDiff::LegacyShims.install(CapybaraScreenshotDiff, "CapybaraScreenshotDiff", {
   RED_RGBA: "SnapDiff::RED_RGBA",
   ORANGE_RGBA: "SnapDiff::ORANGE_RGBA",
@@ -102,16 +352,21 @@ SnapDiff::LegacyShims.install(CapybaraScreenshotDiff, "CapybaraScreenshotDiff",
   BacktraceFilter: "SnapDiff::BacktraceFilter",
   ErrorWithFilteredBacktrace: "SnapDiff::ErrorWithFilteredBacktrace",
   ScreenshotAssertion: "SnapDiff::ScreenshotAssertion",
-  AssertionRegistry: "SnapDiff::AssertionRegistry"
+  AssertionRegistry: "SnapDiff::AssertionRegistry",
+  DSL: "SnapDiff::DSL"
 }.freeze)
 
 SnapDiff::LegacyShims.install(CapybaraScreenshotDiff::Reporters, "CapybaraScreenshotDiff::Reporters", {
   HTML: "SnapDiff::Reporters::HTML"
 }.freeze)
 
-# BaseDriver dissolved into the SnapDiff::Driver mixin (v2 step 4); the
-# Drivers alias is same-object, so the hook has to live on SnapDiff::Drivers
-# itself. `class MyDriver < BaseDriver` becomes `include SnapDiff::Driver`.
+SnapDiff::LegacyShims.install(CapybaraScreenshotDiff::Minitest, "CapybaraScreenshotDiff::Minitest", {
+  Assertions: "SnapDiff::Minitest::Assertions"
+}.freeze)
+
+# BaseDriver dissolved into the SnapDiff::Driver mixin; the Drivers alias is
+# same-object, so the hook has to live on SnapDiff::Drivers itself.
+# `class MyDriver < BaseDriver` becomes `include SnapDiff::Driver`.
 SnapDiff::LegacyShims.install(SnapDiff::Drivers, "Capybara::Screenshot::Diff::Drivers", {
   BaseDriver: "SnapDiff::Driver"
 }.freeze)

data/lib/snap_diff/removal.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module SnapDiff
+  # @api private
+  #
+  # Announces what 2.1 REMOVES, from the 2.0 line that still supports it:
+  # the chunky_png driver, +shift_distance_limit+ (chunky-only, it dies with
+  # it) and the driver abstraction (+SnapDiff::Driver+,
+  # +SnapDiff::Drivers.loaded+ / +.available+, <tt>driver: :auto</tt>) --
+  # libvips becomes the only backend. 2.0 is the transitional release: the
+  # contract is published before it is enforced.
+  #
+  # Same shape and same silencing switches as {SnapDiff::Deprecation}, which
+  # announces the other half (the v1 namespaces), but a file of its own: the
+  # legacy shims and their deprecation channel are themselves part of what is
+  # removed, while the call sites here -- utils, config, drivers -- are core
+  # files that outlive them, so they cannot depend on a doomed file. That is
+  # also why {SnapDiff.silence_deprecations} lives HERE rather than in
+  # deprecation.rb: it is the one switch that silences both halves.
+  #
+  # Deliberately not a warn-per-call channel: one line per subject per
+  # process is an actionable signal, N lines per comparison is noise people
+  # learn to filter out.
+  module Removal
+    # Everything under lib/ is "the gem"; the first caller frame outside it
+    # is the user code that touched the doomed API.
+    GEM_LIB_DIR = File.expand_path("..", __dir__) + File::SEPARATOR
+
+    # Appended to every message, so the individual messages can stay about
+    # the thing being removed.
+    SILENCE_HINT =
+      "Silence with `SnapDiff.silence_deprecations = true` or " \
+      "SNAP_DIFF_SILENCE_DEPRECATIONS=1. (shown once per process)"
+
+    # The one message with two call sites -- the setting's writer (Config)
+    # and the per-comparison option (Comparison) -- so it lives here rather
+    # than in either of them. One subject, one warning, whichever fires.
+    SHIFT_DISTANCE_LIMIT_REMOVED =
+      "`shift_distance_limit` is REMOVED in 2.1: it is implemented only by the chunky_png " \
+      "driver, which is removed with it. libvips has no shift-distance comparison -- drop the " \
+      "option and tune `tolerance` / `color_distance_limit` instead. See docs/configuration.md."
+
+    # Also one subject with several call sites -- the setting's writer
+    # (Config) and the raw per-screenshot / per-compare option hashes.
+    # Deliberately value-blind: `driver: :vips` warns too. It is the knob
+    # that picks between implementations, and 2.1 leaves one implementation,
+    # so the line goes whatever it currently says.
+    DRIVER_REMOVED =
+      "The `driver` setting and the per-screenshot `driver:` option are REMOVED in 2.1: libvips " \
+      "becomes the only backend, so there is nothing left to select. Drop the option and depend " \
+      "on the `ruby-vips` gem instead. See docs/drivers.md."
+
+    # --- the new-screenshot booleans, superseded by `record:` (#259) -----
+    #
+    # Three separate settings, each answering some part of "what happens
+    # when there is no baseline / when there is a difference", none of them
+    # naming the action the user actually wants. 2.0 adds the verb --
+    # `SnapDiff.config.record` -- and 2.1 removes the booleans. Each message
+    # names the mode that replaces THAT setting, and nothing more: `record:`
+    # supersedes the missing-baseline half squarely and the other two only
+    # obliquely, and a message that overclaims is a message that misroutes.
+
+    FAIL_IF_NEW_REMOVED =
+      "`fail_if_new` is REMOVED in 2.1: the record modes replace it. `SnapDiff.config.record = :none` " \
+      "is `fail_if_new = true`, `= :once` is `fail_if_new = false` -- and unlike the boolean, a mode " \
+      "means the same thing on CI and off it. See docs/configuration.md."
+
+    PENDING_IF_NEW_REMOVED =
+      "`pending_if_new` is REMOVED in 2.1: it skips the test instead of saying what to do about the " \
+      "missing baseline. `SnapDiff.config.record = :none` fails with the `git add` command attached; " \
+      "`= :once` records it and reports it in the end-of-run summary. See docs/configuration.md."
+
+    FAIL_ON_DIFFERENCE_REMOVED =
+      "`fail_on_difference` is REMOVED in 2.1: a screenshot that differs from its baseline fails, " \
+      "which is what the gem is for. To ACCEPT a difference, re-record it -- " \
+      "`SnapDiff.config.record = :all` -- and commit the result. See docs/configuration.md."
+
+    # Not a removal: 2.0 announces it and 2.1 turns it into an ArgumentError.
+    # The whole reason unrecognised keys need announcing is that the options
+    # hash was frozen but never validated, so a typo -- or a v1 option that
+    # no longer exists -- configured nothing, silently, forever.
+    def self.unknown_option(key)
+      "`#{key.inspect}` is not a recognised screenshot option, so it does nothing. 2.1 raises " \
+        "ArgumentError for it. Check the spelling against the option list in docs/configuration.md."
+    end
+
+    MUTEX = Mutex.new
+    @seen = {}
+    @suppressed = false
+
+    class << self
+      # Emit +message+ once per +subject+ per process, via Kernel#warn (so
+      # anything hooking +Warning.warn+ sees it like any other Ruby warning).
+      #
+      # @param subject [Symbol] dedup key -- the doomed API, not the call site
+      # @param message [String] what is removed, when, and what to do instead
+      # @return [void]
+      def warn_once(subject, message)
+        return if @suppressed || SnapDiff.silence_deprecations?
+
+        first_time = MUTEX.synchronize { @seen.key?(subject) ? false : (@seen[subject] = true) }
+        return unless first_time
+
+        Kernel.warn(with_origin("[snap_diff deprecation] #{message} #{SILENCE_HINT}", caller_locations(1)))
+      end
+
+      # @api private
+      #
+      # Silences these warnings for the rest of the process, without touching
+      # the v1-namespace ones. For hosts that exercise the doomed APIs BY
+      # DESIGN rather than depending on them -- this gem's own suite runs the
+      # whole comparison matrix on chunky_png and sets shift_distance_limit,
+      # and its test_helper raises on any deprecation output.
+      # @return [void]
+      def suppress!
+        MUTEX.synchronize { @suppressed = true }
+      end
+
+      private
+
+      def with_origin(message, locations)
+        origin = origin_for(locations)
+        origin ? "#{message} (called from #{origin})" : message
+      end
+
+      # First frame outside the gem's lib dir, formatted "file:line"; nil
+      # when every frame is internal (or paths are unavailable).
+      def origin_for(locations)
+        (locations || []).each do |location|
+          path = location.absolute_path || location.path
+          next if path.nil? || path.start_with?(GEM_LIB_DIR)
+
+          return "#{path}:#{location.lineno}"
+        end
+        nil
+      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/reporters/default.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
+require "json"
+
 require "snap_diff/annotation_service"
+# For SnapDiff.config.root, the base for the relative artifact paths below.
+require "snap_diff/config"
 
 module SnapDiff
   module Reporters
@@ -47,22 +51,6 @@ module SnapDiff
         annotation_service.annotate_and_save_images
       end
 
-      def save_annotation_for(image, image_path)
-        annotation_service.save_annotation_for(image, image_path)
-      end
-
-      def annotate_difference(image, region)
-        annotation_service.annotate_difference(image, region)
-      end
-
-      def annotate_skip_areas(image, skip_areas)
-        annotation_service.annotate_skip_areas(image, skip_areas)
-      end
-
-      def save(image, image_path)
-        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") }
@@ -73,20 +61,95 @@ module SnapDiff
 
       NEW_LINE = "\n"
 
+      # The thresholds a comparison is judged against, in the order they read
+      # best. Only the ones actually set are printed -- see #thresholds.
+      THRESHOLDS = [
+        :tolerance,
+        :area_size_limit,
+        :color_distance_limit,
+        :shift_distance_limit,
+        :perceptual_threshold
+      ].freeze
+
+      # The five artifacts a comparison can leave on disk, in the order a
+      # reader wants them: the two inputs first, then what we drew on them.
+      ARTIFACT_LABELS = {
+        "baseline" => :base_image_path,
+        "actual" => :image_path,
+        "baseline annotated" => :annotated_base_image_path,
+        "actual annotated" => :annotated_image_path,
+        "heatmap" => :heatmap_diff_path
+      }.freeze
+
       def build_error_message
-        [
-          "(#{difference.to_h.to_json})",
-          image_path.to_path,
-          annotated_base_image_path.to_path,
-          annotated_image_path.to_path,
-          heatmap_diff_path.to_path
-        ].join(NEW_LINE)
+        [headline, *metric_lines, *artifact_lines].join(NEW_LINE)
       end
 
       private
 
       attr_reader :annotation_service
 
+      # Reads as the tail of "Screenshot does not match for 'name': ".
+      def headline
+        width, height = driver.dimension(comparison.base_image)
+        total_pixels = width * height
+        area = difference.region_area_size
+
+        "the change spans #{area.round} of #{total_pixels} px " \
+          "(#{percent(area.to_f / total_pixels)} of the #{width}x#{height} image)"
+      end
+
+      def metric_lines
+        lines = ["  changed region: #{difference.coordinates.to_json} (left,top,right,bottom edges)"]
+        # difference_level is the changed share of the image area -- the
+        # number `tolerance` is compared against. Only computed when a
+        # tolerance is set, so only printed then.
+        if difference.ratio
+          lines << "  difference level: #{difference.ratio} (#{percent(difference.ratio)} of the image area)"
+        end
+        max_color_distance = difference.meta[:max_color_distance]
+        lines << "  max color distance: #{max_color_distance}" if max_color_distance&.positive?
+        max_shift_distance = difference.meta[:max_shift_distance]
+        lines << "  max shift distance: #{max_shift_distance} px" if max_shift_distance&.positive?
+        lines << "  judged against: #{thresholds}"
+      end
+
+      def thresholds
+        applied = THRESHOLDS.filter_map do |name|
+          value = difference.options[name]
+          "#{name} #{value}" if value
+        end
+
+        applied.empty? ? "no tolerance thresholds configured (any difference fails)" : applied.join(", ")
+      end
+
+      # Only what is on disk gets a line: the heatmap exists solely for
+      # drivers that produce a diff mask, and a comparison can be reported
+      # before either input has been written out.
+      def artifact_lines
+        present = ARTIFACT_LABELS.filter_map do |label, path_method|
+          path = send(path_method)
+          [label, path] if path.exist?
+        end
+        width = present.map { |label, _path| label.length }.max.to_i
+
+        present.map { |label, path| "  #{"#{label}:".ljust(width + 1)} #{display_path(path)}" }
+      end
+
+      # Relative to the configured root: shorter to read, and still
+      # click-through-able in terminals that resolve paths against the
+      # working directory. Anything outside the root stays absolute, because
+      # a "../../.." path is neither.
+      def display_path(path)
+        relative = path.expand_path.relative_path_from(SnapDiff.config.root).to_path
+        relative.start_with?("..") ? path.to_path : relative
+      end
+
+      def percent(fraction)
+        value = fraction * 100
+        (value.positive? && value < 0.01) ? "<0.01%" : format("%.2f%%", value)
+      end
+
       def base_image_path
         comparison.base_image_path
       end