capybara-screenshot-diff 1.15.0 → 2.0.0.alpha1

data/lib/snap_diff/image_preprocessor.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module SnapDiff
+  # Handles image preprocessing operations (skip_area and median filtering)
+  #
+  # This class applies preprocessing filters to images before comparison,
+  # such as masking specific regions (skip_area) or applying noise reduction.
+  # It's designed to work with either direct image objects or with options.
+  class ImagePreprocessor
+    attr_reader :driver, :options
+
+    def initialize(driver, options = {})
+      @driver = driver
+      @options = options
+    end
+
+    # Process a comparison object directly
+    # This allows reusing the comparison's existing options
+    # @param [Comparison] comparison the comparison object
+    # @return [Comparison] the comparison object
+    def process_comparison(comparison)
+      # Process both images
+      comparison.base_image = process_image(comparison.base_image, comparison.base_image_path)
+      comparison.new_image = process_image(comparison.new_image, comparison.new_image_path)
+
+      comparison
+    end
+
+    private
+
+    def process_image(image, path)
+      result = image
+      result = apply_skip_area(result) if skip_area
+      result = apply_median_filter(result, path) if median_filter_window_size
+      result
+    end
+
+    def apply_skip_area(image)
+      skip_area.reduce(image) do |result, region|
+        driver.add_black_box(result, region)
+      end
+    end
+
+    def apply_median_filter(image, path)
+      if driver.supports?(:filter_image_with_median)
+        driver.filter_image_with_median(image, median_filter_window_size)
+      else
+        warn_about_skipped_median_filter(path)
+        image
+      end
+    end
+
+    def warn_about_skipped_median_filter(path)
+      warn(
+        "[capybara-screenshot-diff] Median filter has been skipped for #{path} " \
+        "because it is not supported by #{driver.class}"
+      )
+    end
+
+    def skip_area
+      options[:skip_area]
+    end
+
+    def median_filter_window_size
+      options[:median_filter_window_size]
+    end
+  end
+end

data/lib/snap_diff/integrations/cucumber.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# See the matching comment in integrations/minitest.rb.
+require_relative "../dsl"
+require "capybara_screenshot_diff/screenshot_assertion"
+
+World(::SnapDiff::DSL)
+
+Before do
+  Capybara::Screenshot::Diff.delayed = false
+  SnapDiff::BrowserHelpers.resize_window_if_needed
+end
+
+After do |scenario|
+  if !scenario.failed? && (msg = CapybaraScreenshotDiff.pending_screenshots_message)
+    skip_this_scenario(msg)
+  end
+ensure
+  CapybaraScreenshotDiff.reset
+end
+
+AfterAll { CapybaraScreenshotDiff.finalize_reporters! }

data/lib/snap_diff/integrations/minitest.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "minitest"
+require_relative "../dsl"
+# The CapybaraScreenshotDiff.verify/.reset/.pending_screenshots_message/
+# .finalize_reporters! calls below need the registry singleton machinery,
+# which lives in the *old* capybara_screenshot_diff/screenshot_assertion.rb
+# file (deliberately not moved -- see that file's own comment) and is no
+# longer pulled in transitively by requiring dsl.rb alone.
+require "capybara_screenshot_diff/screenshot_assertion"
+
+used_deprecated_entrypoint = caller.any? do |path|
+  path.include?("capybara-screenshot-diff.rb") || path.include?("capybara/screenshot/diff.rb")
+end
+
+if used_deprecated_entrypoint
+  warn <<~MSG
+    [DEPRECATION] The default activation of `capybara_screenshot_diff/minitest` will be removed.
+                  Please `require "capybara_screenshot_diff/minitest"` explicitly.
+  MSG
+end
+
+module SnapDiff
+  module Minitest
+    module Assertions
+      include ::SnapDiff::DSL
+
+      def assert_matches_screenshot(*args, skip_stack_frames: 0, **opts)
+        self.assertions += 1
+
+        super(*args, skip_stack_frames: skip_stack_frames + 1, **opts)
+      rescue ::CapybaraScreenshotDiff::ExpectationNotMet => e
+        raise ::Minitest::Assertion, e.message
+      end
+
+      def setup
+        super
+        ::SnapDiff::BrowserHelpers.resize_window_if_needed
+      end
+
+      def before_teardown
+        super
+        CapybaraScreenshotDiff.verify
+
+        # 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)
+        failures << assertion
+      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
+
+::Minitest.after_run { CapybaraScreenshotDiff.finalize_reporters! } if ::Minitest.respond_to?(:after_run)

data/lib/snap_diff/integrations/rspec.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+require_relative "../dsl"
+# See the matching comment in integrations/minitest.rb.
+require "capybara_screenshot_diff/screenshot_assertion"
+
+RSpec::Matchers.define :match_screenshot do |name, **options|
+  description { "match screenshot '#{name}'" }
+
+  match do |_page|
+    assert_matches_screenshot(name, **options)
+    true
+  end
+
+  failure_message do
+    "Expected page to match screenshot '#{name}'"
+  end
+
+  failure_message_when_negated do
+    "Expected page not to match screenshot '#{name}'"
+  end
+end
+
+RSpec.configure do |config|
+  config.include SnapDiff::DSL, type: :feature
+  config.include SnapDiff::DSL, type: :system
+
+  config.before do
+    if self.class.include?(SnapDiff::DSL)
+      SnapDiff::BrowserHelpers.resize_window_if_needed
+    end
+  end
+
+  # `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?(SnapDiff::DSL)
+      begin
+        CapybaraScreenshotDiff.verify
+
+        # 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) }
+      ensure
+        CapybaraScreenshotDiff.reset
+      end
+    end
+  end
+
+  config.after(:suite) { CapybaraScreenshotDiff.finalize_reporters! }
+end

data/lib/snap_diff/legacy_shims.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "snap_diff/deprecation"
+require "snap_diff/drivers"
+
+# ADR-004 v2 step 6: 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):
+#
+# - 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.
+# - 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.
+module SnapDiff
+  # @api private
+  module LegacyShims
+    # Installs a warn-then-forward const_missing on +namespace+.
+    #
+    # @param namespace [Module] the old namespace to hook
+    # @param old_prefix [String] how the old constant path reads to a human
+    # @param mapping [Hash{Symbol => String}] old leaf name => new full name
+    def self.install(namespace, old_prefix, mapping)
+      namespace.define_singleton_method(:const_missing) do |name|
+        target = mapping[name]
+        return super(name) unless target
+
+        Deprecation.warn("#{old_prefix}::#{name}", target, category: :constant)
+        Object.const_get(target)
+      end
+    end
+  end
+end
+
+module Capybara
+  module Screenshot
+    module Diff
+    end
+  end
+end
+
+module CapybaraScreenshotDiff
+  module Reporters
+  end
+end
+
+SnapDiff::LegacyShims.install(Capybara::Screenshot, "Capybara::Screenshot", {
+  BrowserHelpers: "SnapDiff::BrowserHelpers",
+  Screenshoter: "SnapDiff::Screenshoter"
+}.freeze)
+
+SnapDiff::LegacyShims.install(Capybara::Screenshot::Diff, "Capybara::Screenshot::Diff", {
+  Vcs: "SnapDiff::Vcs",
+  StableScreenshoter: "SnapDiff::StableScreenshoter",
+  ImagePreprocessor: "SnapDiff::ImagePreprocessor",
+  AreaCalculator: "SnapDiff::AreaCalculator",
+  AnnotationService: "SnapDiff::AnnotationService",
+  Utils: "SnapDiff::Utils",
+  ScreenshotMatcher: "SnapDiff::ScreenshotMatcher",
+  Drivers: "SnapDiff::Drivers",
+  ImageCompare: "SnapDiff::Comparison",
+  Difference: "SnapDiff::ComparisonResult"
+}.freeze)
+
+SnapDiff::LegacyShims.install(CapybaraScreenshotDiff, "CapybaraScreenshotDiff", {
+  RED_RGBA: "SnapDiff::RED_RGBA",
+  ORANGE_RGBA: "SnapDiff::ORANGE_RGBA",
+  SnapManager: "SnapDiff::SnapManager",
+  Snap: "SnapDiff::Snap",
+  ScreenshotNamer: "SnapDiff::ScreenshotNamer",
+  AttemptsReporter: "SnapDiff::AttemptsReporter",
+  BacktraceFilter: "SnapDiff::BacktraceFilter",
+  ErrorWithFilteredBacktrace: "SnapDiff::ErrorWithFilteredBacktrace",
+  ScreenshotAssertion: "SnapDiff::ScreenshotAssertion",
+  AssertionRegistry: "SnapDiff::AssertionRegistry"
+}.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(SnapDiff::Drivers, "Capybara::Screenshot::Diff::Drivers", {
+  BaseDriver: "SnapDiff::Driver"
+}.freeze)

data/lib/snap_diff/os.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module SnapDiff
+  module Os
+    ON_WINDOWS = !!(RbConfig::CONFIG["host_os"] =~ /mswin|mingw|cygwin/)
+    ON_MAC = !!(RbConfig::CONFIG["host_os"] =~ /darwin/)
+    ON_LINUX = !!(RbConfig::CONFIG["host_os"] =~ /linux/)
+
+    def self.name
+      return "windows" if ON_WINDOWS
+      return "macos" if ON_MAC
+      return "linux" if ON_LINUX
+
+      "unknown"
+    end
+  end
+end

data/lib/snap_diff/reporters/html.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "base64"
+require "erb"
+require "fileutils"
+require "pathname"
+require "json"
+# The auto-registration block at the bottom of this file calls
+# CapybaraScreenshotDiff.reporters, which needs the registry singleton
+# machinery in the *old* capybara_screenshot_diff/screenshot_assertion.rb
+# file (deliberately not moved -- see that file's own comment).
+require "capybara_screenshot_diff/screenshot_assertion"
+require "capybara/screenshot/diff/config_legacy"
+
+module SnapDiff
+  module Reporters
+    class HTML
+      attr_reader :failures, :total
+
+      def initialize(output_path: nil, embed_images: false)
+        @explicit_output_path = output_path
+        @embed_images = embed_images
+        @failures = []
+        @total = 0
+        @finalized = false
+        @mutex = Mutex.new
+      end
+
+      def record(assertions)
+        return if @finalized
+
+        failures = []
+        total = 0
+
+        assertions.each do |assertion|
+          compare = assertion.compare
+          next unless compare
+
+          total += 1
+          next unless compare.difference&.different?
+
+          failures << failure_entry_for(assertion.name, compare)
+        rescue => e
+          warn "[snap_diff] Reporter skipped '#{assertion.name}': #{e.message}" if ENV["DEBUG"]
+        end
+
+        @mutex.synchronize do
+          return if @finalized
+          @total += total
+          @failures.concat(failures)
+        end
+      end
+
+      def finalize
+        @mutex.synchronize do
+          return if @finalized
+          return if failures.empty?
+
+          write_report
+          @finalized = true
+          output_path
+        end
+      end
+
+      def output_path
+        @output_path ||= Pathname.new(@explicit_output_path || self.class.default_output_path)
+      end
+
+      def passed = total - failures.size
+      def failed = failures.size
+
+      def summary
+        return if total.zero?
+
+        screenshots_label = (total == 1) ? "1 screenshot" : "#{total} screenshots"
+
+        if failures.empty?
+          "[snap_diff] #{screenshots_label} compared, no failures."
+        else
+          failures_label = (failures.size == 1) ? "1 failure" : "#{failures.size} failures"
+          "[snap_diff] #{screenshots_label} compared, #{failures_label}. Report: #{output_path}"
+        end
+      end
+
+      def render
+        ERB.new(File.read(self.class.template_path)).result(binding)
+      end
+
+      def self.template_path
+        File.expand_path("templates/report.html.erb", __dir__)
+      end
+
+      def self.default_output_path
+        root = Capybara::Screenshot.root || Pathname.pwd
+        root / Capybara::Screenshot.save_path / "snap_diff_report.html"
+      end
+
+      private
+
+      def failure_entry_for(name, compare)
+        difference = compare.difference
+        {
+          name: name,
+          original: resolve_image(compare.base_image_path),
+          new: resolve_image(compare.image_path),
+          base_diff: resolve_image(compare.reporter.annotated_base_image_path),
+          diff: resolve_image(compare.reporter.annotated_image_path),
+          heatmap: resolve_image(compare.reporter.heatmap_diff_path),
+          diff_level: difference.ratio && (difference.ratio * 100).round(2),
+          area_size: difference.region_area_size,
+          max_color_distance: difference.meta[:max_color_distance]&.round(1)
+        }
+      end
+
+      def resolve_image(path)
+        return unless path
+
+        pathname = Pathname.new(path).expand_path
+        return unless pathname.exist?
+
+        @embed_images ? data_uri(pathname) : pathname.relative_path_from(output_path.dirname.expand_path).to_s
+      end
+
+      def data_uri(pathname)
+        ext = pathname.extname.delete_prefix(".")
+        mime = (ext == "webp") ? "image/webp" : "image/png"
+        "data:#{mime};base64,#{Base64.strict_encode64(pathname.binread)}"
+      end
+
+      def write_report
+        FileUtils.mkdir_p(output_path.dirname)
+        File.write(output_path, render)
+      end
+    end
+  end
+end
+
+# Auto-register reporter.
+# Framework adapters (Minitest, RSpec, Cucumber) call finalize_reporters! via native hooks.
+# For custom frameworks, call CapybaraScreenshotDiff.finalize_reporters! manually.
+unless CapybaraScreenshotDiff.reporters.any?(SnapDiff::Reporters::HTML)
+  CapybaraScreenshotDiff.reporters << SnapDiff::Reporters::HTML.new(embed_images: !!ENV["CI"])
+end

data/lib/snap_diff/reporting.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module SnapDiff
+  # Process-global reporter lifecycle: registration, per-test notification,
+  # end-of-suite finalization. One list of reporters for the whole process,
+  # guarded by one mutex.
+  #
+  # Deliberately separate from the per-test session lifecycle (the
+  # thread-local AssertionRegistry reached through
+  # CapybaraScreenshotDiff.registry): reporters outlive any single test,
+  # the registry does not. CapybaraScreenshotDiff keeps its public
+  # reporters/reporters_mutex/finalize_reporters! methods as thin shims
+  # over this module.
+  module Reporting
+    @reporters = []
+    @mutex = Mutex.new
+
+    class << self
+      attr_reader :reporters, :mutex
+
+      # Delivers a finished test's assertions to every registered reporter.
+      # Iterates over a snapshot so a reporter mutating the list mid-notify
+      # cannot affect the current round. A raising reporter is warned about
+      # and skipped; the rest are still notified.
+      def notify(assertions)
+        return if assertions.nil? || assertions.empty?
+
+        reporters_snapshot = @mutex.synchronize { @reporters.dup }
+        return if reporters_snapshot.empty?
+
+        reporters_snapshot.each do |reporter|
+          reporter.record(assertions)
+        rescue => e
+          warn "[capybara-screenshot-diff] Reporter failed: #{e.message}"
+        end
+      end
+
+      # End-of-suite hook: finalizes each reporter and prints its summary.
+      # A raising reporter is warned about and skipped; the rest are still
+      # finalized.
+      def finalize!
+        @mutex.synchronize { @reporters.dup }.each do |reporter|
+          reporter.finalize
+          if (msg = reporter.summary)
+            $stdout.puts msg
+          end
+        rescue => e
+          warn "[snap_diff] Reporter #{reporter.class} failed (#{e.class}: #{e.message})"
+        end
+      end
+    end
+  end
+end

data/lib/snap_diff/screenshot_assertion.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "screenshot_namer"
+
+module SnapDiff
+  class ScreenshotAssertion
+    attr_reader :name, :args
+    attr_accessor :compare, :caller
+
+    def initialize(name, **args)
+      @name = name
+      @args = args
+    end
+
+    # One-line debugging summary. Never triggers the (expensive, file-touching)
+    # comparison itself: an unprocessed comparison shows as "pending".
+    def inspect
+      return "#<#{self.class.name} #{name.inspect} (no comparison)>" unless compare
+
+      state = if compare.processed?
+        compare.difference.different? ? "different" : "matches"
+      else
+        "pending"
+      end
+      "#<#{self.class.name} #{name.inspect} #{state} new=#{compare.image_path} base=#{compare.base_image_path}>"
+    end
+
+    def validate
+      return unless compare
+
+      if compare.different?
+        "Screenshot does not match for '#{name}': #{compare.error_message}\n#{caller.join("\n")}"
+      else
+        archive_baseline!
+        nil
+      end
+    end
+
+    # Commits the baseline after a passing comparison: the base image is
+    # moved over the actual image, so the captured screenshot becomes the
+    # recorded baseline again. This is the file-mutating half of the verify
+    # flow, kept explicit and separate from the pure "are they different?"
+    # question. Idempotent: a second call is a no-op.
+    def archive_baseline!
+      return unless compare && !compare.different? && compare.base_image_path.exist?
+
+      FileUtils.mv(compare.base_image_path, compare.image_path, force: true)
+    end
+
+    def validate!
+      error_msg = validate
+
+      if error_msg
+        raise CapybaraScreenshotDiff::ExpectationNotMet.new(error_msg, caller)
+      end
+    end
+
+    # Verifies that all scheduled screenshots do not show any unintended differences.
+    #
+    # @param screenshots [Array(Array(Array(String), String, Comparison))] The list of match screenshots jobs. Defaults to all screenshots taken during the test.
+    # @return [Array, nil] Returns an array of error messages if there are screenshot differences, otherwise nil.
+    # @note This method is typically called at the end of a test to assert all screenshots are as expected.
+    def self.verify_screenshots!(screenshots)
+      return unless ::Capybara::Screenshot.active? && ::Capybara::Screenshot::Diff.fail_on_difference
+
+      test_screenshot_errors = screenshots.map do |assertion|
+        assertion.validate
+      end
+
+      test_screenshot_errors.compact!
+
+      test_screenshot_errors.empty? ? nil : test_screenshot_errors
+    end
+
+    # Asserts that an image has not changed compared to its baseline.
+    #
+    # @param backtrace [Array(String)] The caller context, used for error reporting.
+    # @param name [String] The name of the screenshot being verified.
+    # @param comparison [Object] The comparison object containing the result and details of the comparison.
+    # @return [String, nil] Returns an error message if the screenshot differs from the baseline, otherwise nil.
+    # @note Legacy entry point; delegates to the instance verify flow
+    #   (pure question + explicit #archive_baseline! on pass).
+    def self.assert_image_not_changed(backtrace, name, comparison)
+      assertion = new(name)
+      assertion.caller = backtrace
+      assertion.compare = comparison
+      assertion.validate
+    end
+  end
+
+  class AssertionRegistry
+    attr_reader :assertions, :screenshot_namer, :new_screenshots
+
+    def initialize
+      @assertions = []
+      @new_screenshots = []
+      @screenshot_namer = SnapDiff::ScreenshotNamer.new
+    end
+
+    def add_assertion(assertion)
+      return unless assertion&.compare
+
+      @assertions.push(assertion)
+
+      assertion
+    end
+
+    def assertions_present?
+      !@assertions.empty?
+    end
+
+    def record_new_screenshot(name)
+      @new_screenshots.push(name)
+    end
+
+    def new_screenshots_present?
+      !@new_screenshots.empty?
+    end
+
+    def verify(screenshots = CapybaraScreenshotDiff.assertions)
+      return unless ::Capybara::Screenshot.active? && ::Capybara::Screenshot::Diff.fail_on_difference
+
+      failed_assertions = CapybaraScreenshotDiff.registry.failed_assertions
+      failed_screenshot = failed_assertions.first
+      result = ScreenshotAssertion.verify_screenshots!(screenshots)
+
+      if result
+        raise CapybaraScreenshotDiff::ExpectationNotMet.new(result.join("\n\n"), failed_screenshot.caller)
+      end
+    end
+
+    def failed_assertions
+      assertions.filter { |screenshot_assert| screenshot_assert.compare&.different? }
+    end
+
+    def reset
+      @assertions.clear
+      @new_screenshots.clear
+      @screenshot_namer = SnapDiff::ScreenshotNamer.new
+    end
+  end
+end