capybara-screenshot-diff 1.8.3 → 1.9.0

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))] 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] 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?
 
@@ -105,6 +168,10 @@ module Capybara
 
         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

@@ -24,7 +24,7 @@ module Capybara
           end
 
           if $CHILD_STATUS != 0
-            FileUtils.rm_f(checkout_path)
+            checkout_path.delete if checkout_path.exist?
             false
           else
             true

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

@@ -3,7 +3,7 @@
 module Capybara
   module Screenshot
     module Diff
-      VERSION = "1.8.3"
+      VERSION = "1.9.0"
     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/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,10 @@
+# frozen_string_literal: true
+
+require "capybara_screenshot_diff"
+
+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,31 @@
+# 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.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.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "capybara/dsl"
+require "capybara/screenshot/diff/version"
+require "capybara/screenshot/diff/utils"
+require "capybara/screenshot/diff/image_compare"
+require "capybara/screenshot/diff/test_methods"
+require "capybara/screenshot/diff/screenshoter"
+
+require "capybara/screenshot/diff/reporters/default"
+
+module CapybaraScreenshotDiff
+  class ExpectationNotMet < StandardError; end
+end
+
+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)
+    mattr_accessor(:screenshot_format) { "png" }
+    mattr_accessor(:capybara_screenshot_options) { {} }
+
+    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 << Os.name if Screenshot.add_os_path
+        parts << Capybara.current_driver.to_s if Screenshot.add_driver_path
+        File.join(*parts)
+      end
+
+      def screenshot_area_abs
+        root / screenshot_area
+      end
+    end
+
+    # Module to track screen shot changes
+    module Diff
+      mattr_accessor(:delayed) { true }
+      mattr_accessor :area_size_limit
+      mattr_accessor(:fail_if_new) { false }
+      mattr_accessor(:fail_on_difference) { true }
+      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
+
+      def self.default_options
+        {
+          area_size_limit: area_size_limit,
+          color_distance_limit: color_distance_limit,
+          driver: driver,
+          screenshot_format: Screenshot.screenshot_format,
+          capybara_screenshot_options: Screenshot.capybara_screenshot_options,
+          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
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: capybara-screenshot-diff
 version: !ruby/object:Gem::Version
-  version: 1.8.3
+  version: 1.9.0
 platform: ruby
 authors:
 - Uwe Kubosch
-autorequire:
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-09-25 00:00:00.000000000 Z
+date: 2024-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -50,20 +50,6 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '4'
-- !ruby/object:Gem::Dependency
-  name: chunky_png
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
 description: Save screen shots and track changes with graphical diff
 email:
 - uwe@kubosch.no
@@ -77,45 +63,37 @@ files:
 - gems.rb
 - lib/capybara-screenshot-diff.rb
 - lib/capybara/screenshot/diff.rb
+- lib/capybara/screenshot/diff/area_calculator.rb
 - lib/capybara/screenshot/diff/browser_helpers.rb
+- lib/capybara/screenshot/diff/comparison.rb
 - lib/capybara/screenshot/diff/cucumber.rb
 - lib/capybara/screenshot/diff/difference.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/utils.rb
 - lib/capybara/screenshot/diff/drivers/vips_driver.rb
 - lib/capybara/screenshot/diff/image_compare.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/stabilization.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
-- sig/capybara/screenshot/diff/diff.rbs
-- sig/capybara/screenshot/diff/difference.rbs
-- sig/capybara/screenshot/diff/drivers/base_driver.rbs
-- sig/capybara/screenshot/diff/drivers/browser_helpers.rbs
-- sig/capybara/screenshot/diff/drivers/chunky_png_driver.rbs
-- sig/capybara/screenshot/diff/drivers/utils.rbs
-- sig/capybara/screenshot/diff/drivers/vips_driver.rbs
-- sig/capybara/screenshot/diff/image_compare.rbs
-- sig/capybara/screenshot/diff/os.rbs
-- sig/capybara/screenshot/diff/region.rbs
-- sig/capybara/screenshot/diff/screenshot_matcher.rbs
-- sig/capybara/screenshot/diff/screenshoter.rbs
-- sig/capybara/screenshot/diff/stable_screenshoter.rbs
-- sig/capybara/screenshot/diff/test_methods.rbs
-- sig/capybara/screenshot/diff/vcs.rbs
+- lib/capybara_screenshot_diff.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
 homepage: https://github.com/donv/capybara-screenshot-diff
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org/
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -130,8 +108,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.5.11
+signing_key: 
 specification_version: 4
 summary: Track your GUI changes with diff assertions
 test_files: []

data/sig/capybara/screenshot/diff/diff.rbs

@@ -1,28 +0,0 @@
-module Capybara
-  module Screenshot
-    def self.root=: ((String | Pathname) path) -> Pathname
-
-    def self.root: -> Pathname
-
-    def self.active?: () -> boolish
-
-    def self.screenshot_area: () -> String
-
-    def self.screenshot_area_abs: () -> Pathname
-
-    # Module to track screen shot changes
-    module Diff
-      AVAILABLE_DRIVERS: Array[(:vips | :chunky_png)]
-
-      ASSERTION: (top | RuntimeError)
-
-      def self.default_options: () -> ScreenshotMatcher::input_options
-
-      def self.included: (top klass) -> void
-
-      private
-
-      def track_failures: (Array[untyped] screenshots) -> void
-    end
-  end
-end

data/sig/capybara/screenshot/diff/difference.rbs

@@ -1,33 +0,0 @@
-module Capybara
-  module Screenshot
-    module Diff
-      class Difference
-        attr_reader comparison: ImageCompare::Comparison
-
-        def different?: () -> bool
-
-        def base_image: () -> top
-
-        def options: () -> Drivers::BaseDriver::options_entity
-
-        def tolerance: () -> Numeric?
-
-        def area_size_limit: () -> Numeric?
-
-        def blank?: () -> bool
-
-        def region_area_size: () -> Numeric
-
-        def ratio: () -> Numeric?
-
-        def to_h: () -> Hash[Symbol, untyped]
-
-        def coordinates: () -> Region::raw_region_entity
-
-        def inspect: () -> String
-
-        def tolerable?: () -> bool
-      end
-    end
-  end
-end