capybara-screenshot-diff 1.8.3 → 1.9.2

data/lib/capybara/screenshot/diff/reporters/default.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Capybara::Screenshot::Diff
+  module Reporters
+    class Default
+      attr_reader :annotated_image_path, :annotated_base_image_path, :heatmap_diff_path, :difference
+
+      def initialize(difference)
+        @difference = difference
+
+        screenshot_format = difference.comparison.options[:screenshot_format] || comparison.new_image_path.extname.slice(1..-1)
+        @annotated_image_path = comparison.new_image_path.sub_ext(".diff.#{screenshot_format}")
+        @annotated_base_image_path = comparison.base_image_path.sub_ext(".diff.#{screenshot_format}")
+        @heatmap_diff_path = comparison.new_image_path.sub_ext(".heatmap.diff.#{screenshot_format}")
+      end
+
+      def generate
+        if difference.equal?
+          # NOTE: Delete previous run runtime files
+          clean_tmp_files
+          return nil
+        end
+
+        if difference.failed? && difference.failed_by[:different_dimensions]
+          return build_error_for_different_dimensions
+        end
+
+        annotate_and_save_images
+        build_error_message
+      end
+
+      def clean_tmp_files
+        annotated_base_image_path.unlink if annotated_base_image_path.exist?
+        annotated_image_path.unlink if annotated_image_path.exist?
+      end
+
+      def build_error_for_different_dimensions
+        change_msg = [comparison.base_image, comparison.new_image]
+          .map { |image| driver.dimension(image).join("x") }
+          .join(" => ")
+
+        "Screenshot dimension has been changed for #{image_path.to_path}: #{change_msg}"
+      end
+
+      def annotate_and_save_images
+        save_annotation_for(new_image, annotated_image_path)
+        save_annotation_for(base_image, annotated_base_image_path)
+        save_heatmap_diff if difference.meta[:diff_mask]
+      end
+
+      def save_annotation_for(image, image_path)
+        image = annotate_difference(image, difference.region)
+        image = annotate_skip_areas(image, difference.skip_area) if difference.skip_area
+
+        save(image, image_path.to_path)
+      end
+
+      DIFF_COLOR = [255, 0, 0, 255].freeze
+
+      def annotate_difference(image, region)
+        driver.draw_rectangles([image], region, DIFF_COLOR, offset: 1).first
+      end
+
+      SKIP_COLOR = [255, 192, 0, 255].freeze
+
+      def annotate_skip_areas(image, skip_areas)
+        skip_areas.reduce(image) do |memo, region|
+          driver.draw_rectangles([memo], region, SKIP_COLOR).first
+        end
+      end
+
+      def save(image, image_path)
+        driver.save_image_to(image, image_path.to_s)
+      end
+
+      NEW_LINE = "\n"
+
+      def build_error_message
+        [
+          "(#{difference.inspect})",
+          image_path.to_path,
+          annotated_base_image_path.to_path,
+          annotated_image_path.to_path
+        ].join(NEW_LINE)
+      end
+
+      private
+
+      def save_heatmap_diff
+        merged_image = driver.merge(new_image, base_image)
+        highlighted_mask = driver.highlight_mask(difference.meta[:diff_mask], merged_image, color: DIFF_COLOR)
+
+        save(highlighted_mask, heatmap_diff_path.to_path)
+      end
+
+      def base_image
+        difference.comparison.base_image
+      end
+
+      def new_image
+        difference.comparison.new_image
+      end
+
+      def image_path
+        comparison.new_image_path
+      end
+
+      def driver
+        @_driver ||= comparison.driver
+      end
+
+      def comparison
+        @_comparison ||= difference.comparison
+      end
+    end
+  end
+end

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

@@ -1,94 +1,80 @@
 # frozen_string_literal: true
 
+require "capybara_screenshot_diff/snap_manager"
 require_relative "screenshoter"
 require_relative "stable_screenshoter"
 require_relative "browser_helpers"
 require_relative "vcs"
+require_relative "area_calculator"
 
 module Capybara
   module Screenshot
     module Diff
       class ScreenshotMatcher
-        attr_reader :screenshot_full_name, :driver_options, :screenshot_path, :base_screenshot_path
+        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_path = Screenshot.screenshot_area_abs / Pathname.new(screenshot_full_name).sub_ext(".png")
-          @base_screenshot_path = ScreenshotMatcher.base_image_path_from(@screenshot_path)
+          @screenshot_format = @driver_options[:screenshot_format]
+          @snapshot = CapybaraScreenshotDiff::SnapManager.snapshot(screenshot_full_name, @screenshot_format)
         end
 
         def build_screenshot_matches_job
           # TODO: Move this into screenshot stage, in order to re-evaluate coordinates after page updates
           return if BrowserHelpers.window_size_is_wrong?(Screenshot.window_size)
 
-          # Stability Screenshoter Options
-
           # TODO: Move this into screenshot stage, in order to re-evaluate coordinates after page updates
-          crop = calculate_crop_region(driver_options)
+          area_calculator = AreaCalculator.new(driver_options.delete(:crop), driver_options[:skip_area])
+          driver_options[:crop] = area_calculator.calculate_crop
 
-          # Allow nil or single or multiple areas
           # TODO: Move this into screenshot stage, in order to re-evaluate coordinates after page updates
-          if driver_options[:skip_area]
-            # Cast skip area args to Region and makes relative to crop
-            driver_options[:skip_area] = calculate_skip_area(driver_options[:skip_area], crop)
-          end
-          driver_options[:driver] = Drivers.for(driver_options)
+          # Allow nil or single or multiple areas
+          driver_options[:skip_area] = area_calculator.calculate_skip_area
+          driver_options[:driver] = Drivers.for(driver_options[:driver])
 
-          create_output_directory_for(screenshot_path) unless screenshot_path.exist?
+          @snapshot.checkout_base_screenshot
 
-          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 && !@snapshot.base_path.exist?
 
-          capture_options = {
-            crop: crop,
-            stability_time_limit: driver_options.delete(:stability_time_limit),
-            wait: driver_options.delete(:wait)
-          }
+          capture_options, comparison_options = extract_capture_and_comparison_options!(driver_options)
 
-          take_comparison_screenshot(capture_options, driver_options, screenshot_path)
+          # Load new screenshot from Browser
+          take_comparison_screenshot(capture_options, comparison_options, @snapshot)
 
-          return unless base_screenshot_path.exist?
+          # Pre-computation: No need to compare without base screenshot
+          return unless @snapshot.base_path.exist?
 
           # Add comparison job in the queue
-          [
-            screenshot_full_name,
-            ImageCompare.new(screenshot_path.to_s, base_screenshot_path.to_s, driver_options)
-          ]
-        end
-
-        def cleanup
-          FileUtils.rm_f(base_screenshot_path)
-        end
-
-        def self.base_image_path_from(screenshot_path)
-          screenshot_path.sub_ext(".base.png")
+          [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 calculate_crop_region(driver_options)
-          crop_coordinates = driver_options.delete(:crop)
-          return nil unless crop_coordinates
-
-          crop_coordinates = BrowserHelpers.bounds_for_css(crop_coordinates).first if crop_coordinates.is_a?(String)
-          Region.from_edge_coordinates(*crop_coordinates)
-        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 = {})
@@ -98,30 +84,6 @@ module Capybara
             Diff.screenshoter.new(capture_options, comparison_options[:driver])
           end
         end
-
-        # Cast skip areas params into Region
-        # and if there is crop then makes absolute coordinates to eb relative to crop top left corner
-        def calculate_skip_area(skip_area, crop)
-          crop_region = crop && Region.new(*crop)
-          skip_area = Array(skip_area)
-
-          css_selectors, regions = skip_area.compact.partition { |region| region.is_a? String }
-
-          result = []
-          unless css_selectors.empty?
-            result.concat(build_regions_for(BrowserHelpers.bounds_for_css(*css_selectors)))
-          end
-          result.concat(build_regions_for(regions.flatten.each_slice(4))) unless regions.empty?
-          result.compact!
-
-          result.map! { |region| crop_region.find_relative_intersect(region) } if crop_region
-
-          result
-        end
-
-        def build_regions_for(coordinates)
-          coordinates.map { |coordinates_entity| Region.from_edge_coordinates(*coordinates_entity) }
-        end
       end
     end
   end

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,88 +21,54 @@ module Capybara
         @capture_options[:wait]
       end
 
-      def self.attempts_screenshot_paths(base_file)
-        Dir["#{base_file.to_s.chomp(".png")}.attempt_*.png"].sort
-      end
-
-      def self.cleanup_attempts_screenshots(base_file)
-        FileUtils.rm_rf attempts_screenshot_paths(base_file)
+      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(screenshot_path)
-        new_screenshot_path = Screenshoter.gen_next_attempt_path(screenshot_path, 0)
-
-        take_screenshot(new_screenshot_path)
-
-        FileUtils.mv(new_screenshot_path, screenshot_path, force: true)
-        Screenshoter.cleanup_attempts_screenshots(screenshot_path)
+      def take_comparison_screenshot(snapshot)
+        capture_screenshot_at(snapshot)
+        snapshot.cleanup_attempts
       end
 
-      def self.gen_next_attempt_path(screenshot_path, iteration)
-        Pathname.new(screenshot_path).sub_ext(format(".attempt_%02i.png", iteration))
-      end
+      PNG_EXTENSION = ".png"
 
       def take_screenshot(screenshot_path)
         blurred_input = prepare_page_for_screenshot(timeout: wait)
 
         # Take browser screenshot and save
-        browser_save_screenshot(screenshot_path)
+        save_and_process_screenshot(screenshot_path)
 
-        # Load saved screenshot and pre-process it
-        process_screenshot(screenshot_path)
-      ensure
         blurred_input&.click
       end
 
-      def browser_save_screenshot(screenshot_path)
-        BrowserHelpers.session.save_screenshot(screenshot_path)
-      end
+      def process_screenshot(stored_path, screenshot_path)
+        screenshot_image = driver.from_file(stored_path)
 
-      def process_screenshot(screenshot_path)
         # TODO(uwe): Remove when chromedriver takes right size screenshots
         # TODO: Adds tests when this case is true
-        if selenium_with_retina_screen?
-          reduce_retina_image_size(screenshot_path)
-        end
+        screenshot_image = resize_if_needed(screenshot_image) if selenium_with_retina_screen?
         # ODOT
 
-        if crop
-          image = driver.from_file(screenshot_path)
-          cropped_image = driver.crop(crop, image)
-          driver.save_image_to(cropped_image, screenshot_path)
-        end
-      end
-
-      def reduce_retina_image_size(file_name)
-        expected_image_width = Screenshot.window_size[0]
-        saved_image = driver.from_file(file_name.to_s)
-        return 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)
-        resized_image = driver.resize_image_to(saved_image, expected_image_width, new_height)
+        screenshot_image = driver.crop(crop, screenshot_image) if crop
 
-        driver.save_image_to(resized_image, file_name)
+        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.'
+                 '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)
+        wait_images_loaded(timeout: timeout) if timeout
 
-        blurred_input = if Screenshot.blur_active_element
-          BrowserHelpers.blur_from_focused_element
-        end
+        blurred_input = BrowserHelpers.blur_from_focused_element if Screenshot.blur_active_element
 
         if Screenshot.hide_caret
           BrowserHelpers.hide_caret
@@ -113,13 +78,15 @@ module Capybara
       end
 
       def wait_images_loaded(timeout:)
-        start = Time.now
+        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 (Time.now - start) >= timeout
-            raise Capybara::Screenshot::Diff::ASSERTION, "Images not loaded after #{timeout}s: #{pending_image.inspect}"
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline_at
+            raise CapybaraScreenshotDiff::ExpectationNotMet, "Images have not been loaded after #{timeout}s: #{pending_image.inspect}"
           end
 
           sleep 0.025
@@ -128,6 +95,31 @@ module Capybara
 
       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
+        File.unlink(tmpfile) if tmpfile
+      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 = 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? && Screenshot.window_size
       end

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

@@ -8,97 +8,99 @@ module Capybara
 
         attr_reader :stability_time_limit, :wait
 
-        def initialize(capture_options, comparison_options = nil)
-          @stability_time_limit, @wait = capture_options.fetch_values(:stability_time_limit, :wait)
-          @comparison_options = comparison_options || Diff.default_options
-          @screenshoter = Diff.screenshoter.new(capture_options.except(*STABILITY_OPTIONS), @comparison_options[:driver])
+        # 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 = {})
+          @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
+
+          driver = Diff::Drivers.for(@comparison_options)
+          @screenshoter = Diff.screenshoter.new(capture_options.except(:stability_time_limit), 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
-        def take_comparison_screenshot(screenshot_path)
-          new_screenshot_path = take_stable_screenshot(screenshot_path)
+        # 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 [RuntimeError] 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 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)
+        def take_stable_screenshot(snapshot)
           # We try to compare first attempt with checkout version, in order to not run next screenshots
-          attempt_path = nil
-          screenshot_started_at = last_attempt_at = Time.now
+          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|
-            # Prevents redundant screenshots generations
-            sleep(stability_time_limit) unless i == 0
-
-            elapsed_time = last_attempt_at - screenshot_started_at
-
-            prev_attempt_path = attempt_path
-            attempt_path = Screenshoter.gen_next_attempt_path(screenshot_path, i)
-
-            @screenshoter.take_screenshot(attempt_path)
-            last_attempt_at = Time.now
+            # FIXME: it should be wait, and wait should be replaced with stability_time_limit
+            sleep(stability_time_limit) unless i == 0 # test prev_attempt_path is nil
 
-            next unless prev_attempt_path
-            stabilization_comparator = build_comparison_for(attempt_path, prev_attempt_path)
+            attempt_next_screenshot(snapshot)
 
-            # If previous screenshot is equal to the current, then we are good
-            return attempt_path if prev_attempt_path && stabilization_comparator.quick_equal?
-
-            # If timeout then we failed to generate valid screenshot
-            return nil if timeout?(elapsed_time)
+            return true if attempt_successful?(snapshot)
+            return false if timeout?(deadline_at)
           end
         end
 
         private
 
-        def build_comparison_for(attempt_path, previous_attempt_path)
-          ImageCompare.new(attempt_path, previous_attempt_path, @comparison_options)
-        end
-
-        def annotate_attempts_and_fail!(screenshot_path)
-          screenshot_attempts = Screenshoter.attempts_screenshot_paths(screenshot_path)
-
-          annotate_stabilization_images(screenshot_attempts)
+        def attempt_successful?(snapshot)
+          return false unless snapshot.prev_attempt_path
 
-          # TODO: Move fail to the queue after tests passed
-          fail("Could not get stable screenshot within #{wait}s:\n#{screenshot_attempts.join("\n")}")
+          build_last_attempts_comparison_for(snapshot).quick_equal?
+        rescue ArgumentError
+          false
         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.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
+        def attempt_next_screenshot(snapshot)
+          @screenshoter.take_screenshot(snapshot.next_attempt_path!)
+        end
 
-              FileUtils.rm(attempts_comparison.annotated_image_path, force: true)
-            end
+        def timeout?(deadline_at)
+          Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline_at
+        end
 
-            previous_file = file_name
-          end
+        def build_last_attempts_comparison_for(snapshot)
+          ImageCompare.new(snapshot.attempt_path, snapshot.prev_attempt_path, @comparison_options)
         end
 
-        def timeout?(elapsed_time)
-          elapsed_time > wait
+        # TODO: Move to the HistoricalReporter
+        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(attempts_reporter.generate)
         end
       end
     end