capybara-screenshot-diff 1.10.3.1 → 1.13.0

data/lib/capybara_screenshot_diff/screenshot_assertion.rb

@@ -7,21 +7,9 @@ module CapybaraScreenshotDiff
     attr_reader :name, :args
     attr_accessor :compare, :caller
 
-    def initialize(name, **args, &block)
+    def initialize(name, **args)
       @name = name
       @args = args
-
-      yield(self) if block_given?
-    end
-
-    def self.from(screenshot_job)
-      return screenshot_job if screenshot_job.is_a?(ScreenshotAssertion)
-
-      caller, name, compare = screenshot_job
-      ScreenshotAssertion.new(name).tap do |it|
-        it.caller = caller
-        it.compare = compare
-      end
     end
 
     def validate
@@ -30,6 +18,14 @@ module CapybaraScreenshotDiff
       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.
@@ -45,8 +41,6 @@ module CapybaraScreenshotDiff
       test_screenshot_errors.compact!
 
       test_screenshot_errors.empty? ? nil : test_screenshot_errors
-    ensure
-      screenshots&.clear
     end
 
     # Asserts that an image has not changed compared to its baseline.
@@ -62,8 +56,6 @@ module CapybaraScreenshotDiff
       # Cleanup after comparisons
       if !result && comparison.base_image_path.exist?
         FileUtils.mv(comparison.base_image_path, comparison.image_path, force: true)
-      elsif !comparison.dimensions_changed?
-        FileUtils.rm_rf(comparison.base_image_path)
       end
 
       return unless result
@@ -73,15 +65,16 @@ module CapybaraScreenshotDiff
   end
 
   class AssertionRegistry
-    attr_reader :assertions
+    attr_reader :assertions, :screenshot_namer, :new_screenshots
 
     def initialize
       @assertions = []
+      @new_screenshots = []
+      @screenshot_namer = CapybaraScreenshotDiff::ScreenshotNamer.new
     end
 
     def add_assertion(assertion)
-      assertion = ScreenshotAssertion.from(assertion)
-      return unless assertion.compare
+      return unless assertion&.compare
 
       @assertions.push(assertion)
 
@@ -92,10 +85,24 @@ module CapybaraScreenshotDiff
       !@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)
 
-      raise CapybaraScreenshotDiff::ExpectationNotMet, result.join("\n\n") if result
+      if result
+        raise CapybaraScreenshotDiff::ExpectationNotMet.new(result.join("\n\n"), failed_screenshot.caller)
+      end
     end
 
     def failed_assertions
@@ -104,6 +111,8 @@ module CapybaraScreenshotDiff
 
     def reset
       @assertions.clear
+      @new_screenshots.clear
+      @screenshot_namer = CapybaraScreenshotDiff::ScreenshotNamer.new
     end
   end
 end
@@ -121,7 +130,49 @@ module CapybaraScreenshotDiff
     def_delegator :registry, :assertions
     def_delegator :registry, :assertions_present?
     def_delegator :registry, :failed_assertions
-    def_delegator :registry, :reset
+    def_delegator :registry, :record_new_screenshot
+    def_delegator :registry, :new_screenshots
+    def_delegator :registry, :new_screenshots_present?
+    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
+
+    private
+
+    def notify_reporters(assertions)
+      return if assertions.nil? || assertions.empty?
+
+      reporters_snapshot = reporters_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
+
+  @reporters_mutex = Mutex.new
 end

data/lib/capybara_screenshot_diff/screenshot_namer.rb

@@ -0,0 +1,81 @@
+# 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

data/lib/capybara_screenshot_diff/snap.rb

@@ -16,7 +16,8 @@ module CapybaraScreenshotDiff
     def delete!
       path.delete if path.exist?
       base_path.delete if base_path.exist?
-      cleanup_attempts
+      cleanup_diff_artifacts!
+      cleanup_attempts!
     end
 
     def checkout_base_screenshot
@@ -43,13 +44,23 @@ module CapybaraScreenshotDiff
       @manager.move(attempt_path, path)
     end
 
-    def cleanup_attempts
+    def cleanup_attempts!
       @manager.cleanup_attempts!(self)
       @attempts_count = 0
     end
 
     def find_attempts_paths
-      Dir[@manager.abs_path_for "**/#{full_name}.attempt_*.#{format}"]
+      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

data/lib/capybara_screenshot_diff/snap_manager.rb

@@ -11,10 +11,13 @@ module CapybaraScreenshotDiff
 
     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)
+      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")
@@ -42,7 +45,10 @@ module CapybaraScreenshotDiff
 
     # TODO: rename to delete!
     def cleanup!
-      FileUtils.rm_rf root, secure: true
+      snapshots.each do |snapshot|
+        cleanup_attempts!(snapshot)
+        snapshot.delete!
+      end
     end
 
     def self.cleanup!
@@ -61,6 +67,8 @@ module CapybaraScreenshotDiff
       root.children.map { |f| f.basename.to_s }
     end
 
+    attr_reader :snapshots
+
     def self.screenshots
       instance.screenshots
     end

data/lib/capybara_screenshot_diff/static.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rack/files"
+require "capybara_screenshot_diff/minitest"
+
+module CapybaraScreenshotDiff
+  def self.serve(directory, root: Dir.pwd)
+    Capybara.app = Rack::Files.new(directory)
+    Capybara::Screenshot.root = root
+  end
+end

data/lib/capybara_screenshot_diff.rb

@@ -5,25 +5,32 @@ require "capybara/screenshot/diff/version"
 require "capybara/screenshot/diff/utils"
 require "capybara/screenshot/diff/image_compare"
 require "capybara_screenshot_diff/snap_manager"
-require "capybara/screenshot/diff/test_methods"
 require "capybara/screenshot/diff/screenshoter"
 require "capybara/screenshot/diff/reporters/default"
 
+require "capybara_screenshot_diff/error_with_filtered_backtrace"
+
 module CapybaraScreenshotDiff
-  class CapybaraScreenshotDiffError < StandardError; end
+  RED_RGBA = [255, 0, 0, 255].freeze
+  ORANGE_RGBA = [255, 192, 0, 255].freeze
+
+  class CapybaraScreenshotDiffError < ErrorWithFilteredBacktrace; end
 
   class ExpectationNotMet < CapybaraScreenshotDiffError; end
 
   class UnstableImage < CapybaraScreenshotDiffError; end
+
+  class WindowSizeMismatchError < ErrorWithFilteredBacktrace; end
 end
 
 module Capybara
   module Screenshot
     mattr_accessor :add_driver_path
     mattr_accessor :add_os_path
-    mattr_accessor :blur_active_element
+    mattr_accessor(:blur_active_element) { true }
     mattr_accessor :enabled
-    mattr_accessor :hide_caret
+    mattr_accessor(:hide_caret) { true }
+    mattr_accessor :disable_animations
     mattr_reader(:root) { (defined?(Rails) && defined?(Rails.root) && Rails.root) || Pathname(".").expand_path }
     mattr_accessor :stability_time_limit
     mattr_accessor :window_size
@@ -57,7 +64,8 @@ module Capybara
     module Diff
       mattr_accessor(:delayed) { true }
       mattr_accessor :area_size_limit
-      mattr_accessor(:fail_if_new) { false }
+      mattr_accessor(:fail_if_new) { !ENV["CI"].nil? && !ENV["CI"].empty? }
+      mattr_accessor(:pending_if_new) { false }
       mattr_accessor(:fail_on_difference) { true }
       mattr_accessor :color_distance_limit
       mattr_accessor(:enabled) { true }
@@ -65,12 +73,29 @@ module Capybara
       mattr_accessor :skip_area
       mattr_accessor(:driver) { :auto }
       mattr_accessor :tolerance
+      mattr_accessor :perceptual_threshold
 
       mattr_accessor(:screenshoter) { Screenshoter }
       mattr_accessor(:manager) { CapybaraScreenshotDiff::SnapManager }
 
       AVAILABLE_DRIVERS = Utils.detect_available_drivers.freeze
 
+      # Configure screenshot and diff settings in one block.
+      #
+      #   Capybara::Screenshot::Diff.configure do |screenshot, diff|
+      #     screenshot.window_size = [1280, 1024]
+      #     screenshot.stability_time_limit = 1
+      #     diff.driver = :vips
+      #     diff.tolerance = 0.0005
+      #   end
+      def self.configure
+        yield Screenshot, self
+      end
+
+      def self.compare(baseline_path, current_path, **options)
+        ImageCompare.new(current_path, baseline_path, default_options.merge(options))
+      end
+
       def self.default_options
         {
           area_size_limit: area_size_limit,
@@ -78,6 +103,7 @@ module Capybara
           driver: driver,
           screenshot_format: Screenshot.screenshot_format,
           capybara_screenshot_options: Screenshot.capybara_screenshot_options,
+          perceptual_threshold: perceptual_threshold,
           shift_distance_limit: shift_distance_limit,
           skip_area: skip_area,
           stability_time_limit: Screenshot.stability_time_limit,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capybara-screenshot-diff
 version: !ruby/object:Gem::Version
-  version: 1.10.3.1
+  version: 1.13.0
 platform: ruby
 authors:
 - Uwe Kubosch
@@ -15,17 +15,37 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
-  type: :runtime
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
@@ -56,9 +76,25 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
 - LICENSE.txt
 - Rakefile
 - capybara-screenshot-diff.gemspec
+- docs/RELEASE_PREP.md
+- docs/UPGRADING.md
+- docs/architecture.md
+- docs/ci-integration.md
+- docs/configuration.md
+- docs/docker-testing.md
+- docs/drivers.md
+- docs/framework-setup.md
+- docs/images/snap_diff_annotated.png
+- docs/images/snap_diff_web_ui.png
+- docs/migration-guide.md
+- docs/organization.md
+- docs/reporters.md
+- docs/thread_safety.md
 - gems.rb
 - lib/capybara-screenshot-diff.rb
 - lib/capybara/screenshot/diff.rb
@@ -67,31 +103,38 @@ files:
 - lib/capybara/screenshot/diff/comparison.rb
 - lib/capybara/screenshot/diff/cucumber.rb
 - lib/capybara/screenshot/diff/difference.rb
+- lib/capybara/screenshot/diff/difference_finder.rb
 - lib/capybara/screenshot/diff/drivers.rb
 - lib/capybara/screenshot/diff/drivers/base_driver.rb
 - lib/capybara/screenshot/diff/drivers/chunky_png_driver.rb
 - lib/capybara/screenshot/diff/drivers/vips_driver.rb
 - lib/capybara/screenshot/diff/image_compare.rb
+- lib/capybara/screenshot/diff/image_preprocessor.rb
 - lib/capybara/screenshot/diff/os.rb
 - lib/capybara/screenshot/diff/region.rb
 - lib/capybara/screenshot/diff/reporters/default.rb
 - lib/capybara/screenshot/diff/screenshot_matcher.rb
 - lib/capybara/screenshot/diff/screenshoter.rb
 - lib/capybara/screenshot/diff/stable_screenshoter.rb
-- lib/capybara/screenshot/diff/test_methods.rb
 - lib/capybara/screenshot/diff/utils.rb
 - lib/capybara/screenshot/diff/vcs.rb
 - lib/capybara/screenshot/diff/version.rb
 - lib/capybara_screenshot_diff.rb
 - lib/capybara_screenshot_diff/attempts_reporter.rb
+- lib/capybara_screenshot_diff/backtrace_filter.rb
 - lib/capybara_screenshot_diff/cucumber.rb
 - lib/capybara_screenshot_diff/dsl.rb
+- lib/capybara_screenshot_diff/error_with_filtered_backtrace.rb
 - lib/capybara_screenshot_diff/minitest.rb
+- lib/capybara_screenshot_diff/reporters/html.rb
+- lib/capybara_screenshot_diff/reporters/templates/report.html.erb
 - lib/capybara_screenshot_diff/rspec.rb
 - lib/capybara_screenshot_diff/screenshot_assertion.rb
+- lib/capybara_screenshot_diff/screenshot_namer.rb
 - lib/capybara_screenshot_diff/snap.rb
 - lib/capybara_screenshot_diff/snap_manager.rb
-homepage: https://github.com/donv/capybara-screenshot-diff
+- lib/capybara_screenshot_diff/static.rb
+homepage: https://github.com/snap-diff/snap_diff-capybara
 licenses:
 - MIT
 metadata:
@@ -103,14 +146,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Track your GUI changes with diff assertions
 test_files: []

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

@@ -1,157 +0,0 @@
-# frozen_string_literal: true
-
-require "English"
-require "capybara"
-require "action_controller"
-require "action_dispatch"
-require "active_support/core_ext/string/strip"
-require "pathname"
-
-require_relative "drivers"
-require_relative "image_compare"
-require_relative "vcs"
-require_relative "browser_helpers"
-require_relative "region"
-
-require_relative "screenshot_matcher"
-
-# == Capybara::Screenshot::Diff::TestMethods
-#
-# This module provides methods for capturing screenshots and verifying them against
-# baseline images to detect visual changes. It's designed to be included in test
-# classes to add visual regression testing capabilities.
-
-module Capybara
-  module Screenshot
-    module Diff
-      module TestMethods
-        # @!attribute [rw] test_screenshots
-        #   @return [Array(Array(Array(String), String, ImageCompare | Minitest::Mock))] An array where each element is an array containing the caller context,
-        #     the name of the screenshot, and the comparison object. This attribute stores information about each screenshot
-        #     scheduled for comparison to ensure they do not show any unintended differences.
-        def initialize(*)
-          super
-          @screenshot_counter = nil
-          @screenshot_group = nil
-          @screenshot_section = nil
-          @test_screenshot_errors = nil
-        end
-
-        # Builds the full name for a screenshot, incorporating counters and group names for uniqueness.
-        #
-        # @param name [String] The base name for the screenshot.
-        # @return [String] The full, unique name for the screenshot.
-        def build_full_name(name)
-          if @screenshot_counter
-            name = format("%02i_#{name}", @screenshot_counter)
-            @screenshot_counter += 1
-          end
-
-          File.join(*group_parts.push(name.to_s))
-        end
-
-        # Determines the directory path for saving screenshots.
-        #
-        # @return [String] The full path to the directory where screenshots are saved.
-        def screenshot_dir
-          File.join(*([Screenshot.screenshot_area] + group_parts))
-        end
-
-        def screenshot_section(name)
-          @screenshot_section = name.to_s
-        end
-
-        def screenshot_group(name)
-          @screenshot_group = name.to_s
-          @screenshot_counter = (@screenshot_group.nil? || @screenshot_group.empty?) ? nil : 0
-          name_present = !(name.nil? || name.empty?)
-          return unless Screenshot.active? && name_present
-
-          FileUtils.rm_rf screenshot_dir
-        end
-
-        # Schedules a screenshot comparison job for later execution.
-        #
-        # This method adds a job to the queue of screenshots to be matched. It's used when `Capybara::Screenshot::Diff.delayed`
-        # is set to true, allowing for batch processing of screenshot comparisons at a later point, typically at the end of a test.
-        #
-        # @param job [Array(Array(String), String, ImageCompare)] The job to be scheduled, consisting of the caller context, screenshot name, and comparison object.
-        # @return [Boolean] Always returns true, indicating the job was successfully scheduled.
-        def schedule_match_job(job)
-          CapybaraScreenshotDiff.add_assertion(job)
-          true
-        end
-
-        def group_parts
-          parts = []
-          parts << @screenshot_section unless @screenshot_section.nil? || @screenshot_section.empty?
-          parts << @screenshot_group unless @screenshot_group.nil? || @screenshot_group.empty?
-          parts
-        end
-
-        # Takes a screenshot and optionally compares it against a baseline image.
-        #
-        # @param name [String] The name of the screenshot, used to generate the filename.
-        # @param skip_stack_frames [Integer] The number of stack frames to skip when reporting errors, for cleaner error messages.
-        # @param options [Hash] Additional options for taking the screenshot, such as custom dimensions or selectors.
-        # @return [Boolean] Returns true if the screenshot was successfully captured and matches the baseline, false otherwise.
-        # @raise [CapybaraScreenshotDiff::ExpectationNotMet] If the screenshot does not match the baseline image and fail_if_new is set to true.
-        # @example Capture a full-page screenshot named 'login_page'
-        #   screenshot('login_page', skip_stack_frames: 1, full: true)
-        def screenshot(name, skip_stack_frames: 0, **options)
-          return false unless Screenshot.active?
-
-          # setup
-          screenshot_full_name = build_full_name(name)
-
-          # exercise
-          match_changes_job = build_screenshot_matches_job(screenshot_full_name, options)
-
-          # verify
-          backtrace = caller(skip_stack_frames + 1).reject { |l| l =~ /gems\/(activesupport|minitest|railties)/ }
-
-          unless match_changes_job
-            if Screenshot::Diff.fail_if_new
-              _raise_error(<<-ERROR.strip_heredoc, backtrace)
-                No existing screenshot found for #{screenshot_full_name}!
-                To stop seeing this error disable by `Capybara::Screenshot::Diff.fail_if_new=false`
-              ERROR
-            end
-
-            return false
-          end
-
-          match_changes_job.prepend(backtrace)
-
-          if Screenshot::Diff.delayed
-            schedule_match_job(match_changes_job)
-          else
-            invoke_match_job(match_changes_job)
-          end
-        end
-
-        private
-
-        def invoke_match_job(job)
-          error_msg = CapybaraScreenshotDiff::ScreenshotAssertion.from(job).validate
-
-          if error_msg
-            _raise_error(error_msg, job[0])
-          end
-
-          true
-        end
-
-        def _raise_error(error_msg, backtrace)
-          raise CapybaraScreenshotDiff::ExpectationNotMet.new(error_msg).tap { _1.set_backtrace(backtrace) }
-        end
-
-        def build_screenshot_matches_job(screenshot_full_name, options)
-          ScreenshotMatcher
-            .new(screenshot_full_name, options)
-            .build_screenshot_matches_job
-        end
-      end
-    end
-  end
-end