capybara-screenshot-diff 1.12.0 → 1.13.0

data/lib/capybara_screenshot_diff/dsl.rb

@@ -25,7 +25,7 @@ module CapybaraScreenshotDiff
       screenshot_namer.group = name
     end
 
-    # Takes a screenshot and optionally compares it against a baseline image.
+    # Takes a screenshot and compares it against a baseline image.
     #
     # The method follows a layered optimization strategy for comparison:
     # 1. First checks if screenshot functionality is active
@@ -53,7 +53,7 @@ module CapybaraScreenshotDiff
     # @raise [CapybaraScreenshotDiff::ExpectationNotMet] If comparison fails and immediate validation is enabled.
     # @raise [CapybaraScreenshotDiff::UnstableImage] If the image comparison is unstable.
     # @raise [CapybaraScreenshotDiff::WindowSizeMismatchError] If the window size doesn't match expectations.
-    def screenshot(name, skip_stack_frames: 0, **options)
+    def assert_matches_screenshot(name, skip_stack_frames: 0, **options)
       return false unless Capybara::Screenshot.active?
 
       # Get the full name with section and group information
@@ -76,15 +76,36 @@ module CapybaraScreenshotDiff
       true
     end
 
-    # Alias for backward compatibility with older test suites.
-    # @see #screenshot
-    alias_method :assert_matches_screenshot, :screenshot
+    # Convenience wrapper around {#assert_matches_screenshot} and {#capture_screenshot}.
+    # @param compare [Boolean] When false, only captures the screenshot without comparing it to a baseline.
+    # @see #assert_matches_screenshot
+    # @see #capture_screenshot
+    def screenshot(name, skip_stack_frames: 0, compare: true, **options)
+      if compare
+        assert_matches_screenshot(name, skip_stack_frames: skip_stack_frames + 1, **options)
+      else
+        capture_screenshot(name, **options)
+      end
+    end
+
+    # Captures a screenshot without comparing it to a baseline.
+    # @param name [String] The base name of the screenshot, used to generate the filename.
+    # @param options [Hash] Additional options for taking the screenshot. See {#assert_matches_screenshot}.
+    # @return [Boolean] True if the screenshot was successfully captured.
+    def capture_screenshot(name, **options)
+      return false unless Capybara::Screenshot.active?
+
+      full_name = CapybaraScreenshotDiff.screenshot_namer.full_name(name)
+      Capybara::Screenshot::Diff::ScreenshotMatcher.new(full_name, options).capture
+
+      true
+    end
 
     # Asserts the current page has no visual changes from the baseline.
     # Override in your base test class to add project-specific behavior
     # (e.g., waiting for Turbo, default skip areas).
     def assert_no_screenshot_changes(name, skip_stack_frames: 0, **opts)
-      screenshot(name, skip_stack_frames: skip_stack_frames + 1, **opts)
+      assert_matches_screenshot(name, skip_stack_frames: skip_stack_frames + 1, **opts)
     end
 
     private
@@ -96,7 +117,7 @@ module CapybaraScreenshotDiff
     #
     # @param name [String] The full name of the screenshot, including any section/group context.
     # @param options [Hash] Options for screenshot taking and comparison.
-    #   See {#screenshot} for available options.
+    #   See {#assert_matches_screenshot} for available options.
     # @param skip_stack_frames [Integer] Number of stack frames to skip for error reporting.
     # @return [ScreenshotAssertion, nil] The assertion object or nil if no assertion is needed.
     # @see ScreenshotAssertion

data/lib/capybara_screenshot_diff/minitest.rb

@@ -19,7 +19,7 @@ module CapybaraScreenshotDiff
     module Assertions
       include ::CapybaraScreenshotDiff::DSL
 
-      def screenshot(*args, skip_stack_frames: 0, **opts)
+      def assert_matches_screenshot(*args, skip_stack_frames: 0, **opts)
         self.assertions += 1
 
         super(*args, skip_stack_frames: skip_stack_frames + 1, **opts)
@@ -27,8 +27,6 @@ module CapybaraScreenshotDiff
         raise ::Minitest::Assertion, e.message
       end
 
-      alias_method :assert_matches_screenshot, :screenshot
-
       def setup
         super
         ::Capybara::Screenshot::BrowserHelpers.resize_window_if_needed
@@ -37,6 +35,11 @@ module CapybaraScreenshotDiff
       def before_teardown
         super
         CapybaraScreenshotDiff.verify
+
+        if ::Capybara::Screenshot::Diff.pending_if_new && CapybaraScreenshotDiff.new_screenshots_present?
+          names = CapybaraScreenshotDiff.new_screenshots
+          skip "No baseline for: #{names.join(", ")}. Commit the captured screenshots to record them."
+        end
       rescue CapybaraScreenshotDiff::ExpectationNotMet => e
         assertion = ::Minitest::Assertion.new(e)
         assertion.set_backtrace(e.backtrace)

data/lib/capybara_screenshot_diff/rspec.rb

@@ -7,7 +7,7 @@ RSpec::Matchers.define :match_screenshot do |name, **options|
   description { "match screenshot '#{name}'" }
 
   match do |_page|
-    screenshot(name, **options)
+    assert_matches_screenshot(name, **options)
     true
   end
 
@@ -30,10 +30,16 @@ RSpec.configure do |config|
     end
   end
 
-  config.after do
+  config.after do |example|
     if self.class.include?(CapybaraScreenshotDiff::DSL)
       begin
         CapybaraScreenshotDiff.verify
+
+        # Never mask a real failure with a pending marker.
+        if example.exception.nil? && Capybara::Screenshot::Diff.pending_if_new && CapybaraScreenshotDiff.new_screenshots_present?
+          names = CapybaraScreenshotDiff.new_screenshots
+          skip "No baseline for: #{names.join(", ")}. Commit the captured screenshots to record them."
+        end
       rescue CapybaraScreenshotDiff::ExpectationNotMet => e
         raise RSpec::Expectations::ExpectationNotMetError.new(e.message).tap { |ex| ex.set_backtrace(e.backtrace) }
       ensure

data/lib/capybara_screenshot_diff/screenshot_assertion.rb

@@ -65,10 +65,11 @@ module CapybaraScreenshotDiff
   end
 
   class AssertionRegistry
-    attr_reader :assertions, :screenshot_namer
+    attr_reader :assertions, :screenshot_namer, :new_screenshots
 
     def initialize
       @assertions = []
+      @new_screenshots = []
       @screenshot_namer = CapybaraScreenshotDiff::ScreenshotNamer.new
     end
 
@@ -84,6 +85,14 @@ 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
 
@@ -102,6 +111,7 @@ module CapybaraScreenshotDiff
 
     def reset
       @assertions.clear
+      @new_screenshots.clear
       @screenshot_namer = CapybaraScreenshotDiff::ScreenshotNamer.new
     end
   end
@@ -120,6 +130,9 @@ module CapybaraScreenshotDiff
     def_delegator :registry, :assertions
     def_delegator :registry, :assertions_present?
     def_delegator :registry, :failed_assertions
+    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

data/lib/capybara_screenshot_diff.rb

@@ -65,6 +65,7 @@ module Capybara
       mattr_accessor(:delayed) { true }
       mattr_accessor :area_size_limit
       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 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capybara-screenshot-diff
 version: !ruby/object:Gem::Version
-  version: 1.12.0
+  version: 1.13.0
 platform: ruby
 authors:
 - Uwe Kubosch
@@ -77,17 +77,21 @@ 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
@@ -149,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Track your GUI changes with diff assertions
 test_files: []