snap_diff-capybara 0.0.1 → 2.0.0.beta1

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