capybara-screenshot-diff 1.8.3 → 1.9.2

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

@@ -15,11 +15,20 @@ require_relative "region"
 
 require_relative "screenshot_matcher"
 
-# Add the `screenshot` method to ActionDispatch::IntegrationTest
+# == 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
@@ -29,6 +38,29 @@ module Capybara
           @test_screenshots = []
         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 verify_screenshots!(screenshots = @test_screenshots)
+          return unless ::Capybara::Screenshot.active? && ::Capybara::Screenshot::Diff.fail_on_difference
+
+          test_screenshot_errors = screenshots.map do |caller, name, compare|
+            assert_image_not_changed(caller, name, compare)
+          end
+
+          test_screenshot_errors.compact!
+
+          test_screenshot_errors.presence
+        ensure
+          screenshots.clear
+        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)
@@ -38,6 +70,9 @@ module Capybara
           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
@@ -54,6 +89,13 @@ module Capybara
           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)
           (@test_screenshots ||= []) << job
           true
@@ -66,28 +108,49 @@ module Capybara
           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?
 
           screenshot_full_name = build_full_name(name)
           job = build_screenshot_matches_job(screenshot_full_name, options)
 
-          return false unless job
+          unless job
+            if Screenshot::Diff.fail_if_new
+              raise_error(<<-ERROR.strip_heredoc, caller(2))
+                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
 
-          job.prepend(caller[skip_stack_frames])
+          job.prepend(caller(skip_stack_frames))
 
           if Screenshot::Diff.delayed
             schedule_match_job(job)
           else
             error_msg = assert_image_not_changed(*job)
-            if error_msg
-              error = ASSERTION.new(error_msg)
-              error.set_backtrace(caller(2))
-              raise error
-            end
+            raise_error(error_msg, caller(2)) if error_msg
           end
         end
 
+        # Asserts that an image has not changed compared to its baseline.
+        #
+        # @param caller [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 assert_image_not_changed(caller, name, comparison)
           result = comparison.different?
 
@@ -100,11 +163,15 @@ module Capybara
 
           return unless result
 
-          "Screenshot does not match for '#{name}' #{comparison.error_message}\n#{caller}"
+          "Screenshot does not match for '#{name}' #{comparison.error_message}\n#{caller.join(", ")}"
         end
 
         private
 
+        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)

data/lib/capybara/screenshot/diff/{drivers/utils.rb → utils.rb}

@@ -36,13 +36,6 @@ module Capybara
               fail "Wrong adapter #{driver.inspect}. Available adapters: #{AVAILABLE_DRIVERS.inspect}"
             end
         end
-
-        def self.detect_test_framework_assert
-          require "minitest"
-          ::Minitest::Assertion
-        rescue
-          ::RuntimeError
-        end
       end
     end
   end

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

@@ -6,39 +6,45 @@ module Capybara
   module Screenshot
     module Diff
       module Vcs
-        SILENCE_ERRORS = Os::ON_WINDOWS ? "2>nul" : "2>/dev/null"
+        def self.checkout_vcs(root, screenshot_path, checkout_path)
+          if svn?(root)
+            restore_svn_revision(screenshot_path, checkout_path)
+          else
+            restore_git_revision(screenshot_path, checkout_path, root: root)
+          end
+        end
 
-        def self.restore_git_revision(screenshot_path, checkout_path)
-          vcs_file_path = screenshot_path.relative_path_from(Screenshot.root)
+        def self.svn?(root)
+          (root / ".svn").exist?
+        end
+
+        SILENCE_ERRORS = Os::ON_WINDOWS ? "2>nul" : "2>/dev/null"
 
+        def self.restore_git_revision(screenshot_path, checkout_path = screenshot_path, root:)
+          vcs_file_path = screenshot_path.relative_path_from(root)
           redirect_target = "#{checkout_path} #{SILENCE_ERRORS}"
           show_command = "git show HEAD~0:./#{vcs_file_path}"
-          if Screenshot.use_lfs
-            `#{show_command} > #{checkout_path}.tmp #{SILENCE_ERRORS}`
-            if $CHILD_STATUS == 0
-              `git lfs smudge < #{checkout_path}.tmp > #{redirect_target}`
+
+          Dir.chdir(root) do
+            if Screenshot.use_lfs
+              system("#{show_command} > #{checkout_path}.tmp #{SILENCE_ERRORS}", exception: !!ENV["DEBUG"])
+
+              `git lfs smudge < #{checkout_path}.tmp > #{redirect_target}` if $CHILD_STATUS == 0
+
+              File.delete "#{checkout_path}.tmp"
+            else
+              system("#{show_command} > #{redirect_target}", exception: !!ENV["DEBUG"])
             end
-            File.delete "#{checkout_path}.tmp"
-          else
-            `#{show_command} > #{redirect_target}`
           end
 
           if $CHILD_STATUS != 0
-            FileUtils.rm_f(checkout_path)
+            checkout_path.delete if checkout_path.exist?
             false
           else
             true
           end
         end
 
-        def self.checkout_vcs(screenshot_path, checkout_path)
-          if svn?
-            restore_svn_revision(screenshot_path, checkout_path)
-          else
-            restore_git_revision(screenshot_path, checkout_path)
-          end
-        end
-
         def self.restore_svn_revision(screenshot_path, checkout_path)
           committed_file_name = screenshot_path + "../.svn/text-base/" + "#{screenshot_path.basename}.svn-base"
           if committed_file_name.exist?
@@ -60,10 +66,6 @@ module Capybara
 
           false
         end
-
-        def self.svn?
-          (Screenshot.screenshot_area_abs / ".svn").exist?
-        end
       end
     end
   end

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

@@ -3,7 +3,7 @@
 module Capybara
   module Screenshot
     module Diff
-      VERSION = "1.8.3"
+      VERSION = "1.9.2"
     end
   end
 end

data/lib/capybara/screenshot/diff.rb

@@ -1,113 +1,3 @@
 # frozen_string_literal: true
 
-require "capybara/dsl"
-require "capybara/screenshot/diff/version"
-require "capybara/screenshot/diff/drivers/utils"
-require "capybara/screenshot/diff/image_compare"
-require "capybara/screenshot/diff/test_methods"
-require "capybara/screenshot/diff/screenshoter"
-
-module Capybara
-  module Screenshot
-    mattr_accessor :add_driver_path
-    mattr_accessor :add_os_path
-    mattr_accessor :blur_active_element
-    mattr_accessor :enabled
-    mattr_accessor :hide_caret
-    mattr_reader(:root) { (defined?(Rails.root) && Rails.root) || Pathname(".").expand_path }
-    mattr_accessor :stability_time_limit
-    mattr_accessor :window_size
-    mattr_accessor(:save_path) { "doc/screenshots" }
-    mattr_accessor(:use_lfs)
-
-    class << self
-      def root=(path)
-        @@root = Pathname(path).expand_path
-      end
-
-      def active?
-        enabled || (enabled.nil? && Diff.enabled)
-      end
-
-      def screenshot_area
-        parts = [Screenshot.save_path]
-        parts << Capybara.current_driver.to_s if Screenshot.add_driver_path
-        parts << Os.name if Screenshot.add_os_path
-        File.join(*parts)
-      end
-
-      def screenshot_area_abs
-        root / screenshot_area
-      end
-    end
-
-    # Module to track screen shot changes
-    module Diff
-      include Capybara::DSL
-
-      mattr_accessor(:delayed) { true }
-      mattr_accessor :area_size_limit
-      mattr_accessor :color_distance_limit
-      mattr_accessor(:enabled) { true }
-      mattr_accessor :shift_distance_limit
-      mattr_accessor :skip_area
-      mattr_accessor(:driver) { :auto }
-      mattr_accessor :tolerance
-
-      mattr_accessor(:screenshoter) { Screenshoter }
-
-      AVAILABLE_DRIVERS = Utils.detect_available_drivers.freeze
-      ASSERTION = Utils.detect_test_framework_assert
-
-      def self.default_options
-        {
-          area_size_limit: area_size_limit,
-          color_distance_limit: color_distance_limit,
-          driver: driver,
-          shift_distance_limit: shift_distance_limit,
-          skip_area: skip_area,
-          stability_time_limit: Screenshot.stability_time_limit,
-          tolerance: tolerance || ((driver == :vips) ? 0.001 : nil),
-          wait: Capybara.default_max_wait_time
-        }
-      end
-
-      def self.included(klass)
-        klass.include TestMethods
-        klass.setup do
-          BrowserHelpers.resize_to(Screenshot.window_size) if Screenshot.window_size
-        end
-
-        klass.teardown do
-          if Screenshot.active? && @test_screenshots.present?
-            track_failures(@test_screenshots)
-            @test_screenshots.clear
-          end
-        end
-      end
-
-      private
-
-      EMPTY_LINE = "\n\n"
-
-      def track_failures(screenshots)
-        test_screenshot_errors = screenshots.map do |caller, name, compare|
-          assert_image_not_changed(caller, name, compare)
-        end
-
-        test_screenshot_errors.compact!
-
-        unless test_screenshot_errors.empty?
-          error = ASSERTION.new(test_screenshot_errors.join(EMPTY_LINE))
-          error.set_backtrace([])
-
-          if is_a?(::Minitest::Runnable)
-            failures << error
-          else
-            raise error
-          end
-        end
-      end
-    end
-  end
-end
+require "capybara_screenshot_diff/minitest"

data/lib/capybara-screenshot-diff.rb

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
 
-require "capybara/screenshot/diff"
+require "capybara_screenshot_diff/minitest"

data/lib/capybara_screenshot_diff/attempts_reporter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "capybara/screenshot/diff/image_compare"
+
+module CapybaraScreenshotDiff
+  class AttemptsReporter
+    def initialize(snapshot, comparison_options, stability_options = {})
+      @snapshot = snapshot
+      @comparison_options = comparison_options
+      @wait = stability_options[:wait]
+    end
+
+    def generate
+      attempts_screenshot_paths = @snapshot.find_attempts_paths
+
+      annotate_attempts(attempts_screenshot_paths)
+
+      "Could not get stable screenshot within #{@wait}s:\n#{attempts_screenshot_paths.join("\n")}"
+    end
+
+    def build_comparison_for(attempt_path, previous_attempt_path)
+      Capybara::Screenshot::Diff::ImageCompare.new(attempt_path, previous_attempt_path, @comparison_options)
+    end
+
+    private
+
+    def annotate_attempts(attempts_screenshot_paths)
+      previous_file = nil
+      attempts_screenshot_paths.reverse_each do |file_name|
+        if previous_file && File.exist?(previous_file)
+          attempts_comparison = build_comparison_for(file_name, previous_file)
+
+          if attempts_comparison.different?
+            FileUtils.mv(attempts_comparison.reporter.annotated_base_image_path, previous_file, force: true)
+          else
+            warn "[capybara-screenshot-diff] Some attempts was stable, but mistakenly marked as not: " \
+                   "#{previous_file} and #{file_name} are equal"
+          end
+
+          FileUtils.rm(attempts_comparison.reporter.annotated_image_path, force: true)
+        end
+
+        previous_file = file_name
+      end
+
+      previous_file
+    end
+  end
+end

data/lib/capybara_screenshot_diff/cucumber.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "capybara_screenshot_diff/dsl"
+
+World(::CapybaraScreenshotDiff::DSL)
+
+Before do
+  Capybara::Screenshot::Diff.delayed = false
+  if Capybara::Screenshot.active? && Capybara::Screenshot.window_size
+    Capybara::Screenshot::BrowserHelpers.resize_to(Capybara::Screenshot.window_size)
+  end
+end

data/lib/capybara_screenshot_diff/dsl.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "capybara_screenshot_diff"
+require "capybara/screenshot/diff/test_methods"
+
+module CapybaraScreenshotDiff
+  module DSL
+    include Capybara::DSL
+    include Capybara::Screenshot::Diff::TestMethods
+  end
+end

data/lib/capybara_screenshot_diff/minitest.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "minitest"
+require "capybara_screenshot_diff/dsl"
+
+used_deprecated_entrypoint = caller.any? do |path|
+  path.include?("capybara-screenshot-diff.rb") || path.include?("capybara/screenshot/diff.rb")
+end
+
+if used_deprecated_entrypoint
+  warn <<~MSG
+    [DEPRECATION] The default activation of `capybara_screenshot_diff/minitest` will be removed. 
+                  Please `require "capybara_screenshot_diff/minitest"` explicitly.
+  MSG
+end
+
+module CapybaraScreenshotDiff
+  module Minitest
+    module Assertions
+      include ::CapybaraScreenshotDiff::DSL
+
+      def screenshot(*, **)
+        super
+      rescue CapybaraScreenshotDiff::ExpectationNotMet => e
+        raise ::Minitest::Assertion, e.message
+      end
+
+      alias_method :assert_matches_screenshot, :screenshot
+
+      def self.included(klass)
+        klass.setup do
+          if ::Capybara::Screenshot.window_size
+            ::Capybara::Screenshot::BrowserHelpers.resize_to(::Capybara::Screenshot.window_size)
+          end
+        end
+
+        klass.teardown do
+          errors = verify_screenshots!(@test_screenshots)
+
+          failures << ::Minitest::Assertion.new(errors.join("\n\n")) if errors && !errors.empty?
+        end
+      end
+    end
+  end
+end

data/lib/capybara_screenshot_diff/rspec.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+require "capybara_screenshot_diff/dsl"
+
+RSpec::Matchers.define :match_screenshot do |name, **options|
+  description { "match a screenshot" }
+
+  match do |_page|
+    screenshot(name, **options)
+    true
+  end
+end
+
+RSpec.configure do |config|
+  config.include ::CapybaraScreenshotDiff::DSL, type: :feature
+  config.include ::CapybaraScreenshotDiff::DSL, type: :system
+
+  config.after do
+    if self.class.include?(::CapybaraScreenshotDiff::DSL) && ::Capybara::Screenshot.active?
+      errors = verify_screenshots!(@test_screenshots)
+      # TODO: Use rspec/mock approach to postpone verification
+      raise ::CapybaraScreenshotDiff::ExpectationNotMet, errors.join("\n") if errors && !errors.empty?
+    end
+  end
+
+  config.before do
+    if self.class.include?(::CapybaraScreenshotDiff::DSL) && ::Capybara::Screenshot.window_size
+      ::Capybara::Screenshot::BrowserHelpers.resize_to(::Capybara::Screenshot.window_size)
+    end
+  end
+end

data/lib/capybara_screenshot_diff/snap.rb

@@ -0,0 +1,55 @@
+# 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_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_*.#{format}"]
+    end
+  end
+end

data/lib/capybara_screenshot_diff/snap_manager.rb

@@ -0,0 +1,76 @@
+# 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)
+    end
+
+    def snapshot(screenshot_full_name, screenshot_format = "png")
+      Snap.new(screenshot_full_name, screenshot_format, manager: self)
+    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!
+      FileUtils.rm_rf root, secure: true
+    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
+
+    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