capybara-screenshot-diff 1.10.3.1 → 1.13.0

data/docs/reporters.md

@@ -0,0 +1,46 @@
+# Reporters
+
+## Web UI for Reviewing Screenshot Changes
+
+Generate an interactive Web UI report of screenshot differences:
+
+```ruby
+# Add to test_helper.rb — one line, that's it
+require 'capybara_screenshot_diff/reporters/html'
+```
+
+After running tests, open the report (generated only when there are failures):
+
+```bash
+open doc/screenshots/snap_diff_report.html
+```
+
+The report includes a sidebar with thumbnails, side-by-side comparison with diff toggle, search, and summary stats. No configuration needed — just require it.
+
+**Note:** The report is not generated when all screenshots match. In parallel test environments, each worker writes to the same file — the last worker's results will be in the report.
+
+## Custom Reporters
+
+Build your own reporter by implementing `record` and `finalize`:
+
+```ruby
+class MyReporter
+  def record(assertions)
+    assertions.each do |assertion|
+      next unless assertion.compare&.difference&.different?
+      # process the failure — send to Slack, write JSON, etc.
+    end
+  end
+
+  def finalize
+    # called once at process exit — write summary, upload report, etc.
+  end
+end
+
+# Register in test_helper.rb
+CapybaraScreenshotDiff.reporters << MyReporter.new
+```
+
+Reporters are notified before assertions are cleared on each test teardown. `finalize` is called via `at_exit`.
+
+[← Back to README](../README.md)

data/docs/thread_safety.md

@@ -0,0 +1,97 @@
+# Thread Safety Guide for Parallel Testing
+
+This document explains how `snap_diff` behaves under Rails parallel tests with the `:thread` strategy.
+
+## Overview
+
+`snap_diff` is thread safe for parallel test execution as long as global configuration is set before tests run. Per-thread state is isolated, and shared state is protected where it matters.
+
+## Architecture Summary
+
+### Per-thread Assertion Registry
+
+Each thread gets its own `AssertionRegistry` stored in thread-local storage:
+
+```ruby
+def registry
+  Thread.current[:capybara_screenshot_diff_registry] ||= AssertionRegistry.new
+end
+```
+
+This prevents cross-thread leakage for assertions and screenshot naming.
+
+### Reporters Snapshot on Notify
+
+Reporters are notified using a snapshot protected by an eagerly initialized mutex:
+
+```ruby
+@reporters_mutex = Mutex.new
+
+def notify_reporters(assertions)
+  reporters_snapshot = reporters_mutex.synchronize { reporters.dup }
+  reporters_snapshot.each { |reporter| reporter.record(assertions) }
+end
+```
+
+This ensures a stable list while notifying without forcing a global lock around reporter work.
+
+### HTML Reporter Internal Lock
+
+The HTML reporter protects `@failures`, `@total`, and `@finalized` with a mutex so `record` and `finalize` can run safely:
+
+```ruby
+@mutex.synchronize do
+  return if @finalized
+  @total += total
+  @failures.concat(failures)
+end
+```
+
+`@finalized` is set only after `write_report` succeeds, so a failed write can be retried.
+
+### Screenshot Naming Isolation
+
+Each thread gets its own `ScreenshotNamer` via the per-thread registry, so counters, sections, and groups do not collide.
+
+### SnapManager Per Call
+
+`SnapManager` returns a new instance for each call, avoiding shared mutable state.
+
+## Global Configuration
+
+Configuration uses `mattr_accessor` and should be set once before tests run. Do not mutate config during parallel execution.
+
+## Parallel Test Lifecycle
+
+- Setup: per-thread registry is created, config is read
+- Execution: assertions are added to the thread-local registry
+- Teardown: `verify` and `reset` operate on the thread-local registry, reporters are notified
+- Exit: reporters finalize once per process (using mutex-protected snapshot)
+
+## Usage Examples
+
+```ruby
+parallelize(workers: :number_of_processors, with: :threads)
+
+Capybara::Screenshot::Diff.configure do |screenshot, diff|
+  screenshot.window_size = [1280, 1024]
+  screenshot.save_path = "doc/screenshots"
+  diff.tolerance = 0.001
+end
+```
+
+## Do and Do Not
+
+Do:
+- Set config once in test helper
+- Pass per-screenshot options in the call
+
+Do not:
+- Change global config inside tests
+- Manually mutate registry internals
+
+## File System Notes
+
+- Paths are unique per screenshot name and counter
+- `FileUtils.mv` is atomic on most file systems
+- Directory creation uses `mkpath`

data/gems.rb

@@ -15,7 +15,8 @@ gem "ruby-vips", require: false
 group :test do
   gem "capybara", ">= 3.26"
   gem "mutex_m" # Needed for RubyMine debugging.  Try removing it.
-  gem "minitest", require: false
+  gem "minitest", "< 6", require: false
+  gem "minitest-mock", require: false
   gem "minitest-stub-const", require: false
   gem "simplecov", require: false
   gem "rspec", require: false

data/lib/capybara/screenshot/diff/area_calculator.rb

@@ -48,7 +48,7 @@ module Capybara
         def build_regions_for(coordinates)
           coordinates
             .map { |entry| Region.from_edge_coordinates(*entry) }
-            .tap { |it| it.compact! }
+            .tap { |region| region.compact! }
         end
       end
     end

data/lib/capybara/screenshot/diff/browser_helpers.rb

@@ -60,6 +60,19 @@ module Capybara
         session.execute_script(HIDE_CARET_SCRIPT)
       end
 
+      DISABLE_ANIMATIONS_SCRIPT = <<~JS
+        if (!document.getElementById('csdDisableAnimationsStyle')) {
+          let style = document.createElement('style');
+          style.setAttribute('id', 'csdDisableAnimationsStyle');
+          style.textContent = '*, *::before, *::after { animation-duration: 0s !important; animation-delay: 0s !important; transition-duration: 0s !important; transition-delay: 0s !important; }';
+          document.head.appendChild(style);
+        }
+      JS
+
+      def self.disable_animations
+        session.execute_script(DISABLE_ANIMATIONS_SCRIPT)
+      end
+
       FIND_ACTIVE_ELEMENT_SCRIPT = <<~JS
         function activeElement(){
           const ae = document.activeElement; 
@@ -85,7 +98,7 @@ module Capybara
       JS
 
       def self.all_visible_regions_for(selector)
-        BrowserHelpers.session.all(selector, visible: true).map(&method(:region_for))
+        BrowserHelpers.session.all(selector, visible: true).map { |el| region_for(el) }
       end
 
       def self.region_for(element)

data/lib/capybara/screenshot/diff/comparison.rb

@@ -2,5 +2,8 @@
 
 module Capybara::Screenshot::Diff
   class Comparison < Struct.new(:new_image, :base_image, :options, :driver, :new_image_path, :base_image_path)
+    def skip_area
+      options[:skip_area]
+    end
   end
 end

data/lib/capybara/screenshot/diff/difference.rb

@@ -5,7 +5,31 @@ require "json"
 module Capybara
   module Screenshot
     module Diff
-      class Difference < Struct.new(:region, :meta, :comparison, :failed_by)
+      # Represents a difference between two images
+      #
+      # This value object encapsulates the result of an image comparison operation.
+      # It follows the Single Responsibility Principle by focusing solely on representing
+      # the difference state, including:
+      # - Whether images are different or equal
+      # - Why they differ (dimensions, pixels, etc.)
+      # - The specific region of difference
+      # - Whether differences are tolerable based on configured thresholds
+      #
+      # As part of the layered comparison architecture, this class represents the final
+      # output of the comparison process, containing all data needed for reporting.
+      # Represents a difference between two images
+      class Difference < Struct.new(:region, :meta, :comparison, :failed_by, :base_image_path, :image_path, keyword_init: nil)
+        def self.build_null(comparison, base_image_path, new_image_path, failed_by = nil)
+          Difference.new(
+            nil,
+            {difference_level: nil, max_color_distance: 0},
+            comparison,
+            failed_by,
+            base_image_path,
+            new_image_path
+          ).freeze
+        end
+
         def different?
           failed? || !(blank? || tolerable?)
         end
@@ -27,7 +51,7 @@ module Capybara
         end
 
         def skip_area
-          options[:skip_area]
+          comparison.skip_area
         end
 
         def area_size_limit
@@ -39,7 +63,7 @@ module Capybara
         end
 
         def region_area_size
-          region&.size || 0
+          @region_area_size ||= region&.size || 0
         end
 
         def ratio
@@ -61,6 +85,19 @@ module Capybara
         def tolerable?
           !!((area_size_limit && area_size_limit >= region_area_size) || (tolerance && tolerance >= ratio))
         end
+
+        # Path accessors for backward compatibility
+        def new_image_path
+          image_path || comparison&.new_image_path
+        end
+
+        def original_image_path
+          base_image_path || comparison&.base_image_path
+        end
+
+        def diff_mask
+          meta[:diff_mask]
+        end
       end
     end
   end

data/lib/capybara/screenshot/diff/difference_finder.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "capybara/screenshot/diff/comparison"
+require "capybara/screenshot/diff/difference"
+
+module Capybara
+  module Screenshot
+    module Diff
+      # Analyzes image differences with configurable tolerance levels.
+      #
+      # This class implements the core comparison logic for detecting visual differences
+      # between images while accounting for various tolerances and optimizations.
+      #
+      # The comparison process follows these steps:
+      # 1. Dimension Check (Fastest)
+      #    - Compares image dimensions first for quick rejection
+      #    - Different dimensions always indicate a difference
+      #
+      # 2. Pixel Equality Check (Fast)
+      #    - Performs bitwise comparison if dimensions match
+      #    - Returns immediately if images are exactly identical
+      #
+      # 3. Tolerant Comparison (Slower)
+      #    - Only runs if quick checks don't determine equality
+      #    - Respects configured tolerances for color and shift differences
+      #    - Can ignore specific regions (skip_area)
+      #    - Considers anti-aliasing and sub-pixel rendering differences
+      #
+      # The class is designed to be stateless and thread-safe, with all configuration
+      # passed in through the constructor.
+      class DifferenceFinder
+        TOLERABLE_OPTIONS = [:tolerance, :color_distance_limit, :shift_distance_limit, :area_size_limit].freeze
+
+        attr_reader :driver, :options
+
+        # Creates a new DifferenceFinder instance.
+        #
+        # @param driver [Drivers::Base] The image processing driver to use.
+        #   Must implement the driver interface expected by DifferenceFinder.
+        # @param options [Hash] Configuration options for the comparison:
+        #   @option options [Numeric] :tolerance (0.001) Color tolerance threshold (0.0-1.0).
+        #   @option options [Numeric] :color_distance_limit Maximum allowed color distance.
+        #   @option options [Numeric] :shift_distance_limit Maximum allowed shift distance.
+        #   @option options [Numeric] :area_size_limit Maximum allowed difference area size.
+        #   @option options [Array<Array>] :skip_area Regions to exclude from comparison.
+        def initialize(driver, options)
+          @driver = driver
+          @options = options
+          @without_tolerable_options = (options.keys & TOLERABLE_OPTIONS).empty?
+        end
+
+        # Analyzes the comparison and determines if images are different.
+        #
+        # @param comparison [Comparison] The comparison object containing images to analyze.
+        # @param quick_mode [Boolean] When true, performs minimal checks and returns early.
+        #   In quick mode, returns [is_equal, difference] where:
+        #   - is_equal is true if images are considered equal
+        #   - difference is a Difference object or nil
+        #   When false, returns a Difference object directly.
+        # @return [Array, Difference] Result format depends on quick_mode parameter.
+        # @raise [ArgumentError] If the comparison object is invalid.
+        def call(comparison, quick_mode: true)
+          # Process the comparison and return result
+
+          # Handle dimension differences
+          unless driver.same_dimension?(comparison)
+            result = Difference.build_null(comparison, comparison.base_image_path, comparison.new_image_path, {different_dimensions: true})
+            return quick_mode ? [false, result] : result
+          end
+
+          # Handle identical pixels
+          if driver.same_pixels?(comparison)
+            result = Difference.build_null(comparison, comparison.base_image_path, comparison.new_image_path)
+            return quick_mode ? [true, result] : result
+          end
+
+          # Handle early return for non-tolerable options
+          if quick_mode && without_tolerable_options?
+            return [false, nil]
+          end
+
+          # Process difference region
+          region = driver.find_difference_region(comparison)
+
+          # Only create a proper difference object if we've completed the comparison
+          quick_mode ? [!region.different?, region] : region
+        end
+
+        private
+
+        def without_tolerable_options?
+          @without_tolerable_options
+        end
+      end
+    end
+  end
+end

data/lib/capybara/screenshot/diff/drivers/base_driver.rb

@@ -30,6 +30,10 @@ module Capybara
           def dimension(image)
             [width_for(image), height_for(image)]
           end
+
+          def supports?(feature)
+            respond_to?(feature)
+          end
         end
       end
     end

data/lib/capybara/screenshot/diff/drivers/chunky_png_driver.rb

@@ -24,10 +24,6 @@ module Capybara
             _load_images(old_bytes, new_bytes)
           end
 
-          def filter_image_with_median(_image)
-            raise NotImplementedError
-          end
-
           def add_black_box(image, _region)
             image
           end
@@ -217,22 +213,24 @@ module Capybara
 
             def color_distance_at(new_img, old_img, x, y, shift_distance_limit:)
               org_color = old_img[x, y]
-              if shift_distance_limit
-                start_x = [0, x - shift_distance_limit].max
-                end_x = [x + shift_distance_limit, new_img.width - 1].min
-                xs = (start_x..end_x).to_a
-                start_y = [0, y - shift_distance_limit].max
-                end_y = [y + shift_distance_limit, new_img.height - 1].min
-                ys = (start_y..end_y).to_a
-                new_pixels = xs.product(ys)
-
-                distances = new_pixels.map do |dx, dy|
-                  ChunkyPNG::Color.euclidean_distance_rgba(org_color, new_img[dx, dy])
+              unless shift_distance_limit
+                return ChunkyPNG::Color.euclidean_distance_rgba(org_color, new_img[x, y])
+              end
+
+              start_x = [0, x - shift_distance_limit].max
+              end_x = [x + shift_distance_limit, new_img.width - 1].min
+              start_y = [0, y - shift_distance_limit].max
+              end_y = [y + shift_distance_limit, new_img.height - 1].min
+
+              min_distance = Float::INFINITY
+              (start_y..end_y).each do |dy|
+                (start_x..end_x).each do |dx|
+                  distance = ChunkyPNG::Color.euclidean_distance_rgba(org_color, new_img[dx, dy])
+                  return 0 if distance == 0
+                  min_distance = distance if distance < min_distance
                 end
-                distances.min
-              else
-                ChunkyPNG::Color.euclidean_distance_rgba(org_color, new_img[x, y])
               end
+              min_distance
             end
 
             def shift_distance_at(new_img, old_img, x, y, color_distance_limit:)
@@ -254,10 +252,10 @@ module Capybara
                   if (x - shift_distance) >= 0 # left
                     ([0, top_row + 1].max..[y + shift_distance, new_img.height - 2].min)
                       .each do |dy|
-                      if color_matches(new_img, org_color, x - shift_distance, dy, color_distance_limit)
-                        return shift_distance
+                        if color_matches(new_img, org_color, x - shift_distance, dy, color_distance_limit)
+                          return shift_distance
+                        end
                       end
-                    end
                   else
                     bounds_breached += 1
                   end
@@ -273,10 +271,10 @@ module Capybara
                   if (x + shift_distance) < new_img.width # right
                     ([0, top_row + 1].max..[y + shift_distance, new_img.height - 2].min)
                       .each do |dy|
-                      if color_matches(new_img, org_color, x + shift_distance, dy, color_distance_limit)
-                        return shift_distance
+                        if color_matches(new_img, org_color, x + shift_distance, dy, color_distance_limit)
+                          return shift_distance
+                        end
                       end
-                    end
                   else
                     bounds_breached += 1
                   end

data/lib/capybara/screenshot/diff/drivers/vips_driver.rb

@@ -15,15 +15,18 @@ module Capybara
       # Compare two images and determine if they are equal, different, or within some comparison
       # range considering color values and difference area size.
       module Drivers
-        DEFAULT_HIGHLIGHT_COLOR = [255, 0, 0, 255].freeze
-
         class VipsDriver < BaseDriver
           def find_difference_region(comparison)
             new_image, base_image, options = comparison.new_image, comparison.base_image, comparison.options
 
-            diff_mask = VipsUtil.difference_mask(base_image, new_image, options[:color_distance_limit])
-            region = VipsUtil.difference_region_by(diff_mask)
-            region = nil if region && same_as?(region, base_image)
+            diff_mask = if options[:perceptual_threshold]
+              self.class.perceptual_difference_mask(base_image, new_image, options[:perceptual_threshold])
+            else
+              self.class.difference_mask(base_image, new_image, options[:color_distance_limit])
+            end
+            region = self.class.difference_region_by(diff_mask)
+            # TODO: schedule research when we got this case for VIPs
+            # region = nil if region && region_covers_entire_image?(region, base_image)
 
             result = Difference.new(region, {}, comparison)
 
@@ -40,7 +43,7 @@ module Capybara
           rescue Vips::Error => e
             warn(
               "[capybara-screenshot-diff] Crop has been failed for " \
-              "{ region: #{region.to_top_left_corner_coordinates.inspect}, image: #{dimension(i).join("x")} }"
+                "{ region: #{region.to_top_left_corner_coordinates.inspect}, image: #{dimension(i).join("x")} }"
             )
             raise e
           end
@@ -56,7 +59,7 @@ module Capybara
           end
 
           def difference_level(diff_mask, old_img, _region = nil)
-            VipsUtil.difference_area_size_by(diff_mask).to_f / image_area_size(old_img)
+            self.class.difference_area_size_by(diff_mask).to_f / image_area_size(old_img)
           end
 
           MAX_FILENAME_LENGTH = 200
@@ -89,10 +92,6 @@ module Capybara
             result
           end
 
-          def dimension(image)
-            [width_for(image), height_for(image)]
-          end
-
           def draw_rectangles(images, region, rgba, offset: 0)
             images.map do |image|
               image.draw_rect(rgba, region.left - offset, region.top - offset, region.width + (offset * 2), region.height + (offset * 2))
@@ -107,37 +106,51 @@ module Capybara
             base_image.composite2(new_image, :over)
           end
 
-          def highlight_mask(diff_mask, merged_image, color: DEFAULT_HIGHLIGHT_COLOR)
+          def highlight_mask(diff_mask, merged_image, color: CapybaraScreenshotDiff::RED_RGBA)
             diff_mask.ifthenelse(color, merged_image * 0.75)
           end
 
           private
 
-          def same_as?(region, base_image)
-            region.x.zero? &&
-              region.y.zero? &&
-              region.height == height_for(base_image) &&
-              region.width == width_for(base_image)
-          end
-
-          class VipsUtil
-            def self.difference_area(old_image, new_image, color_distance: 0)
-              difference_mask = difference_mask(new_image, old_image, color_distance)
-              difference_area_size_by(difference_mask)
+          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 self.difference_area_size_by(difference_mask)
+            def difference_area_size_by(difference_mask)
               diff_mask = difference_mask == 0
               diff_mask.hist_find.to_a[0][0].max
             end
 
-            def self.difference_mask(base_image, new_image, color_distance = nil)
+            def difference_mask(base_image, new_image, color_distance = nil)
               result = (new_image - base_image).abs
-
               color_distance ? result > color_distance : result
             end
 
-            def self.difference_region_by(diff_mask)
+            def perceptual_difference_mask(base_image, new_image, threshold = 2.0)
+              color_diff = perceptual_color_diff(base_image, new_image) > threshold
+              alpha_diff = alpha_channel_diff(base_image, new_image)
+              alpha_diff ? (color_diff | alpha_diff) : color_diff
+            end
+
+            def perceptual_color_diff(base_image, new_image)
+              base_rgb = (base_image.bands > 3) ? base_image.extract_band(0, n: 3) : base_image
+              new_rgb = (new_image.bands > 3) ? new_image.extract_band(0, n: 3) : new_image
+              base_lab = base_rgb.colourspace(:lab)
+              new_lab = new_rgb.colourspace(:lab)
+              base_lab.dE00(new_lab)
+            rescue Vips::Error
+              base_lab.dE76(new_lab)
+            end
+
+            def alpha_channel_diff(base_image, new_image)
+              return unless base_image.bands > 3 && new_image.bands > 3
+
+              (base_image.extract_band(3) - new_image.extract_band(3)).abs > 0
+            end
+
+            def difference_region_by(diff_mask)
               columns, rows = diff_mask.bandor.project
 
               left = columns.profile[1].min