snap_diff-capybara 0.0.1 → 2.0.0.beta1

data/lib/snap_diff/screenshot_matcher.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "capybara_screenshot_diff/snap_manager"
+require_relative "screenshoter"
+require_relative "stable_screenshoter"
+require_relative "browser_helpers"
+require_relative "capture/viewport"
+require_relative "vcs"
+require_relative "area_calculator"
+
+module SnapDiff
+  class ScreenshotMatcher
+    attr_reader :screenshot_full_name, :driver_options, :screenshot_format
+
+    def initialize(screenshot_full_name, options = {})
+      @screenshot_full_name = screenshot_full_name
+      @driver_options = Capybara::Screenshot::Diff.default_options.merge(options)
+
+      @screenshot_format = @driver_options[:screenshot_format]
+      @snapshot = SnapDiff::SnapManager.snapshot(screenshot_full_name, @screenshot_format)
+    end
+
+    def build_screenshot_assertion(skip_stack_frames: 0)
+      Capture::Viewport.prepare!(Capybara::Screenshot.window_size, anchor: nil)
+      prepare_screenshot_options
+      check_base_screenshot
+
+      capture_options, comparison_options = extract_capture_and_comparison_options(driver_options)
+
+      capture_screenshot(capture_options, comparison_options)
+
+      # Pre-computation: No need to compare without base screenshot
+      # NOTE: Consider to return PreValid Assertion Value Object with hard coded valid result
+      unless need_to_compare?
+        CapybaraScreenshotDiff.record_new_screenshot(screenshot_full_name)
+        return
+      end
+
+      create_screenshot_assertion(skip_stack_frames + 1, comparison_options)
+    end
+
+    # Captures a screenshot without comparing it to a baseline.
+    def capture
+      Capture::Viewport.prepare!(Capybara::Screenshot.window_size, anchor: nil)
+      prepare_screenshot_options
+
+      capture_options, comparison_options = extract_capture_and_comparison_options(driver_options)
+
+      @snapshot.manager.create_output_directory_for(@snapshot.path)
+      capture_screenshot(capture_options, comparison_options)
+    end
+
+    private
+
+    def need_to_compare?
+      @snapshot.base_path.exist?
+    end
+
+    def prepare_screenshot_options
+      area_calculator = AreaCalculator.new(driver_options.delete(:crop), driver_options[:skip_area])
+
+      driver_options[:crop] = area_calculator.calculate_crop
+      driver_options[:skip_area] = area_calculator.calculate_skip_area
+      driver_options[:driver] = SnapDiff::Drivers.for(driver_options[:driver])
+    end
+
+    def check_base_screenshot
+      @snapshot.checkout_base_screenshot
+
+      if Capybara::Screenshot::Diff.fail_if_new && !@snapshot.base_path.exist?
+        raise CapybaraScreenshotDiff::ExpectationNotMet.new(<<~ERROR.chomp, caller)
+          No existing screenshot found for #{@snapshot.base_path}!
+          To record baselines: RECORD_SCREENSHOTS=1 bundle exec rake test
+          To allow new screenshots: Capybara::Screenshot::Diff.fail_if_new = false
+        ERROR
+      end
+    end
+
+    def capture_screenshot(capture_options, comparison_options)
+      screenshoter = if capture_options[:stability_time_limit]
+        StableScreenshoter.new(capture_options, comparison_options)
+      else
+        Capybara::Screenshot::Diff.screenshoter.new(capture_options, comparison_options)
+      end
+      screenshoter.take_comparison_screenshot(@snapshot)
+    end
+
+    def create_screenshot_assertion(skip_stack_frames, comparison_options)
+      assertion = SnapDiff::ScreenshotAssertion.new(screenshot_full_name)
+      assertion.caller = caller(skip_stack_frames + 1)
+      assertion.compare = Comparison.new(@snapshot.path, @snapshot.base_path, comparison_options)
+      assertion
+    end
+
+    # Pure partition of one options hash into [capture_options,
+    # comparison_options]. Unlike the previous delete-based carve, this
+    # method itself does not mutate its input hash.
+    def extract_capture_and_comparison_options(driver_options = {})
+      capture_options = {
+        # screenshot options
+        capybara_screenshot_options: driver_options[:capybara_screenshot_options],
+        crop: driver_options[:crop],
+        # delivery options
+        screenshot_format: driver_options[:screenshot_format],
+        # stability options
+        stability_time_limit: driver_options[:stability_time_limit],
+        wait: driver_options[:wait]
+      }
+
+      [capture_options, driver_options.except(:crop, :stability_time_limit, :wait)]
+    end
+  end
+end

data/lib/snap_diff/screenshot_namer.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module SnapDiff
+  # Handles the naming, path generation, and organization of screenshots.
+  # This class encapsulates logic related to screenshot sections, groups,
+  # and counters, providing a centralized way to determine screenshot filenames
+  # and directories.
+  class ScreenshotNamer
+    attr_reader :section, :group
+
+    def initialize(screenshot_area = nil)
+      @section = nil
+      @group = nil
+      @counter = nil
+      @screenshot_area = screenshot_area
+    end
+
+    def screenshot_area
+      @screenshot_area ||= Capybara::Screenshot.screenshot_area
+    end
+
+    # Sets the current section for screenshots.
+    # @param name [String, nil] The name of the section.
+    def section=(name)
+      @section = name&.to_s
+      reset_group_counter
+    end
+
+    # Sets the current group for screenshots and resets the counter.
+    # @param name [String, nil] The name of the group.
+    def group=(name)
+      @group = name&.to_s
+      reset_group_counter
+    end
+
+    # Builds the full, unique name for a screenshot, including any counter.
+    # @param base_name [String] The base name for the screenshot.
+    # @return [String] The full screenshot name.
+    def full_name(base_name)
+      name = base_name.to_s
+
+      if @counter
+        name = format("%02i_%s", @counter, name)
+        @counter += 1
+      end
+
+      File.join(*directory_parts.push(name.to_s))
+    end
+
+    # Builds the full path for a screenshot file, including section and group directories.
+    # @param base_name [String] The base name for the screenshot.
+    # @return [String] The absolute path for the screenshot file.
+    def full_name_with_path(base_name)
+      File.join(screenshot_area, full_name(base_name))
+    end
+
+    # Returns the directory parts (section and group) for constructing paths.
+    # @return [Array<String>] An array of directory names.
+    def directory_parts
+      parts = []
+      parts << @section unless @section.nil? || @section.empty?
+      parts << @group unless @group.nil? || @group.empty?
+      parts
+    end
+
+    # Calculates the directory path for the current section and group.
+    # @return [String] The full path to the directory.
+    def current_group_directory
+      File.join(*([screenshot_area] + directory_parts))
+    end
+
+    private
+
+    def reset_group_counter
+      @counter = (@group.nil? || @group.empty?) ? nil : 0
+    end
+  end
+end

data/lib/snap_diff/screenshoter.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+require_relative "os"
+require_relative "browser_helpers"
+
+module SnapDiff
+  class Screenshoter
+    attr_reader :capture_options, :driver
+
+    # @param capture_options [Hash] Options for capturing (window_size, wait, etc.)
+    # @param comparison_options [Hash] Options for image comparison (driver, tolerance, etc.)
+    def initialize(capture_options, comparison_options = {})
+      @capture_options = capture_options
+      @driver = SnapDiff::Drivers.for(comparison_options)
+    end
+
+    def crop
+      @capture_options[:crop]
+    end
+
+    def wait
+      @capture_options[:wait]
+    end
+
+    def capybara_screenshot_options
+      @capture_options[:capybara_screenshot_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(snapshot)
+      capture_screenshot_at(snapshot)
+      snapshot.cleanup_attempts!
+    end
+
+    PNG_EXTENSION = ".png"
+
+    def take_screenshot(screenshot_path)
+      blurred_input = prepare_page_for_screenshot(timeout: wait)
+
+      # Take browser screenshot and save
+      save_and_process_screenshot(screenshot_path)
+
+      blurred_input&.click
+    end
+
+    def process_screenshot(stored_path, screenshot_path)
+      screenshot_image = driver.from_file(stored_path)
+
+      # TODO(uwe): Remove when chromedriver takes right size screenshots
+      # TODO: Adds tests when this case is true
+      screenshot_image = resize_if_needed(screenshot_image) if selenium_with_retina_screen?
+      # ODOT
+
+      screenshot_image = driver.crop(crop, screenshot_image) if crop
+
+      driver.save_image_to(screenshot_image, screenshot_path)
+    end
+
+    def notice_how_to_avoid_this
+      unless defined?(@_csd_retina_warned)
+        warn "Halving retina screenshot.  " \
+               'You should add "force-device-scale-factor=1" to your Chrome chromeOptions args.'
+        @_csd_retina_warned = true
+      end
+    end
+
+    def prepare_page_for_screenshot(timeout:)
+      wait_images_loaded(timeout: timeout) if timeout
+
+      blurred_input = BrowserHelpers.blur_from_focused_element if Capybara::Screenshot.blur_active_element
+
+      BrowserHelpers.hide_caret if Capybara::Screenshot.hide_caret
+      BrowserHelpers.disable_animations if Capybara::Screenshot.disable_animations
+
+      blurred_input
+    end
+
+    def wait_images_loaded(timeout:)
+      return unless timeout
+
+      deadline_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      loop do
+        pending_image = BrowserHelpers.pending_image_to_load
+        break unless pending_image
+
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline_at
+          raise CapybaraScreenshotDiff::ExpectationNotMet.new("Images have not been loaded after #{timeout}s: #{pending_image.inspect}", caller)
+        end
+
+        sleep 0.025
+      end
+    end
+
+    private
+
+    def save_and_process_screenshot(screenshot_path)
+      tmpfile = Tempfile.new([screenshot_path.basename.to_s, PNG_EXTENSION])
+      BrowserHelpers.session.save_screenshot(tmpfile.path, **capybara_screenshot_options)
+      # Load saved screenshot and pre-process it
+      process_screenshot(tmpfile.path, screenshot_path)
+    ensure
+      tmpfile&.close!
+    end
+
+    def capture_screenshot_at(snapshot)
+      take_screenshot(snapshot.next_attempt_path!)
+
+      snapshot.commit_last_attempt
+    end
+
+    def resize_if_needed(saved_image)
+      expected_image_width = Capybara::Screenshot.window_size[0]
+      return saved_image if driver.width_for(saved_image) < expected_image_width * 2
+
+      notice_how_to_avoid_this
+
+      new_height = expected_image_width * driver.height_for(saved_image) / driver.width_for(saved_image)
+      driver.resize_image_to(saved_image, expected_image_width, new_height)
+    end
+
+    def selenium_with_retina_screen?
+      Os::ON_MAC && BrowserHelpers.selenium? && Capybara::Screenshot.window_size
+    end
+  end
+end

data/lib/snap_diff/snap.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module SnapDiff
+  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_diff_artifacts!
+      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_[0-9][0-9].#{format}")]
+    end
+
+    private
+
+    def cleanup_diff_artifacts!
+      [
+        path.sub_ext(".diff.#{format}"),
+        path.sub_ext(".heatmap.diff.#{format}"),
+        base_path.sub_ext(".diff.#{format}")
+      ].each { |f| f.unlink if f.exist? }
+    end
+  end
+end

data/lib/snap_diff/snap_manager.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+require_relative "vcs"
+require "active_support/core_ext/module/attribute_accessors"
+
+require_relative "snap"
+
+module SnapDiff
+  class SnapManager
+    attr_reader :root
+
+    def initialize(root)
+      @root = Pathname.new(root)
+      @snapshots = Set.new
+    end
+
+    def snapshot(screenshot_full_name, screenshot_format = "png")
+      Snap.new(screenshot_full_name, screenshot_format, manager: self).tap do |snapshot|
+        @snapshots << snapshot
+      end
+    end
+
+    def self.snapshot(screenshot_full_name, screenshot_format = "png")
+      instance.snapshot(screenshot_full_name, screenshot_format)
+    end
+
+    # Pure path lookup: builds the Snap (path bundle) for a name WITHOUT
+    # registering it for cleanup. Use this when you only need to know where
+    # a screenshot lives; use #snapshot when taking one that cleanup! owns.
+    def path_for(screenshot_full_name, screenshot_format = "png")
+      Snap.new(screenshot_full_name, screenshot_format, manager: self)
+    end
+
+    def self.path_for(screenshot_full_name, screenshot_format = "png")
+      instance.path_for(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?
+      SnapDiff::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!
+      snapshots.each do |snapshot|
+        cleanup_attempts!(snapshot)
+        snapshot.delete!
+      end
+      # With the manager memoized per thread the set would otherwise grow for
+      # the whole run, and a later cleanup! could delete a path an earlier
+      # test tracked but the current test re-provisioned.
+      snapshots.clear
+    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
+
+    attr_reader :snapshots
+
+    def self.screenshots
+      instance.screenshots
+    end
+
+    def self.root
+      instance.root
+    end
+
+    # Thread-local memoized manager (D7 fix): snapshots tracked via the
+    # class-method path and class-method cleanup! now share one instance, so
+    # cleanup! actually deletes what was tracked. Rebuilt when the configured
+    # manager class or screenshot root changes (tests re-root per example).
+    #
+    # Thread.current[] is fiber-local — same construct as
+    # CapybaraScreenshotDiff.registry; both split per fiber and must migrate
+    # together if async support ever lands.
+    #
+    # Scope of the fix: default-root unit tests and before_setup re-rooters
+    # get working cleanup. System tests do NOT — system_test_case.rb re-roots
+    # in `setup do`, and LIFO teardown restores the root BEFORE test_helper's
+    # cleanup! runs, so the root-mismatch check below rebuilds an empty
+    # manager there. That miss is protective: firing cleanup on the restored
+    # instance would delete committed baselines under
+    # test/fixtures/app/doc/screenshots/ that VCS rollback just restored.
+    # Do not reorder those teardowns without revisiting this.
+    def self.instance
+      manager_class = Capybara::Screenshot::Diff.manager
+      root = Pathname.new(Capybara::Screenshot.screenshot_area_abs)
+
+      current = Thread.current[:snap_diff_manager]
+      unless current&.instance_of?(manager_class) && current.root == root
+        current = Thread.current[:snap_diff_manager] = manager_class.new(root)
+      end
+      current
+    end
+  end
+end

data/lib/snap_diff/stable_screenshoter.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module SnapDiff
+  class StableScreenshoter
+    STABILITY_OPTIONS = [:stability_time_limit, :wait]
+
+    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] The options for comparing screenshots, defaults to `{}`. Same signature as {Capybara::Screenshot::Screenshoter#initialize}.
+    # @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 = {})
+      @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
+
+      @screenshoter = Capybara::Screenshot::Diff.screenshoter.new(capture_options.except(:stability_time_limit), @comparison_options)
+    end
+
+    # 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 snapshot Snap The snapshot details to take a stable screenshot of.
+    # @return [void]
+    # @raise [CapybaraScreenshotDiff::UnstableImage] If a stable screenshot cannot be obtained within the specified `:wait` time.
+    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 result
+        # The failed-stability outcome is data (the annotated attempts report); raising is this
+        # boundary's decision, not the reporter's.
+        # FIXME(uwe): Hand the failure to the verify path so it only reports after the test's own assertions run.
+        raise CapybaraScreenshotDiff::UnstableImage.new(stability_failure_report(snapshot), caller)
+      end
+
+      # store success attempt as actual screenshot
+      snapshot.commit_last_attempt
+
+      # cleanup all previous attempts
+      snapshot.cleanup_attempts!
+    end
+
+    def take_stable_screenshot(snapshot)
+      # We try to compare first attempt with checkout version, in order to not run next screenshots
+      deadline_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + wait
+
+      # Cleanup all previous attempts for sure
+      snapshot.cleanup_attempts!
+
+      loop do
+        attempt_next_screenshot(snapshot)
+
+        return true if attempt_successful?(snapshot)
+        return false if timeout?(deadline_at)
+
+        sleep(stability_time_limit)
+      end
+    end
+
+    private
+
+    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(snapshot)
+      @screenshoter.take_screenshot(snapshot.next_attempt_path!)
+    end
+
+    def timeout?(deadline_at)
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline_at
+    end
+
+    def build_last_attempts_comparison_for(snapshot)
+      Comparison.new(snapshot.attempt_path, snapshot.prev_attempt_path, @comparison_options)
+    end
+
+    # Builds the failed-stability outcome as data: annotates the attempt artifacts on disk
+    # and returns the report message. Does not raise.
+    # @return [String] the annotated attempts report
+    def stability_failure_report(snapshot)
+      require_relative "attempts_reporter"
+      SnapDiff::AttemptsReporter.new(snapshot, @comparison_options, {wait: wait, stability_time_limit: stability_time_limit}).generate
+    end
+  end
+end

data/lib/snap_diff/static.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rack/files"
+require_relative "integrations/minitest"
+
+module SnapDiff
+  def self.serve(directory, root: Dir.pwd)
+    Capybara.app = Rack::Files.new(directory)
+    Capybara::Screenshot.root = root
+  end
+end

data/lib/snap_diff/utils.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module SnapDiff
+  module Utils
+    def self.detect_available_drivers
+      result = []
+      begin
+        result << :vips if defined?(Vips) || require("vips")
+      rescue LoadError
+        # vips not present
+        Object.send(:remove_const, :Vips) if defined?(Vips)
+      end
+      begin
+        result << :chunky_png if defined?(ChunkyPNG) || require("chunky_png")
+      rescue LoadError
+        # chunky_png not present
+        Object.send(:remove_const, :ChunkyPNG) if defined?(ChunkyPNG)
+      end
+      result
+    end
+
+    def self.find_driver_class_for(driver)
+      driver = Capybara::Screenshot::Diff::AVAILABLE_DRIVERS.first if driver == :auto
+
+      Capybara::Screenshot::Diff::LOADED_DRIVERS[driver] ||=
+        case driver
+        when :chunky_png
+          require "snap_diff/drivers/chunky_png_driver"
+          SnapDiff::Drivers::ChunkyPNGDriver
+        when :vips
+          require "snap_diff/drivers/vips_driver"
+          SnapDiff::Drivers::VipsDriver
+        else
+          fail "Wrong adapter #{driver.inspect}. Available adapters: #{Capybara::Screenshot::Diff::AVAILABLE_DRIVERS.inspect}"
+        end
+    end
+  end
+end