capybara-screenshot-diff 1.8.3 → 1.9.0

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

@@ -4,18 +4,20 @@ 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_path, :base_screenshot_path, :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")
+          @screenshot_format = @driver_options[:screenshot_format]
+          @screenshot_path = Screenshot.screenshot_area_abs / Pathname.new(screenshot_full_name).sub_ext(".#{screenshot_format}")
           @base_screenshot_path = ScreenshotMatcher.base_image_path_from(@screenshot_path)
         end
 
@@ -23,46 +25,47 @@ module Capybara
           # 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])
 
+          # Load base screenshot from VCS
           create_output_directory_for(screenshot_path) unless screenshot_path.exist?
 
           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 && !base_screenshot_path.exist?
+
           capture_options = {
-            crop: crop,
+            # 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)
           }
 
+          # Load new screenshot from Browser
           take_comparison_screenshot(capture_options, driver_options, screenshot_path)
 
+          # Pre-computation: No need to compare without base screenshot
           return unless base_screenshot_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)
+          [screenshot_full_name, ImageCompare.new(screenshot_path, base_screenshot_path, driver_options)]
         end
 
         def self.base_image_path_from(screenshot_path)
-          screenshot_path.sub_ext(".base.png")
+          screenshot_path.sub_ext(".base#{screenshot_path.extname}")
         end
 
         private
@@ -71,14 +74,6 @@ module Capybara
           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
         end
@@ -98,30 +93,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

@@ -22,8 +22,17 @@ module Capybara
         @capture_options[:wait]
       end
 
+      def screenshot_format
+        @capture_options[:screenshot_format] || "png"
+      end
+
+      def capybara_screenshot_options
+        @capture_options[:capybara_screenshot_options] || {}
+      end
+
       def self.attempts_screenshot_paths(base_file)
-        Dir["#{base_file.to_s.chomp(".png")}.attempt_*.png"].sort
+        extname = Pathname.new(base_file).extname
+        Dir["#{base_file.to_s.chomp(extname)}.attempt_*#{extname}"].sort
       end
 
       def self.cleanup_attempts_screenshots(base_file)
@@ -34,76 +43,51 @@ module Capybara
       # 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)
+        capture_screenshot_at(screenshot_path)
 
-        take_screenshot(new_screenshot_path)
-
-        FileUtils.mv(new_screenshot_path, screenshot_path, force: true)
         Screenshoter.cleanup_attempts_screenshots(screenshot_path)
       end
 
       def self.gen_next_attempt_path(screenshot_path, iteration)
-        Pathname.new(screenshot_path).sub_ext(format(".attempt_%02i.png", iteration))
+        screenshot_path.sub_ext(format(".attempt_%02i#{screenshot_path.extname}", 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
+        screenshot_image = driver.crop(crop, screenshot_image) if crop
 
-        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)
-
-        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 +97,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 +114,39 @@ 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(screenshot_path)
+        new_screenshot_path = Screenshoter.gen_next_attempt_path(screenshot_path, 0)
+        take_and_process_screenshot(new_screenshot_path, screenshot_path)
+      end
+
+      def take_and_process_screenshot(new_screenshot_path, screenshot_path)
+        take_screenshot(new_screenshot_path)
+        move_screenshot_to(new_screenshot_path, screenshot_path)
+      end
+
+      def move_screenshot_to(new_screenshot_path, screenshot_path)
+        FileUtils.mv(new_screenshot_path, screenshot_path, force: true)
+      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,15 +8,36 @@ module Capybara
 
         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)
+
+          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 || Diff.default_options
-          @screenshoter = Diff.screenshoter.new(capture_options.except(*STABILITY_OPTIONS), @comparison_options[:driver])
+
+          driver = Diff::Drivers.for(@comparison_options)
+          @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)
 
@@ -31,42 +52,47 @@ module Capybara
         end
 
         def take_stable_screenshot(screenshot_path)
+          screenshot_path = screenshot_path.is_a?(String) ? Pathname.new(screenshot_path) : screenshot_path
           # 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)
 
           0.step do |i|
-            # Prevents redundant screenshots generations
+            # FIXME: it should be wait, and wait should be replaced with stability_time_limit
             sleep(stability_time_limit) unless i == 0
+            attempt_path, prev_attempt_path = attempt_next_screenshot(attempt_path, i, screenshot_path)
+            return attempt_path if attempt_successful?(attempt_path, prev_attempt_path)
+            return nil if timeout?(deadline_at)
+          end
+        end
 
-            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
-
-            next unless prev_attempt_path
-            stabilization_comparator = build_comparison_for(attempt_path, prev_attempt_path)
+        private
 
-            # If previous screenshot is equal to the current, then we are good
-            return attempt_path if prev_attempt_path && stabilization_comparator.quick_equal?
+        def attempt_successful?(attempt_path, prev_attempt_path)
+          return false unless prev_attempt_path
+          build_comparison_for(attempt_path, prev_attempt_path).quick_equal?
+        rescue ArgumentError
+          false
+        end
 
-            # If timeout then we failed to generate valid screenshot
-            return nil if timeout?(elapsed_time)
-          end
+        def attempt_next_screenshot(prev_attempt_path, i, screenshot_path)
+          new_attempt_path = Screenshoter.gen_next_attempt_path(screenshot_path, i)
+          @screenshoter.take_screenshot(new_attempt_path)
+          [new_attempt_path, prev_attempt_path]
         end
 
-        private
+        def timeout?(deadline_at)
+          Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline_at
+        end
 
         def build_comparison_for(attempt_path, previous_attempt_path)
           ImageCompare.new(attempt_path, previous_attempt_path, @comparison_options)
         end
 
+        # TODO: Move to the HistoricalReporter
         def annotate_attempts_and_fail!(screenshot_path)
           screenshot_attempts = Screenshoter.attempts_screenshot_paths(screenshot_path)
 
@@ -84,22 +110,18 @@ module Capybara
               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)
+                FileUtils.mv(attempts_comparison.reporter.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"
+                       "#{previous_file} and #{file_name} are equal"
               end
 
-              FileUtils.rm(attempts_comparison.annotated_image_path, force: true)
+              FileUtils.rm(attempts_comparison.reporter.annotated_image_path, force: true)
             end
 
             previous_file = file_name
           end
         end
-
-        def timeout?(elapsed_time)
-          elapsed_time > wait
-        end
       end
     end
   end