refact: drops rbs usage (#122)

.github/actions/setup-ruby-and-dependencies/action.yml

@@ -20,7 +20,7 @@ runs:
       with:
         ruby-version: ${{ inputs.ruby-version }}
         bundler-cache: true
-        cache-version: ${{ inputs.ruby-cache-version }}
+        cache-version: ${{ inputs.ruby-cache-version }}-v1
 
     - name: Install and cache vips
       if: ${{ inputs.cache-apt-packages == 'true' }}

.github/workflows/test.yml

@@ -79,23 +79,6 @@ jobs:
           retention-days: 1
           path: coverage
 
-  test-signature:
-    name: Testing Signatures
-    needs: [ 'test' ]
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: ./.github/actions/setup-ruby-and-dependencies
-        with:
-          ruby-version: 3.3
-          cache-apt-packages: true
-
-      - run: bin/rake test:signatures
-        env:
-          SCREENSHOT_DRIVER: vips
-
   matrix:
     name: Test Integration Rails & Ruby
     # Test on master, when a review is requested or manually invoked.

Rakefile

@@ -17,16 +17,6 @@ Rake::TestTask.new("test:integration") do |t|
   t.test_files = FileList["test/integration/**/*_test.rb"]
 end
 
-Rake::TestTask.new("test:signatures") do |t|
-  ENV["RBS_TEST_DOUBLE_SUITE"] ||= "minitest"
-  ENV["RBS_TEST_TARGET"] ||= "Capybara::Screenshot::Diff::*"
-  ENV["RBS_TEST_OPT"] ||= "-rset -rpathname -Isig"
-
-  t.libs << "test"
-  t.ruby_opts << "-r rbs/test/setup"
-  t.test_files = FileList["test/**/*_test.rb"]
-end
-
 task "clobber" do
   puts "Cleanup tmp/*.png"
   FileUtils.rm_rf(Dir["./tmp/*"])

gems.rb

@@ -32,5 +32,4 @@
 
 group :tools do
   gem "standard", require: false
-  gem "rbs", require: false, platform: :ruby
 end

lib/capybara/screenshot/diff/stable_screenshoter.rb

@@ -8,6 +8,14 @@ class StableScreenshoter
 
         attr_reader :stability_time_limit, :wait
 
+        # Initializes a new instance of StableScreenshoter
+        #
+        # This method sets up a new screenshoter with specific capture and comparison options. It validates the presence of
+        # `:stability_time_limit` and `:wait` in capture options and ensures that `:stability_time_limit` is less than or equal to `:wait`.
+        #
+        # @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)
 
@@ -21,9 +29,15 @@ def initialize(capture_options, comparison_options = nil)
           @screenshoter = Diff.screenshoter.new(capture_options.except(*STABILITY_OPTIONS), driver)
         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
+        # Takes a comparison screenshot ensuring page stability
+        #
+        # Attempts to take a stable screenshot of the page by comparing several screenshot attempts until the page stops updating
+        # 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.
+        # @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)
 

lib/capybara/screenshot/diff/test_methods.rb

@@ -15,11 +15,20 @@
 
 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,11 @@ def initialize(*)
           @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
 
@@ -43,6 +57,10 @@ def verify_screenshots!(screenshots = @test_screenshots)
           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)
@@ -52,6 +70,9 @@ def build_full_name(name)
           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
@@ -68,6 +89,13 @@ def screenshot_group(name)
           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
@@ -80,6 +108,15 @@ def group_parts
           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?
 
@@ -97,7 +134,7 @@ def screenshot(name, skip_stack_frames: 0, **options)
             return false
           end
 
-          job.prepend(caller[skip_stack_frames])
+          job.prepend(caller(skip_stack_frames))
 
           if Screenshot::Diff.delayed
             schedule_match_job(job)
@@ -107,6 +144,13 @@ def screenshot(name, skip_stack_frames: 0, **options)
           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?