capybara-screenshot-diff 1.15.0 → 2.0.0.alpha1

data/lib/capybara_screenshot_diff/reporters/html.rb

@@ -1,137 +1,7 @@
 # frozen_string_literal: true
 
-require "base64"
-require "erb"
-require "fileutils"
-require "pathname"
-require "json"
-
-module CapybaraScreenshotDiff
-  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?(CapybaraScreenshotDiff::Reporters::HTML)
-  CapybaraScreenshotDiff.reporters << CapybaraScreenshotDiff::Reporters::HTML.new(embed_images: !!ENV["CI"])
-end
+# Forwarder (ADR-004 v2 step 6): CapybaraScreenshotDiff::Reporters::HTML now
+# resolves lazily via snap_diff/legacy_shims' const_missing, with a
+# deprecation warning pointing at SnapDiff::Reporters::HTML.
+require "snap_diff/reporters/html"
+require "snap_diff/legacy_shims"

data/lib/capybara_screenshot_diff/rspec.rb

@@ -1,66 +1,8 @@
 # frozen_string_literal: true
 
-require "rspec/core"
-require "capybara_screenshot_diff/dsl"
+# Legacy entry point: pre-move, this path transitively loaded the whole gem
+# (via dsl -> umbrella). Preserve that contract for consumers who require
+# only this file.
+require "capybara_screenshot_diff"
 
-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 CapybaraScreenshotDiff::DSL, type: :feature
-  config.include CapybaraScreenshotDiff::DSL, type: :system
-
-  config.before do
-    if self.class.include?(CapybaraScreenshotDiff::DSL)
-      Capybara::Screenshot::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?(CapybaraScreenshotDiff::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
+require "snap_diff/integrations/rspec"

data/lib/capybara_screenshot_diff/screenshot_assertion.rb

@@ -1,163 +1,42 @@
 # frozen_string_literal: true
 
-require "fileutils"
-
-module CapybaraScreenshotDiff
-  class ScreenshotAssertion
-    attr_reader :name, :args
-    attr_accessor :compare, :caller
-
-    def initialize(name, **args)
-      @name = name
-      @args = args
-    end
-
-    def validate
-      return unless compare
-
-      self.class.assert_image_not_changed(caller, name, compare)
-    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, ImageCompare))] 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 This method is used internally to verify individual screenshots.
-    def self.assert_image_not_changed(backtrace, name, comparison)
-      result = comparison.different?
-
-      # Cleanup after comparisons
-      if !result && comparison.base_image_path.exist?
-        FileUtils.mv(comparison.base_image_path, comparison.image_path, force: true)
-      end
-
-      return unless result
-
-      "Screenshot does not match for '#{name}': #{comparison.error_message}\n#{backtrace.join("\n")}"
-    end
-  end
-
-  class AssertionRegistry
-    attr_reader :assertions, :screenshot_namer, :new_screenshots
-
-    def initialize
-      @assertions = []
-      @new_screenshots = []
-      @screenshot_namer = CapybaraScreenshotDiff::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 = CapybaraScreenshotDiff::ScreenshotNamer.new
-    end
-  end
-end
-
+require "snap_diff/screenshot_assertion"
+require "snap_diff/reporting"
+# ScreenshotAssertion / AssertionRegistry forward lazily (with deprecation
+# warnings) via snap_diff/legacy_shims' const_missing since v2 step 6.
+require "snap_diff/legacy_shims"
+
+# CapybaraScreenshotDiff's module methods cover two lifecycles with
+# different scopes, kept separate below:
+#
+# - Session lifecycle: thread-local, per-test. The AssertionRegistry holds
+#   the assertions and screenshot names of the test running on this thread;
+#   `reset` clears it between tests.
+# - Reporter lifecycle: process-global, suite-long. Owned by
+#   SnapDiff::Reporting; the methods here are thin public shims over it.
+#
+# `reset` is the one deliberate bridge between the two: a finished test's
+# assertions are handed to the reporters before the registry is cleared.
 module CapybaraScreenshotDiff
   class << self
     require "forwardable"
     extend Forwardable
 
+    # --- Session lifecycle (thread-local, per-test) ---
+
     def registry
-      Thread.current[:capybara_screenshot_diff_registry] ||= AssertionRegistry.new
+      Thread.current[:capybara_screenshot_diff_registry] ||= SnapDiff::AssertionRegistry.new
     end
 
-    def_delegator :registry, :add_assertion
-    def_delegator :registry, :assertions
-    def_delegator :registry, :assertions_present?
-    def_delegator :registry, :failed_assertions
-    def_delegator :registry, :record_new_screenshot
-    def_delegator :registry, :new_screenshots
-    def_delegator :registry, :new_screenshots_present?
+    def_delegators :registry, :add_assertion, :assertions, :assertions_present?,
+      :failed_assertions, :record_new_screenshot, :new_screenshots,
+      :new_screenshots_present?, :screenshot_namer, :verify
+
     def reset
       notify_reporters(registry.assertions)
       registry.reset
     end
 
-    def reporters
-      @reporters ||= []
-    end
-
-    attr_reader :reporters_mutex
-
-    def finalize_reporters!
-      reporters_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
-
-    def_delegator :registry, :screenshot_namer
-    def_delegator :registry, :verify
-
     # Message to skip the test with when a new screenshot has no baseline yet
     # and `pending_if_new` is enabled. Adapters call this after verifying
     # screenshots, and skip the test with the returned message when present.
@@ -169,21 +48,24 @@ module CapybaraScreenshotDiff
       "No baseline for: #{new_screenshots.join(", ")}. Commit the captured screenshots to record them."
     end
 
-    private
+    # --- Reporter lifecycle (process-global, suite-long) ---
 
-    def notify_reporters(assertions)
-      return if assertions.nil? || assertions.empty?
+    def reporters
+      SnapDiff::Reporting.reporters
+    end
 
-      reporters_snapshot = reporters_mutex.synchronize { reporters.dup }
-      return if reporters_snapshot.empty?
+    def reporters_mutex
+      SnapDiff::Reporting.mutex
+    end
 
-      reporters_snapshot.each do |reporter|
-        reporter.record(assertions)
-      rescue => e
-        warn "[capybara-screenshot-diff] Reporter failed: #{e.message}"
-      end
+    def finalize_reporters!
+      SnapDiff::Reporting.finalize!
     end
-  end
 
-  @reporters_mutex = Mutex.new
+    private
+
+    def notify_reporters(assertions)
+      SnapDiff::Reporting.notify(assertions)
+    end
+  end
 end

data/lib/capybara_screenshot_diff/screenshot_namer.rb

@@ -1,81 +1,7 @@
 # frozen_string_literal: true
 
-require "fileutils"
-require "pathname"
-
-module CapybaraScreenshotDiff
-  # Handles the naming, path generation, and organization of screenshots.
-  # This class encapsulates logic related to screenshot sections, groups,
-  # and counters, providing a centralized way to determine screenshot filenames
-  # and directories.
-  class ScreenshotNamer
-    attr_reader :section, :group
-
-    def initialize(screenshot_area = nil)
-      @section = nil
-      @group = nil
-      @counter = nil
-      @screenshot_area = screenshot_area
-    end
-
-    def screenshot_area
-      @screenshot_area ||= Capybara::Screenshot.screenshot_area
-    end
-
-    # Sets the current section for screenshots.
-    # @param name [String, nil] The name of the section.
-    def section=(name)
-      @section = name&.to_s
-      reset_group_counter
-    end
-
-    # Sets the current group for screenshots and resets the counter.
-    # @param name [String, nil] The name of the group.
-    def group=(name)
-      @group = name&.to_s
-      reset_group_counter
-    end
-
-    # Builds the full, unique name for a screenshot, including any counter.
-    # @param base_name [String] The base name for the screenshot.
-    # @return [String] The full screenshot name.
-    def full_name(base_name)
-      name = base_name.to_s
-
-      if @counter
-        name = format("%02i_%s", @counter, name)
-        @counter += 1
-      end
-
-      File.join(*directory_parts.push(name.to_s))
-    end
-
-    # Builds the full path for a screenshot file, including section and group directories.
-    # @param base_name [String] The base name for the screenshot.
-    # @return [String] The absolute path for the screenshot file.
-    def full_name_with_path(base_name)
-      File.join(screenshot_area, full_name(base_name))
-    end
-
-    # Returns the directory parts (section and group) for constructing paths.
-    # @return [Array<String>] An array of directory names.
-    def directory_parts
-      parts = []
-      parts << @section unless @section.nil? || @section.empty?
-      parts << @group unless @group.nil? || @group.empty?
-      parts
-    end
-
-    # Calculates the directory path for the current section and group.
-    # @return [String] The full path to the directory.
-    def current_group_directory
-      File.join(*([screenshot_area] + directory_parts))
-    end
-
-    private
-
-    def reset_group_counter
-      @counter = (@group.nil? || @group.empty?) ? nil : 0
-    end
-  end
-end
+# Forwarder (ADR-004 v2 step 6): CapybaraScreenshotDiff::ScreenshotNamer now
+# resolves lazily via snap_diff/legacy_shims' const_missing, with a
+# deprecation warning pointing at SnapDiff::ScreenshotNamer.
+require "snap_diff/screenshot_namer"
+require "snap_diff/legacy_shims"

data/lib/capybara_screenshot_diff/snap.rb

@@ -1,66 +1,7 @@
 # frozen_string_literal: true
 
-module CapybaraScreenshotDiff
-  class Snap
-    attr_reader :full_name, :format, :path, :base_path, :manager, :attempt_path, :prev_attempt_path, :attempts_count
-
-    def initialize(full_name, format, manager: SnapManager.instance)
-      @full_name = full_name
-      @format = format
-      @path = manager.abs_path_for(Pathname.new(@full_name).sub_ext(".#{@format}"))
-      @base_path = @path.sub_ext(".base.#{@format}")
-      @manager = manager
-      @attempts_count = 0
-    end
-
-    def delete!
-      path.delete if path.exist?
-      base_path.delete if base_path.exist?
-      cleanup_diff_artifacts!
-      cleanup_attempts!
-    end
-
-    def checkout_base_screenshot
-      @manager.checkout_file(path, base_path)
-    end
-
-    def path_for(version = :actual)
-      case version
-      when :base
-        base_path
-      else
-        path
-      end
-    end
-
-    def next_attempt_path!
-      @prev_attempt_path = @attempt_path
-      @attempt_path = path.sub_ext(sprintf(".attempt_%02i.#{format}", @attempts_count))
-    ensure
-      @attempts_count += 1
-    end
-
-    def commit_last_attempt
-      @manager.move(attempt_path, path)
-    end
-
-    def cleanup_attempts!
-      @manager.cleanup_attempts!(self)
-      @attempts_count = 0
-    end
-
-    def find_attempts_paths
-      Dir[@manager.abs_path_for("**/#{full_name}.attempt_[0-9][0-9].#{format}")]
-    end
-
-    private
-
-    def cleanup_diff_artifacts!
-      [
-        path.sub_ext(".diff.#{format}"),
-        path.sub_ext(".heatmap.diff.#{format}"),
-        base_path.sub_ext(".diff.#{format}")
-      ].each { |f| f.unlink if f.exist? }
-    end
-  end
-end
+# Forwarder (ADR-004 v2 step 6): CapybaraScreenshotDiff::Snap now resolves
+# lazily via snap_diff/legacy_shims' const_missing, with a deprecation
+# warning pointing at SnapDiff::Snap.
+require "snap_diff/snap"
+require "snap_diff/legacy_shims"

data/lib/capybara_screenshot_diff/snap_manager.rb

@@ -1,84 +1,7 @@
 # frozen_string_literal: true
 
-require "capybara/screenshot/diff/vcs"
-require "active_support/core_ext/module/attribute_accessors"
-
-require "capybara_screenshot_diff/snap"
-
-module CapybaraScreenshotDiff
-  class SnapManager
-    attr_reader :root
-
-    def initialize(root)
-      @root = Pathname.new(root)
-      @snapshots = Set.new
-    end
-
-    def snapshot(screenshot_full_name, screenshot_format = "png")
-      Snap.new(screenshot_full_name, screenshot_format, manager: self).tap do |snapshot|
-        @snapshots << snapshot
-      end
-    end
-
-    def self.snapshot(screenshot_full_name, screenshot_format = "png")
-      instance.snapshot(screenshot_full_name, screenshot_format)
-    end
-
-    def abs_path_for(relative_path)
-      @root / relative_path
-    end
-
-    def checkout_file(path, as_path)
-      create_output_directory_for(as_path) unless as_path.exist?
-      Capybara::Screenshot::Diff::Vcs.checkout_vcs(root, path, as_path)
-    end
-
-    def provision_snap_with(snap, path, version: :actual)
-      managed_path = snap.path_for(version)
-      create_output_directory_for(managed_path) unless managed_path.exist?
-      FileUtils.cp(path, managed_path)
-    end
-
-    def create_output_directory_for(path = nil)
-      path ? path.dirname.mkpath : root.mkpath
-    end
-
-    # TODO: rename to delete!
-    def cleanup!
-      snapshots.each do |snapshot|
-        cleanup_attempts!(snapshot)
-        snapshot.delete!
-      end
-    end
-
-    def self.cleanup!
-      instance.cleanup!
-    end
-
-    def cleanup_attempts!(snapshot)
-      FileUtils.rm_rf snapshot.find_attempts_paths, secure: true
-    end
-
-    def move(new_screenshot_path, screenshot_path)
-      FileUtils.mv(new_screenshot_path, screenshot_path, force: true)
-    end
-
-    def screenshots
-      root.children.map { |f| f.basename.to_s }
-    end
-
-    attr_reader :snapshots
-
-    def self.screenshots
-      instance.screenshots
-    end
-
-    def self.root
-      instance.root
-    end
-
-    def self.instance
-      Capybara::Screenshot::Diff.manager.new(Capybara::Screenshot.screenshot_area_abs)
-    end
-  end
-end
+# Forwarder (ADR-004 v2 step 6): CapybaraScreenshotDiff::SnapManager now
+# resolves lazily via snap_diff/legacy_shims' const_missing, with a
+# deprecation warning pointing at SnapDiff::SnapManager.
+require "snap_diff/snap_manager"
+require "snap_diff/legacy_shims"