capybara-screenshot-diff 1.7.0 → 1.8.0

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative "screenshoter"
+require_relative "stable_screenshoter"
+require_relative "browser_helpers"
+require_relative "vcs"
+
+module Capybara
+  module Screenshot
+    module Diff
+      class ScreenshotMatcher
+        attr_reader :screenshot_full_name, :driver_options, :screenshot_path, :base_screenshot_path
+
+        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)
+        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)
+
+          # 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)
+
+          create_output_directory_for(screenshot_path) unless screenshot_path.exist?
+
+          checkout_base_screenshot
+
+          capture_options = {
+            crop: crop,
+            stability_time_limit: driver_options.delete(:stability_time_limit),
+            wait: driver_options.delete(:wait)
+          }
+
+          take_comparison_screenshot(capture_options, driver_options, screenshot_path)
+
+          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)
+        end
+
+        def self.base_image_path_from(screenshot_path)
+          screenshot_path.sub_ext(".base.png")
+        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
+        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)
+        end
+
+        def build_screenshoter_for(capture_options, comparison_options = {})
+          if capture_options[:stability_time_limit]
+            StableScreenshoter.new(capture_options, comparison_options)
+          else
+            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
+end

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

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative "os"
+require_relative "browser_helpers"
+
+module Capybara
+  module Screenshot
+    class Screenshoter
+      attr_reader :capture_options, :comparison_options, :driver
+
+      def initialize(capture_options, driver)
+        @capture_options = capture_options
+        @comparison_options = comparison_options
+        @driver = driver
+      end
+
+      def crop
+        @capture_options[:crop]
+      end
+
+      def wait
+        @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)
+      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)
+      end
+
+      def self.gen_next_attempt_path(screenshot_path, iteration)
+        Pathname.new(screenshot_path).sub_ext(format(".attempt_%02i.png", iteration))
+      end
+
+      def take_screenshot(screenshot_path)
+        blurred_input = prepare_page_for_screenshot(timeout: wait)
+
+        # Take browser screenshot and save
+        browser_save_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(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
+        # 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)
+
+        driver.save_image_to(resized_image, file_name)
+      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)
+
+        blurred_input = if Screenshot.blur_active_element
+          BrowserHelpers.blur_from_focused_element
+        end
+
+        if Screenshot.hide_caret
+          BrowserHelpers.hide_caret
+        end
+
+        blurred_input
+      end
+
+      def wait_images_loaded(timeout:)
+        start = Time.now
+        loop do
+          pending_image = BrowserHelpers.pending_image_to_load
+          break unless pending_image
+
+          assert(
+            (Time.now - start) < timeout,
+            "Images not loaded after #{timeout}s: #{pending_image.inspect}"
+          )
+
+          sleep 0.025
+        end
+      end
+
+      private
+
+      def selenium_with_retina_screen?
+        Os::ON_MAC && BrowserHelpers.selenium? && Screenshot.window_size
+      end
+    end
+  end
+end

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

@@ -1,184 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "os"
-
-module Capybara
-  module Screenshot
-    module Diff
-      module Stabilization
-        include Os
-
-        def take_stable_screenshot(comparison, stability_time_limit:, wait:, crop:)
-          previous_file_name = comparison.old_file_name
-          screenshot_started_at = last_image_change_at = Time.now
-          clean_stabilization_images(comparison.new_file_name)
-
-          1.step do |i|
-            take_right_size_screenshot(comparison, crop: crop)
-            if comparison.quick_equal?
-              clean_stabilization_images(comparison.new_file_name)
-              break
-            end
-
-            comparison.reset
-
-            if previous_file_name
-              stabilization_comparison = make_stabilization_comparison_from(
-                comparison,
-                comparison.new_file_name,
-                previous_file_name
-              )
-              if stabilization_comparison.quick_equal?
-                if (Time.now - last_image_change_at) > stability_time_limit
-                  clean_stabilization_images(comparison.new_file_name)
-                  break
-                end
-                next
-              else
-                last_image_change_at = Time.now
-              end
-            end
-
-            previous_file_name = build_snapshot_version_file_name(
-              comparison,
-              i,
-              screenshot_started_at,
-              stabilization_comparison
-            )
-
-            FileUtils.mv(comparison.new_file_name, previous_file_name)
-
-            check_max_wait_time(
-              comparison,
-              screenshot_started_at,
-              max_wait_time: max_wait_time(comparison.shift_distance_limit, wait)
-            )
-          end
-        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
-
-        private
-
-        def build_snapshot_version_file_name(comparison, iteration, screenshot_started_at, stabilization_comparison)
-          "#{comparison.new_file_name.chomp(".png")}" \
-                "_x#{format("%02i", iteration)}_#{(Time.now - screenshot_started_at).round(1)}s" \
-                "_#{stabilization_comparison.difference_coordinates&.to_s&.gsub(", ", "_") || :initial}.png" \
-                "#{ImageCompare::TMP_FILE_SUFFIX}"
-        end
-
-        def make_stabilization_comparison_from(comparison, new_file_name, previous_file_name)
-          ImageCompare.new(new_file_name, previous_file_name, comparison.driver_options)
-        end
-
-        def reduce_retina_image_size(file_name, driver)
-          return if !ON_MAC || !selenium? || !Capybara::Screenshot.window_size
-
-          expected_image_width = Capybara::Screenshot.window_size[0]
-          saved_image = driver.from_file(file_name)
-          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)
-
-          driver.save_image_to(resized_image, file_name)
-        end
-
-        def stabilization_images(base_file)
-          Dir["#{base_file.chomp(".png")}_x*.png#{ImageCompare::TMP_FILE_SUFFIX}"].sort
-        end
-
-        def clean_stabilization_images(base_file)
-          FileUtils.rm stabilization_images(base_file)
-        end
-
-        def prepare_page_for_screenshot(timeout:)
-          assert_images_loaded(timeout: timeout)
-
-          if Capybara::Screenshot.blur_active_element
-            blurred_input = blur_from_focused_element
-          end
-
-          if Capybara::Screenshot.hide_caret
-            hide_caret
-          end
-
-          blurred_input
-        end
-
-        def take_right_size_screenshot(comparison, crop:)
-          driver = comparison.driver
-
-          save_screenshot(comparison.new_file_name)
-
-          # TODO(uwe): Remove when chromedriver takes right size screenshots
-          reduce_retina_image_size(comparison.new_file_name, driver)
-          # ODOT
-
-          if crop
-            image = driver.from_file(comparison.new_file_name)
-            cropped_image = driver.crop(crop, image)
-            driver.save_image_to(cropped_image, comparison.new_file_name)
-          end
-        end
-
-        def check_max_wait_time(comparison, screenshot_started_at, max_wait_time:)
-          return if (Time.now - screenshot_started_at) < max_wait_time
-
-          annotate_stabilization_images(comparison)
-          # FIXME(uwe): Change to store the failure and only report if the test succeeds functionally.
-          fail("Could not get stable screenshot within #{max_wait_time}s\n" \
-                    "#{stabilization_images(comparison.new_file_name).join("\n")}")
-        end
-
-        def annotate_stabilization_images(comparison)
-          previous_file = comparison.old_file_name
-          stabilization_images(comparison.new_file_name).each do |file_name|
-            if File.exist? previous_file
-              stabilization_comparison = make_stabilization_comparison_from(
-                comparison,
-                file_name,
-                previous_file
-              )
-              if stabilization_comparison.different?
-                FileUtils.mv stabilization_comparison.annotated_new_file_name, file_name
-              end
-              FileUtils.rm stabilization_comparison.annotated_old_file_name
-            end
-            previous_file = file_name
-          end
-        end
-
-        def max_wait_time(shift_distance_limit, wait)
-          shift_factor = shift_distance_limit ? (shift_distance_limit * 2 + 1) ^ 2 : 1
-          wait * shift_factor
-        end
-
-        def assert_images_loaded(timeout:)
-          return unless respond_to? :evaluate_script
-
-          start = Time.now
-          loop do
-            pending_image = pending_image_to_load
-            break unless pending_image
-
-            assert(
-              (Time.now - start) < timeout,
-              "Images not loaded after #{timeout}s: #{pending_image.inspect}"
-            )
-
-            sleep 0.1
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Screenshot
+    module Diff
+      class StableScreenshoter
+        STABILITY_OPTIONS = [:stability_time_limit, :wait]
+
+        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])
+        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)
+
+          # We failed to get stable browser state! Generate difference between attempts to overview moving parts!
+          unless new_screenshot_path
+            # FIXME(uwe): Change to store the failure and only report if the test succeeds functionally.
+            annotate_attempts_and_fail!(screenshot_path)
+          end
+
+          FileUtils.mv(new_screenshot_path, screenshot_path, force: true)
+          Screenshoter.cleanup_attempts_screenshots(screenshot_path)
+        end
+
+        def take_stable_screenshot(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
+
+          # Cleanup all previous attempts for sure
+          Screenshoter.cleanup_attempts_screenshots(screenshot_path)
+
+          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
+
+            next unless prev_attempt_path
+            stabilization_comparator = build_comparison_for(attempt_path, prev_attempt_path)
+
+            # 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)
+          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)
+
+          # TODO: Move fail to the queue after tests passed
+          fail("Could not get stable screenshot within #{wait}s:\n#{screenshot_attempts.join("\n")}")
+        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
+
+              FileUtils.rm(attempts_comparison.annotated_image_path, force: true)
+            end
+
+            previous_file = file_name
+          end
+        end
+
+        def timeout?(elapsed_time)
+          elapsed_time > wait
+        end
+      end
+    end
+  end
+end