capybara-screenshot-diff 1.9.0 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39580aa58be36c5c95baa57516c499050b5806ac156e567cc31e5ce5b3a2c92c
-  data.tar.gz: 4a529c3e70bd39dbfb7eb10c78d15e24a66e47179445cc2f42ffd63305b3491f
+  metadata.gz: b035794cdcf21a354847ddc368d0eeedade734ee20c42f68552baaab5e10adce
+  data.tar.gz: 52053bf5f927c67478b1b5532e42fbaba493000196d55cad9e7f9229207ff9d2
 SHA512:
-  metadata.gz: 3ed30c48e2e2b3e9a4e49ab267ace2eadf4e3c7730ca628f9a0e58bf5f03f7c5d303c52744a1ffd554a3a4498101d4b6615f59d971ad8403a446c40bbac1582f
-  data.tar.gz: 9a2bd4035a02d2d38840befbf982adad15f45f0ce529dfbc1c8ad13ac047957e6eeee2b49d8bd77455443378f66a9113b584e9b714d0efc93f5639c0aad65788
+  metadata.gz: bf40f14eff9443d32aa8e179f97e33f4c36e4ad16a0fa49a23ebbfd50056b916bf74bdd1f64ac4cacf19b2ed1aaf6d948851879b5c814cae4701d94ee5d68287
+  data.tar.gz: '096e47818809b8f8cbca41b77b0044c0a91aa449e635315f090f74325be46a868ae3ee2958b518a29b59f294e9173c46ce4c4bb901349ffea46a2afc7edad0c8'

data/capybara-screenshot-diff.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.summary = "Track your GUI changes with diff assertions"
   spec.description = "Save screen shots and track changes with graphical diff"
   spec.homepage = "https://github.com/donv/capybara-screenshot-diff"
-  spec.required_ruby_version = ">= 3.0.0"
+  spec.required_ruby_version = ">= 3.1"
   spec.license = "MIT"
   spec.metadata["allowed_push_host"] = "https://rubygems.org/"
   spec.files = `git ls-files -z`.split("\x0").reject do |f|
@@ -23,6 +23,6 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "actionpack", ">= 6.1", "< 8"
+  spec.add_runtime_dependency "actionpack", ">= 7.0", "< 9"
   spec.add_runtime_dependency "capybara", ">= 2", "< 4"
 end

data/gems.rb

@@ -12,11 +12,13 @@ gem "chunky_png", ">= 1.3", require: false
 gem "oily_png", platform: :ruby, git: "https://github.com/wvanbergen/oily_png", ref: "44042006e79efd42ce4b52c1d78a4c70f0b4b1b2"
 gem "ruby-vips", require: false
 
-# Test
-gem "minitest", require: false
-gem "minitest-stub-const", require: false
-gem "simplecov", require: false
-gem "rspec", require: false
+group :test do
+  gem 'mutex_m' # Needed for RubyMine
+  gem "minitest", require: false
+  gem "minitest-stub-const", require: false
+  gem "simplecov", require: false
+  gem "rspec", require: false
+end
 
 # Capybara Server
 gem "puma", require: false

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

@@ -30,13 +30,13 @@ module Capybara
 
       IMAGE_WAIT_SCRIPT = <<~JS
         function pending_image() {
-          var images = document.images;
+          const images = document.images
           for (var i = 0; i < images.length; i++) {
-            if (!images[i].complete) {
-                return images[i].src;
+            if (!images[i].complete && images[i].loading !== "lazy") {
+                return images[i].src
             }
           }
-          return false;
+          return false
         }(window)
       JS
 

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

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "chunky_png"
 require "capybara/screenshot/diff/difference"
 
 module Capybara

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "capybara_screenshot_diff/snap_manager"
 require_relative "screenshoter"
 require_relative "stable_screenshoter"
 require_relative "browser_helpers"
@@ -10,15 +11,14 @@ module Capybara
   module Screenshot
     module Diff
       class ScreenshotMatcher
-        attr_reader :screenshot_full_name, :driver_options, :screenshot_path, :base_screenshot_path, :screenshot_format
+        attr_reader :screenshot_full_name, :driver_options, :screenshot_format
 
         def initialize(screenshot_full_name, options = {})
           @screenshot_full_name = screenshot_full_name
           @driver_options = Diff.default_options.merge(options)
 
           @screenshot_format = @driver_options[:screenshot_format]
-          @screenshot_path = Screenshot.screenshot_area_abs / Pathname.new(screenshot_full_name).sub_ext(".#{screenshot_format}")
-          @base_screenshot_path = ScreenshotMatcher.base_image_path_from(@screenshot_path)
+          @snapshot = CapybaraScreenshotDiff::SnapManager.snapshot(screenshot_full_name, @screenshot_format)
         end
 
         def build_screenshot_matches_job
@@ -32,58 +32,49 @@ module Capybara
           # TODO: Move this into screenshot stage, in order to re-evaluate coordinates after page updates
           # Allow nil or single or multiple areas
           driver_options[:skip_area] = area_calculator.calculate_skip_area
-
           driver_options[:driver] = Drivers.for(driver_options[:driver])
 
-          # Load base screenshot from VCS
-          create_output_directory_for(screenshot_path) unless screenshot_path.exist?
-
-          checkout_base_screenshot
+          @snapshot.checkout_base_screenshot
 
           # When fail_if_new is true no need to create screenshot if base screenshot is missing
-          return if Capybara::Screenshot::Diff.fail_if_new && !base_screenshot_path.exist?
-
-          capture_options = {
-            # screenshot options
-            capybara_screenshot_options: driver_options[:capybara_screenshot_options],
-            crop: driver_options.delete(:crop),
-            # delivery options
-            screenshot_format: driver_options[:screenshot_format],
-            # stability options
-            stability_time_limit: driver_options.delete(:stability_time_limit),
-            wait: driver_options.delete(:wait)
-          }
+          return if Capybara::Screenshot::Diff.fail_if_new && !@snapshot.base_path.exist?
+
+          capture_options, comparison_options = extract_capture_and_comparison_options!(driver_options)
 
           # Load new screenshot from Browser
-          take_comparison_screenshot(capture_options, driver_options, screenshot_path)
+          take_comparison_screenshot(capture_options, comparison_options, @snapshot)
 
           # Pre-computation: No need to compare without base screenshot
-          return unless base_screenshot_path.exist?
+          return unless @snapshot.base_path.exist?
 
           # Add comparison job in the queue
-          [screenshot_full_name, ImageCompare.new(screenshot_path, base_screenshot_path, driver_options)]
-        end
-
-        def self.base_image_path_from(screenshot_path)
-          screenshot_path.sub_ext(".base#{screenshot_path.extname}")
+          [screenshot_full_name, ImageCompare.new(@snapshot.path, @snapshot.base_path, comparison_options)]
         end
 
         private
 
-        def checkout_base_screenshot
-          Vcs.checkout_vcs(screenshot_path, base_screenshot_path)
-        end
-
-        def create_output_directory_for(screenshot_path)
-          screenshot_path.dirname.mkpath
+        def extract_capture_and_comparison_options!(driver_options = {})
+          [
+            {
+              # screenshot options
+              capybara_screenshot_options: driver_options[:capybara_screenshot_options],
+              crop: driver_options.delete(:crop),
+              # delivery options
+              screenshot_format: driver_options[:screenshot_format],
+              # stability options
+              stability_time_limit: driver_options.delete(:stability_time_limit),
+              wait: driver_options.delete(:wait)
+            },
+            driver_options
+          ]
         end
 
         # Try to get screenshot from browser.
         # On `stability_time_limit` it checks that page stop updating by comparison several screenshot attempts
         # On reaching `wait` limit then it has been failed. On failing we annotate screenshot attempts to help to debug
-        def take_comparison_screenshot(capture_options, driver_options, screenshot_path)
-          screenshoter = build_screenshoter_for(capture_options, driver_options)
-          screenshoter.take_comparison_screenshot(screenshot_path)
+        def take_comparison_screenshot(capture_options, comparison_options, snapshot = nil)
+          screenshoter = build_screenshoter_for(capture_options, comparison_options)
+          screenshoter.take_comparison_screenshot(snapshot)
         end
 
         def build_screenshoter_for(capture_options, comparison_options = {})

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

@@ -6,11 +6,10 @@ require_relative "browser_helpers"
 module Capybara
   module Screenshot
     class Screenshoter
-      attr_reader :capture_options, :comparison_options, :driver
+      attr_reader :capture_options, :driver
 
       def initialize(capture_options, driver)
         @capture_options = capture_options
-        @comparison_options = comparison_options
         @driver = driver
       end
 
@@ -22,34 +21,16 @@ module Capybara
         @capture_options[:wait]
       end
 
-      def screenshot_format
-        @capture_options[:screenshot_format] || "png"
-      end
-
       def capybara_screenshot_options
         @capture_options[:capybara_screenshot_options] || {}
       end
 
-      def self.attempts_screenshot_paths(base_file)
-        extname = Pathname.new(base_file).extname
-        Dir["#{base_file.to_s.chomp(extname)}.attempt_*#{extname}"].sort
-      end
-
-      def self.cleanup_attempts_screenshots(base_file)
-        FileUtils.rm_rf attempts_screenshot_paths(base_file)
-      end
-
       # Try to get screenshot from browser.
       # On `stability_time_limit` it checks that page stop updating by comparison several screenshot attempts
       # On reaching `wait` limit then it has been failed. On failing we annotate screenshot attempts to help to debug
-      def take_comparison_screenshot(screenshot_path)
-        capture_screenshot_at(screenshot_path)
-
-        Screenshoter.cleanup_attempts_screenshots(screenshot_path)
-      end
-
-      def self.gen_next_attempt_path(screenshot_path, iteration)
-        screenshot_path.sub_ext(format(".attempt_%02i#{screenshot_path.extname}", iteration))
+      def take_comparison_screenshot(snapshot)
+        capture_screenshot_at(snapshot)
+        snapshot.cleanup_attempts
       end
 
       PNG_EXTENSION = ".png"
@@ -123,18 +104,10 @@ module Capybara
         File.unlink(tmpfile) if tmpfile
       end
 
-      def capture_screenshot_at(screenshot_path)
-        new_screenshot_path = Screenshoter.gen_next_attempt_path(screenshot_path, 0)
-        take_and_process_screenshot(new_screenshot_path, screenshot_path)
-      end
-
-      def take_and_process_screenshot(new_screenshot_path, screenshot_path)
-        take_screenshot(new_screenshot_path)
-        move_screenshot_to(new_screenshot_path, screenshot_path)
-      end
+      def capture_screenshot_at(snapshot)
+        take_screenshot(snapshot.next_attempt_path!)
 
-      def move_screenshot_to(new_screenshot_path, screenshot_path)
-        FileUtils.mv(new_screenshot_path, screenshot_path, force: true)
+        snapshot.commit_last_attempt
       end
 
       def resize_if_needed(saved_image)

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

@@ -16,17 +16,17 @@ module Capybara
         # @param capture_options [Hash] The options for capturing screenshots, must include `:stability_time_limit` and `:wait`.
         # @param comparison_options [Hash, nil] The options for comparing screenshots, defaults to `nil` which uses `Diff.default_options`.
         # @raise [ArgumentError] If `:wait` or `:stability_time_limit` are not provided, or if `:stability_time_limit` is greater than `:wait`.
-        def initialize(capture_options, comparison_options = nil)
-          @stability_time_limit, @wait = capture_options.fetch_values(:stability_time_limit, :wait)
+        def initialize(capture_options, comparison_options = {})
+          @stability_time_limit, @wait = capture_options.fetch_values(*STABILITY_OPTIONS)
 
           raise ArgumentError, "wait should be provided for stable screenshots" unless wait
           raise ArgumentError, "stability_time_limit should be provided for stable screenshots" unless stability_time_limit
           raise ArgumentError, "stability_time_limit (#{stability_time_limit}) should be less or equal than wait (#{wait}) for stable screenshots" unless stability_time_limit <= wait
 
-          @comparison_options = comparison_options || Diff.default_options
+          @comparison_options = comparison_options
 
           driver = Diff::Drivers.for(@comparison_options)
-          @screenshoter = Diff.screenshoter.new(capture_options.except(*STABILITY_OPTIONS), driver)
+          @screenshoter = Diff.screenshoter.new(capture_options.except(:stability_time_limit), driver)
         end
 
         # Takes a comparison screenshot ensuring page stability
@@ -35,92 +35,72 @@ module Capybara
         # or the `:wait` limit is reached. If unable to achieve a stable state within the time limit, it annotates the attempts
         # to aid debugging.
         #
-        # @param screenshot_path [String, Pathname] The path where the screenshot will be saved.
+        # @param snapshot Snap The snapshot details to take a stable screenshot of.
         # @return [void]
         # @raise [RuntimeError] If a stable screenshot cannot be obtained within the specified `:wait` time.
-        def take_comparison_screenshot(screenshot_path)
-          new_screenshot_path = take_stable_screenshot(screenshot_path)
+        def take_comparison_screenshot(snapshot)
+          result = take_stable_screenshot(snapshot)
 
           # We failed to get stable browser state! Generate difference between attempts to overview moving parts!
-          unless new_screenshot_path
+          unless result
             # FIXME(uwe): Change to store the failure and only report if the test succeeds functionally.
-            annotate_attempts_and_fail!(screenshot_path)
+            annotate_attempts_and_fail!(snapshot)
           end
 
-          FileUtils.mv(new_screenshot_path, screenshot_path, force: true)
-          Screenshoter.cleanup_attempts_screenshots(screenshot_path)
+          # store success attempt as actual screenshot
+          snapshot.commit_last_attempt
+
+          # cleanup all previous attempts
+          snapshot.cleanup_attempts
         end
 
-        def take_stable_screenshot(screenshot_path)
-          screenshot_path = screenshot_path.is_a?(String) ? Pathname.new(screenshot_path) : screenshot_path
+        def take_stable_screenshot(snapshot)
           # We try to compare first attempt with checkout version, in order to not run next screenshots
-          attempt_path = nil
           deadline_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + wait
 
           # Cleanup all previous attempts for sure
-          Screenshoter.cleanup_attempts_screenshots(screenshot_path)
+          snapshot.cleanup_attempts
 
           0.step do |i|
             # FIXME: it should be wait, and wait should be replaced with stability_time_limit
-            sleep(stability_time_limit) unless i == 0
-            attempt_path, prev_attempt_path = attempt_next_screenshot(attempt_path, i, screenshot_path)
-            return attempt_path if attempt_successful?(attempt_path, prev_attempt_path)
-            return nil if timeout?(deadline_at)
+            sleep(stability_time_limit) unless i == 0 # test prev_attempt_path is nil
+
+            attempt_next_screenshot(snapshot)
+
+            return true if attempt_successful?(snapshot)
+            return false if timeout?(deadline_at)
           end
         end
 
         private
 
-        def attempt_successful?(attempt_path, prev_attempt_path)
-          return false unless prev_attempt_path
-          build_comparison_for(attempt_path, prev_attempt_path).quick_equal?
+        def attempt_successful?(snapshot)
+          return false unless snapshot.prev_attempt_path
+
+          build_last_attempts_comparison_for(snapshot).quick_equal?
         rescue ArgumentError
           false
         end
 
-        def attempt_next_screenshot(prev_attempt_path, i, screenshot_path)
-          new_attempt_path = Screenshoter.gen_next_attempt_path(screenshot_path, i)
-          @screenshoter.take_screenshot(new_attempt_path)
-          [new_attempt_path, prev_attempt_path]
+        def attempt_next_screenshot(snapshot)
+          @screenshoter.take_screenshot(snapshot.next_attempt_path!)
         end
 
         def timeout?(deadline_at)
           Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline_at
         end
 
-        def build_comparison_for(attempt_path, previous_attempt_path)
-          ImageCompare.new(attempt_path, previous_attempt_path, @comparison_options)
+        def build_last_attempts_comparison_for(snapshot)
+          ImageCompare.new(snapshot.attempt_path, snapshot.prev_attempt_path, @comparison_options)
         end
 
         # TODO: Move to the HistoricalReporter
-        def annotate_attempts_and_fail!(screenshot_path)
-          screenshot_attempts = Screenshoter.attempts_screenshot_paths(screenshot_path)
-
-          annotate_stabilization_images(screenshot_attempts)
+        def annotate_attempts_and_fail!(snapshot)
+          require "capybara_screenshot_diff/attempts_reporter"
+          attempts_reporter = CapybaraScreenshotDiff::AttemptsReporter.new(snapshot, @comparison_options, {wait: wait, stability_time_limit: stability_time_limit})
 
           # TODO: Move fail to the queue after tests passed
-          fail("Could not get stable screenshot within #{wait}s:\n#{screenshot_attempts.join("\n")}")
-        end
-
-        # TODO: Add tests that we annotate all files except first one
-        def annotate_stabilization_images(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
+          fail(attempts_reporter.generate)
         end
       end
     end

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

@@ -26,7 +26,7 @@ module Capybara
     module Diff
       module TestMethods
         # @!attribute [rw] test_screenshots
-        #   @return [Array(Array(Array(String), String, ImageCompare))] An array where each element is an array containing the caller context,
+        #   @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(*)
@@ -123,9 +123,10 @@ module Capybara
           screenshot_full_name = build_full_name(name)
           job = build_screenshot_matches_job(screenshot_full_name, options)
 
+          caller = caller(skip_stack_frames + 1).reject { |l| l =~ /gems\/(activesupport|minitest|railties)/ }
           unless job
             if Screenshot::Diff.fail_if_new
-              raise_error(<<-ERROR.strip_heredoc, caller(2))
+              _raise_error(<<-ERROR.strip_heredoc, caller)
                 No existing screenshot found for #{screenshot_full_name}!
                 To stop seeing this error disable by `Capybara::Screenshot::Diff.fail_if_new=false`
               ERROR
@@ -134,19 +135,19 @@ module Capybara
             return false
           end
 
-          job.prepend(caller(skip_stack_frames))
+          job.prepend(caller)
 
           if Screenshot::Diff.delayed
             schedule_match_job(job)
           else
             error_msg = assert_image_not_changed(*job)
-            raise_error(error_msg, caller(2)) if error_msg
+            _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] The caller context, used for error reporting.
+        # @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.
@@ -163,12 +164,12 @@ 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("\n")}"
         end
 
         private
 
-        def raise_error(error_msg, backtrace)
+        def _raise_error(error_msg, backtrace)
           raise CapybaraScreenshotDiff::ExpectationNotMet.new(error_msg).tap { _1.set_backtrace(backtrace) }
         end
 

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

@@ -6,21 +6,35 @@ 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
@@ -31,14 +45,6 @@ module Capybara
           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.9.0"
+      VERSION = '1.10.0'
     end
   end
 end

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/dsl.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "capybara_screenshot_diff"
+require "capybara/screenshot/diff/test_methods"
 
 module CapybaraScreenshotDiff
   module DSL

data/lib/capybara_screenshot_diff/minitest.rb

@@ -19,10 +19,10 @@ module CapybaraScreenshotDiff
     module Assertions
       include ::CapybaraScreenshotDiff::DSL
 
-      def screenshot(*, **)
-        super
-      rescue CapybaraScreenshotDiff::ExpectationNotMet => e
-        raise ::Minitest::Assertion, e.message
+      def screenshot(*args, skip_stack_frames: 0, **opts)
+        assert_nothing_raised do
+          super(*args, skip_stack_frames: skip_stack_frames + 1, **opts)
+        end
       end
 
       alias_method :assert_matches_screenshot, :screenshot
@@ -37,7 +37,11 @@ module CapybaraScreenshotDiff
         klass.teardown do
           errors = verify_screenshots!(@test_screenshots)
 
-          failures << ::Minitest::Assertion.new(errors.join("\n\n")) if errors && !errors.empty?
+          if errors.present?
+            assertion = ::Minitest::Assertion.new(errors.join("\n\n"))
+            assertion.set_backtrace []
+            failures << assertion
+          end
         end
       end
     end

data/lib/capybara_screenshot_diff/rspec.rb

@@ -14,6 +14,7 @@ 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?

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

data/lib/capybara_screenshot_diff.rb

@@ -4,9 +4,9 @@ require "capybara/dsl"
 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"
 
 module CapybaraScreenshotDiff
@@ -20,7 +20,7 @@ module Capybara
     mattr_accessor :blur_active_element
     mattr_accessor :enabled
     mattr_accessor :hide_caret
-    mattr_reader(:root) { (defined?(Rails.root) && Rails.root) || Pathname(".").expand_path }
+    mattr_reader(:root) { (defined?(Rails) && defined?(Rails.root) && Rails.root) || Pathname(".").expand_path }
     mattr_accessor :stability_time_limit
     mattr_accessor :window_size
     mattr_accessor(:save_path) { "doc/screenshots" }
@@ -63,6 +63,7 @@ module Capybara
       mattr_accessor :tolerance
 
       mattr_accessor(:screenshoter) { Screenshoter }
+      mattr_accessor(:manager) { CapybaraScreenshotDiff::SnapManager }
 
       AVAILABLE_DRIVERS = Utils.detect_available_drivers.freeze
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: capybara-screenshot-diff
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.10.0
 platform: ruby
 authors:
 - Uwe Kubosch
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-07-30 00:00:00.000000000 Z
+date: 2024-12-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -16,20 +15,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '9'
 - !ruby/object:Gem::Dependency
   name: capybara
   requirement: !ruby/object:Gem::Requirement
@@ -84,16 +83,18 @@ files:
 - 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/cucumber.rb
 - lib/capybara_screenshot_diff/dsl.rb
 - lib/capybara_screenshot_diff/minitest.rb
 - lib/capybara_screenshot_diff/rspec.rb
+- lib/capybara_screenshot_diff/snap.rb
+- lib/capybara_screenshot_diff/snap_manager.rb
 homepage: https://github.com/donv/capybara-screenshot-diff
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org/
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -101,15 +102,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key: 
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Track your GUI changes with diff assertions
 test_files: []