capybara-screenshot-diff 1.10.3 → 1.12.0

data/docs/drivers.md

@@ -0,0 +1,102 @@
+# Image Processing Drivers
+
+## Perceptual color comparison (VIPS only)
+
+By default, color differences are measured using raw RGB channel distance. This can produce
+false positives from anti-aliasing and sub-pixel font rendering — the same page rendered on
+different OS versions or browsers will have slightly different pixel values at text edges.
+
+The `perceptual_threshold` option uses the CIE dE00 formula instead, which measures color
+difference the way human eyes perceive it. Anti-aliasing artifacts typically score below 2.0
+on the dE00 scale and are automatically ignored.
+
+```ruby
+# Per-screenshot: ignore anti-aliasing, catch real visual changes
+screenshot 'dashboard', perceptual_threshold: 2.0
+
+# Global: apply to all screenshots
+Capybara::Screenshot::Diff.perceptual_threshold = 2.0
+
+# dE00 scale reference:
+#   < 1.0  — not perceptible by human eyes
+#   1-2    — perceptible through close observation (anti-aliasing, font hinting)
+#   2-10   — perceptible at a glance (color shifts, layout changes)
+#   > 10   — clearly different colors
+```
+
+Use `perceptual_threshold` when you see false positives from font rendering differences across
+CI environments, or when `color_distance_limit` with raw RGB requires frequent tuning.
+
+**⚠️ Important:** `perceptual_threshold` and `color_distance_limit` are **mutually exclusive**.
+If you set both, `perceptual_threshold` takes priority and `color_distance_limit` is silently ignored.
+
+These options use different scales and algorithms:
+- `perceptual_threshold` → CIE dE00 perceptual distance (0-100+)
+- `color_distance_limit` → Euclidean RGBA distance (0-510)
+
+**Choose one based on your driver setup:**
+- VIPS with `ruby-vips` gem → prefer `perceptual_threshold`
+- ChunkyPNG (no native dependencies) → use `color_distance_limit`
+
+## Available Image Processing Drivers
+
+There are several image processing supported by this gem.
+There are several options to setup active driver: `:auto`, `:chunky_png` and `:vips`.
+
+* `:auto` - will try to load `:vips` if there is gem `ruby-vips`, in other cases will load `:chunky_png`
+* `:chunky_png` and `:vips` will load correspondent driver
+
+## Enable VIPS image processing
+
+[Vips](https://www.rubydoc.info/gems/ruby-vips/Vips/Image) driver provides a faster comparison,
+and could be enabled by adding `ruby-vips` to `Gemfile`.
+
+If need to setup explicitly Vips driver, there are several ways to do this:
+
+* Globally: `Capybara::Screenshot::Diff.driver = :vips`
+* Per screenshot option: `screenshot 'index', driver: :vips`
+
+With enabled VIPS there are new alternatives to process differences, which are easier to find and support.
+For example, `shift_distance_limit` is a very heavy operation. Instead, use `median_filter_window_size`.
+
+## Tolerance level (vips only)
+
+You can set a "tolerance" anywhere from 0% to 100%. This is the amount of change that's allowable.
+If the screenshot has changed by more than that amount, it'll flag it as a failure.
+
+This is alternative to "Allowed difference size", only the difference that area calculates including valid pixels.
+But "tolerance" compares only different pixels.
+
+You can use the `tolerance` option to the `screenshot` method to set level:
+
+```ruby
+test 'unstable area' do
+  visit '/'
+  # tolerance: 0.01 allows 1% of pixels to differ (use for noisy pages)
+  screenshot 'index', tolerance: 0.01
+end
+```
+
+You can also set this globally:
+
+```ruby
+# Default for VIPS is 0.001 (0.1% pixel difference allowed)
+Capybara::Screenshot::Diff.tolerance = 0.001
+```
+
+## Median filter size (vips only)
+
+This is an alternative to "Allowed shift distance", but much faster.
+You can find more about this strategy on [Median Filter](https://en.wikipedia.org/wiki/Median_filter).
+Think about this like smoothing of the image, before comparison.
+
+You can use the `median_filter_window_size` option to the `screenshot` method to set level:
+
+```ruby
+test 'unstable area' do
+  visit '/'
+  screenshot 'index', median_filter_window_size: 2
+end
+```
+
+[← Back to README](../README.md)

data/docs/framework-setup.md

@@ -0,0 +1,87 @@
+# Framework Setup
+
+## Including DSL
+
+To use the screenshot capturing and change detection features in your tests, include the `CapybaraScreenshotDiff::DSL` in your test classes. It provides the `screenshot` method to capture and compare screenshots.
+
+There are different modules for different testing frameworks integrations.
+
+## Minitest
+
+For Minitest, need to require `capybara_screenshot_diff/minitest`.
+In your test class, include the `CapybaraScreenshotDiff::Minitest::Assertions` module:
+
+```ruby
+require 'capybara_screenshot_diff/minitest'
+
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  # Make the Capybara & Capybara Screenshot Diff DSLs available in tests
+  include CapybaraScreenshotDiff::DSL
+  # Make `assert_*` methods behave like Minitest assertions
+  include CapybaraScreenshotDiff::Minitest::Assertions
+
+  def test_my_feature
+    visit '/'
+    assert_matches_screenshot 'index'
+  end
+end
+```
+
+## RSpec
+
+To use the screenshot capturing and change detection features in your tests,
+include the `CapybaraScreenshotDiff::DSL` in your test classes.
+It adds `match_screenshot` matcher to RSpec.
+
+> **Important**:
+> The `CapybaraScreenshotDiff::DSL` is automatically included in all feature and system tests by default.
+
+
+```ruby
+require 'capybara_screenshot_diff/rspec'
+
+describe 'Permissions admin', type: :feature do
+  it 'works with permissions' do
+    visit('/')
+    expect(page).to match_screenshot('home_page')
+  end
+end
+
+
+describe 'Permissions admin', type: :non_feature do
+  include CapybaraScreenshotDiff::DSL
+
+  it 'works with permissions' do
+    visit('/')
+    expect(page).to match_screenshot('home_page')
+  end
+end
+```
+
+## Cucumber
+
+Load Cucumber support by adding the following line (typically to your `features/support/env.rb` file):
+
+```ruby
+require 'capybara_screenshot_diff/cucumber'
+```
+
+And in the steps you can use:
+
+```ruby
+Then('I should not see any visual difference') do
+  screenshot 'homepage'
+end
+```
+
+## Custom Test Frameworks
+
+Minitest, RSpec, and Cucumber are supported out of the box. For other frameworks, call `finalize_reporters!` in your framework's "after suite" hook:
+
+```ruby
+CapybaraScreenshotDiff.finalize_reporters!
+```
+
+This generates the HTML report and prints the summary.
+
+[← Back to README](../README.md)

data/docs/organization.md

@@ -0,0 +1,226 @@
+# Screenshot Organization
+
+## Taking screenshots
+
+Add `screenshot '<my_feature>'` to your tests.  The screenshot will be saved in
+the `doc/screenshots` directory.
+
+Change your existing `save_screenshot` calls to `screenshot`
+
+```ruby
+test 'my useful feature' do
+  visit '/'
+  screenshot 'welcome_index'
+  click_button 'Useful feature'
+  screenshot 'feature_index'
+  click_button 'Perform action'
+  screenshot 'action_performed'
+end
+```
+
+This will produce a sequence of images like this
+
+```
+doc
+  screenshots
+    action_performed
+    feature_index
+    welcome_index
+```
+
+To store the screenshot history, add the `doc/screenshots` directory to your
+version control system (git).
+
+Screenshots are compared to the previously COMMITTED version of the same screenshot.
+
+### Generated artifacts (do not commit)
+
+When a screenshot differs, the gem generates temporary diff files alongside the baseline:
+
+| Pattern | Description |
+|---------|-------------|
+| `*.base.png` | VCS checkout of the committed baseline |
+| `*.diff.png` | Annotated diff with changes highlighted |
+| `*.base.diff.png` | Annotated baseline with diff region marked |
+| `*.heatmap.diff.png` | Heatmap of pixel differences |
+| `snap_diff_report.html` | Interactive Web UI report |
+
+Add these to `.gitignore`:
+
+```gitignore
+*.diff.png
+*.base.png
+*.diff.webp
+*.base.webp
+snap_diff_report.html
+```
+
+Clean up artifacts with `rake snap_diff:clean`.
+
+## Screenshot groups
+
+Commonly it is useful to group screenshots around a feature, and record them as
+a sequence.  To do this, add a `screenshot_group` call to the start of your
+test.
+
+```ruby
+test 'my useful feature' do
+  screenshot_group 'useful_feature'
+  visit '/'
+  screenshot 'welcome_index'
+  click_button 'Useful feature'
+  screenshot 'feature_index'
+  click_button 'Perform action'
+  screenshot 'action_performed'
+end
+```
+
+This will produce a sequence of images like this
+
+```
+doc
+  screenshots
+    useful_feature
+      00_welcome_index
+      01_feature_index
+      02_action_performed
+```
+
+**Note:** `screenshot_group` sets the group name for organizing screenshots. It does not delete existing files.
+
+
+## Screenshot sections
+
+You can introduce another level above the screenshot group called a
+`screenshot_section`.  The section name is inserted just before the group name
+in the save path.  If called in the setup of the test, all screenshots in
+that test will get the same prefix:
+
+```ruby
+setup do
+  screenshot_section 'my_feature'
+end
+
+test 'my subfeature' do
+  screenshot_group 'subfeature'
+  visit '/feature'
+  click_button 'Interesting button'
+  screenshot 'subfeature_index'
+  click_button 'Perform action'
+  screenshot 'action_performed'
+end
+```
+
+This will produce a sequence of images like this
+
+```
+doc
+  screenshots
+    my_feature
+      subfeature
+        00_subfeature_index
+        01_action_performed
+```
+
+
+## Setting `screenshot_section` and/or `screenshot_group` for all tests
+
+Setting the `screenshot_section` and/or `screenshot_group` for all tests can be
+done in the super class setup:
+
+```ruby
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  setup do
+    screenshot_section class_name.underscore.sub(/(_feature|_system)?_test$/, '')
+    screenshot_group name[5..-1]
+  end
+end
+```
+
+`screenshot_section` and/or `screenshot_group` can still be overridden in each
+test.
+
+
+## Capturing one area instead of the whole page
+
+You can crop images before comparison to be run, by providing region to crop as `[left, top, right, bottom]` or by css selector like `body .tag`
+
+```ruby
+test 'the cool' do
+  visit '/feature'
+  screenshot 'cool_element', crop: '#my_element'
+end
+```
+
+**Note:** When using a retina device screenshots dimensions might be off. If
+you are using (headless) chrome you can prevent this by setting the
+`force-device-scale-factor` argument to `1`.
+
+For Rails system specs using selenium you can do so for example by using the
+following snippet:
+
+```ruby
+driven_by :selenium, using: :chrome_headless do |options|
+  options.args << '--force-device-scale-factor=1'
+end
+```
+
+## Multiple Capybara drivers
+
+Often it is useful to test your app using different browsers.  To avoid the
+screenshots for different Capybara drivers to overwrite each other, set
+
+```ruby
+Capybara::Screenshot.add_driver_path = true
+```
+
+The example above will then save your screenshots like this
+(for poltergeist and selenium):
+
+```
+doc
+  screenshots
+    poltergeist
+      useful_feature
+        00_welcome_index
+        01_feature_index
+        02_action_performed
+    selenium
+      useful_feature
+        00_welcome_index
+        01_feature_index
+        02_action_performed
+```
+
+## Multiple OSs
+
+If you run your tests on multiple operating systems, you will most likely find
+the screen shots differ.  To avoid the screenshots for different OSs to
+overwrite each other, set
+
+```ruby
+Capybara::Screenshot.add_os_path = true
+```
+
+The example above will then save your screenshots like this
+(for Linux and Windows):
+
+```
+doc
+  screenshots
+    linux
+      useful_feature
+        00_welcome_index
+        01_feature_index
+        02_action_performed
+    windows
+      useful_feature
+        00_welcome_index
+        01_feature_index
+        02_action_performed
+```
+
+If you combine this config with the `add_driver_path` config, the driver will be
+put in front of the OS name.
+
+[← Back to README](../README.md)

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