eyes_selenium 2.15.0 → 2.16.0

data/lib/applitools/eyes_logger.rb

@@ -0,0 +1,40 @@
+require 'logger'
+require 'forwardable'
+
+module Applitools::EyesLogger
+  class NullLogger < Logger
+    def initialize(*args)
+    end
+
+    def add(*args, &block)
+    end
+  end
+
+  extend Forwardable
+  extend self
+
+  MANDATORY_METHODS = [:debug, :info, :close].freeze
+  OPTIONAL_METHODS = [:warn, :error, :fatal].freeze
+
+  def_delegators :@@log_handler, *MANDATORY_METHODS
+
+  @@log_handler = NullLogger.new
+
+  def log_handler=(log_handler)
+    raise Applitools::EyesError.new('log_handler must implement Logger!') unless valid?(log_handler)
+
+    @@log_handler = log_handler
+  end
+
+  OPTIONAL_METHODS.each do |method|
+    define_singleton_method(method) do |msg|
+      @@log_handler.respond_to?(method) ? @@log_handler.send(method, msg) : @@log_handler.info(msg)
+    end
+  end
+
+  private
+
+  def valid?(log_handler)
+    MANDATORY_METHODS.all? {|method| log_handler.respond_to?(method)}
+  end
+end

data/lib/applitools/method_tracer.rb

@@ -0,0 +1,22 @@
+module Applitools::MethodTracer
+  def self.included(base)
+    instance_methods = base.instance_methods(false) + base.private_instance_methods(false)
+    class_methods = base.methods(false)
+
+    base.class_eval do
+      def self.trace_method(base, method_name, instance = true)
+        original_method = instance ? instance_method(method_name) : method(method_name)
+
+        send(instance ? :define_method : :define_singleton_method, method_name) do |*args, &block|
+          Applitools::EyesLogger.debug "-> #{base}##{method_name}"
+          return_value = (instance ? original_method.bind(self) : original_method).call(*args, &block)
+          Applitools::EyesLogger.debug "<- #{base}##{method_name}"
+          return_value
+        end
+      end
+
+      instance_methods.each {|method_name| trace_method(base, method_name) }
+      class_methods.each {|method_name| trace_method(base, method_name, false) }
+    end
+  end
+end

data/lib/applitools/selenium/driver.rb

@@ -0,0 +1,194 @@
+require 'forwardable'
+require 'socket'
+require 'selenium-webdriver'
+
+module Applitools::Selenium
+  class Driver < SimpleDelegator
+    extend Forwardable
+
+    include Selenium::WebDriver::DriverExtensions::HasInputDevices
+
+    RIGHT_ANGLE = 90.freeze
+    ANDROID = 'ANDROID'.freeze
+    IOS = 'IOS'.freeze
+    LANDSCAPE = 'LANDSCAPE'.freeze
+
+    IE = 'ie'.freeze
+    FIREFOX = 'firefox'.freeze
+
+    FINDERS = {
+      class: 'class name',
+      class_name: 'class name',
+      css: 'css selector',
+      id: 'id',
+      link: 'link text',
+      link_text: 'link text',
+      name: 'name',
+      partial_link_text: 'partial link text',
+      tag_name: 'tag name',
+      xpath: 'xpath'
+    }.freeze
+
+    JS_GET_USER_AGENT = 'return navigator.userAgent;'.freeze
+
+    def_delegators :@eyes, :user_inputs, :clear_user_inputs
+
+    # If driver is not provided, Applitools::Selenium::Driver will raise an EyesError exception.
+    def initialize(eyes, options)
+      super(options[:driver])
+
+      @is_mobile_device = options.fetch(:is_mobile_device, false)
+      @eyes = eyes
+
+      raise 'Uncapable of taking screenshots!' unless capabilities.takes_screenshot?
+    end
+
+    # Rotates the image as necessary. The rotation is either manually forced by passing a value in
+    # the +rotation+ parameter, or automatically inferred if the +rotation+ parameter is +nil+.
+    #
+    # +driver+:: +Applitools::Selenium::Driver+ The driver which produced the screenshot.
+    # +image+:: +ChunkyPNG::Canvas+ The image to normalize.
+    # +rotation+:: +Integer+|+nil+ The degrees by which to rotate the image: positive values = clockwise rotation,
+    #   negative values = counter-clockwise, 0 = force no rotation, +nil+ = rotate automatically when needed.
+    def self.normalize_rotation(driver, image, rotation)
+      return if rotation == 0
+
+      num_quadrants = 0
+      if !rotation.nil?
+        if rotation % RIGHT_ANGLE != 0
+          raise Applitools::EyesError.new("Currently only quadrant rotations are supported. Current rotation: "\
+            "#{rotation}")
+        end
+        num_quadrants = (rotation / RIGHT_ANGLE).to_i
+      elsif rotation.nil? && driver.mobile_device? && driver.landscape_orientation? && image.height > image.width
+        # For Android, we need to rotate images to the right, and for iOS to the left.
+        num_quadrants = driver.android? ? 1 : -1
+      end
+
+      Applitools::Utils::ImageUtils.quadrant_rotate!(image, num_quadrants)
+    end
+
+    # Returns:
+    # +String+ The platform name or +nil+ if it is undefined.
+    def platform_name
+      capabilities['platformName']
+    end
+
+    # Returns:
+    # +String+ The platform version or +nil+ if it is undefined.
+    def platform_version
+      version = capabilities['platformVersion']
+      version.nil? ? nil : version.to_s
+    end
+
+    # Returns:
+    # +true+ if the driver is an Android driver.
+    def android?
+      platform_name.to_s.upcase == ANDROID
+    end
+
+    # Returns:
+    # +true+ if the driver is an iOS driver.
+    def ios?
+      platform_name.to_s.upcase == IOS
+    end
+
+    # Returns:
+    # +true+ if the driver orientation is landscape.
+    def landscape_orientation?
+      begin
+        driver.orientation.to_s.upcase == LANDSCAPE
+      rescue NameError
+        Applitools::EyesLogger.debug 'driver has no "orientation" attribute. Assuming: portrait.'
+      end
+    end
+
+    # Returns:
+    # +true+ if the platform running the test is a mobile platform. +false+ otherwise.
+    def mobile_device?
+      # We CAN'T check if the device is an +Appium::Driver+ since it is not a RemoteWebDriver. Because of that we use a
+      # flag we got as an option in the constructor.
+      @is_mobile_device
+    end
+
+    # Return a PNG screenshot in the given format as a string
+    #
+    # +output_type+:: +Symbol+ The format of the screenshot. Accepted values are +:base64+ and +:png+.
+    # +rotation+:: +Integer+|+nil+ The degrees by which to rotate the image: positive values = clockwise rotation,
+    #   negative values = counter-clockwise, 0 = force no rotation, +nil+ = rotate automatically when needed.
+    #
+    # Returns: +String+ A screenshot in the requested format.
+    def screenshot_as(output_type, rotation = nil)
+      screenshot = Applitools::Utils::ImageUtils.png_image_from_base64(driver.screenshot_as(:base64))
+      Applitools::Selenium::Driver.normalize_rotation(self, screenshot, rotation)
+
+      case output_type
+      when :base64
+        screenshot = Applitools::Utils::ImageUtils.base64_from_png_image(screenshot)
+      when :png
+        screenshot = Applitools::Utils::ImageUtils.bytes_from_png_image(screenshot)
+      else
+        raise Applitools::EyesError.new("Unsupported screenshot output type: #{output_type.to_s}")
+      end
+
+      screenshot.force_encoding('BINARY')
+    end
+
+    def mouse
+      Applitools::Selenium::Mouse.new(self, driver.mouse)
+    end
+
+    def keyboard
+      Applitools::Selenium::Keyboard.new(self, driver.keyboard)
+    end
+
+    def find_element(*args)
+      how, what = extract_args(args)
+
+      # Make sure that "how" is a valid locator.
+      raise ArgumentError, "cannot find element by: #{how.inspect}" unless FINDERS[how.to_sym]
+
+      Applitools::Selenium::Element.new(self, driver.find_element(how, what))
+    end
+
+    def find_elements(*args)
+      how, what = extract_args(args)
+
+      raise ArgumentError, "cannot find element by: #{how.inspect}" unless FINDERS[how.to_sym]
+
+      driver.find_elements(how, what).map { |el| Applitools::Selenium::Element.new(self, el) }
+    end
+
+    def user_agent
+      @user_agent ||= execute_script JS_GET_USER_AGENT
+    rescue => e
+      Applitools::EyesLogger.error "Failed to obtain user-agent string (#{e.message})"
+
+      nil
+    end
+
+    private
+
+    def driver
+      @driver ||= __getobj__
+    end
+
+    def extract_args(args)
+      case args.size
+      when 2
+        args
+      when 1
+        arg = args.first
+
+        raise Argu mentError, "expected #{arg.inspect}:#{arg.class} to respond to #shift" unless arg.respond_to?(:shift)
+
+        # This will be a single-entry hash, so use #shift over #first or #[].
+        arg.dup.shift.tap do |arr|
+          raise ArgumentError, "expected #{arr.inspect} to have 2 elements" unless arr.size == 2
+        end
+      else
+        raise ArgumentError, "wrong number of arguments (#{args.size} for 2)"
+      end
+    end
+  end
+end

data/lib/applitools/selenium/element.rb

@@ -0,0 +1,66 @@
+module Applitools::Selenium
+  class Element < SimpleDelegator
+    TRACE_PREFIX = 'EyesWebElement'.freeze
+
+    def initialize(driver, element)
+      super(element)
+
+      @driver = driver
+    end
+
+    def web_element
+      @web_element ||= __getobj__
+    end
+
+    def click
+      current_control = region
+      offset = current_control.middle_offset
+      @driver.user_inputs << Applitools::Base::MouseTrigger.new(:click, current_control, offset)
+
+      web_element.click
+    end
+
+    def inspect
+      TRACE_PREFIX + web_element.inspect
+    end
+
+    def ==(other)
+      other.kind_of?(web_element.class) && web_element == other
+    end
+    alias_method :eql?, :==
+
+    def send_keys(*args)
+      current_control = region
+      Selenium::WebDriver::Keys.encode(args).each do |key|
+        @driver.user_inputs << Applitools::Base::TextTrigger.new(key.to_s, current_control)
+      end
+
+      web_element.send_keys(*args)
+    end
+    alias_method :send_key, :send_keys
+
+    def region
+      point = location
+      left, top, width, height  = point.x, point.y, 0, 0
+
+      begin
+        dimension = size
+        width, height = dimension.width, dimension.height
+      rescue
+        # Not supported on all platforms.
+      end
+
+      if left < 0
+        width = [0, width + left].max
+        left = 0
+      end
+
+      if top < 0
+        height = [0, height + top].max
+        top = 0
+      end
+
+      return Applitools::Base::Region.new(left, top, width, height)
+    end
+  end
+end

data/lib/applitools/selenium/keyboard.rb

@@ -0,0 +1,27 @@
+module Applitools::Selenium
+  class Keyboard
+    attr_reader :keyboard, :driver
+
+    def initialize(driver, keyboard)
+      @driver = driver
+      @keyboard = keyboard
+    end
+
+    def send_keys(*keys)
+      active_element = Applitools::Selenium::Element.new(driver, driver.switch_to.active_element)
+      current_control = active_element.region
+      Selenium::WebDriver::Keys.encode(keys).each do |key|
+        driver.user_inputs << Applitools::Base::TextTrigger.new(key.to_s, current_control)
+      end
+      keyboard.send_keys(*keys)
+    end
+
+    def press(key)
+      keyboard.press(key)
+    end
+
+    def release(key)
+      keyboard.release(key)
+    end
+  end
+end

data/lib/applitools/selenium/match_window_data.rb

@@ -0,0 +1,24 @@
+module Applitools::Selenium
+  class MatchWindowData
+    attr_reader :user_inputs, :app_output, :tag, :ignore_mismatch, :screenshot
+
+    def initialize(app_output, user_inputs = [], tag, ignore_mismatch, screenshot)
+      @user_inputs = user_inputs
+      @app_output = app_output
+      @tag = tag
+      @ignore_mismatch = ignore_mismatch
+      @screenshot = screenshot
+    end
+
+    # IMPORTANT This method returns a hash WITHOUT the screenshot property. This is on purspose! The screenshot should
+    # not be included as part of the json.
+    def to_hash
+      {
+        user_inputs: user_inputs.map(&:to_hash),
+        app_output: Hash[app_output.each_pair.to_a],
+        tag: @tag,
+        ignore_mismatch: @ignore_mismatch
+      }
+    end
+  end
+end

data/lib/applitools/selenium/match_window_task.rb

@@ -0,0 +1,190 @@
+require 'base64'
+
+module Applitools::Selenium
+  class MatchWindowTask
+    MATCH_INTERVAL = 0.5.freeze
+    AppOuptut = Struct.new(:title, :screenshot64)
+
+    attr_reader :eyes, :session, :driver, :default_retry_timeout, :last_checked_window,
+      :last_screenshot_bounds
+
+    def initialize(eyes, session, driver, default_retry_timeout)
+      @eyes = eyes
+
+      @session = session
+      @driver = driver
+      @default_retry_timeout = default_retry_timeout
+      @last_checked_window = nil # +ChunkyPNG::Canvas+
+      @last_screenshot_bounds = Applitools::Base::Region::EMPTY # +Applitools::Base::Region+
+      @current_screenshot = nil # +ChunkyPNG::Canvas+
+    end
+
+    def match_window(region, retry_timeout, tag, rotation, run_once_after_wait = false)
+      retry_timeout = default_retry_timeout if retry_timeout < 0
+
+      Applitools::EyesLogger.debug "Retry timeout set to: #{retry_timeout}"
+
+      start = Time.now
+      res = if retry_timeout.zero?
+        run(region, tag, rotation)
+      elsif run_once_after_wait
+        run(region, tag, rotation, retry_timeout)
+      else
+        run_with_intervals(region, tag, rotation, retry_timeout)
+      end
+      elapsed_time = Time.now - start
+
+      Applitools::EyesLogger.debug "match_window(): Completed in #{format('%.2f', elapsed_time)} seconds"
+
+      @last_checked_window = @current_screenshot
+      @last_screenshot_bounds = region.empty? ? Applitools::Base::Region.new(0, 0, last_checked_window.width,
+        last_checked_window.height) : region
+      driver.clear_user_inputs
+
+      res
+    end
+
+    def run(region, tag, rotation, wait_before_run=nil)
+      Applitools::EyesLogger.debug 'Trying matching once...'
+
+      if wait_before_run
+        Applitools::EyesLogger.debug 'Waiting before run...'
+        sleep(wait_before_run)
+        Applitools::EyesLogger.debug 'Wwaiting done!'
+      end
+
+      match(region, tag, rotation)
+    end
+
+    def run_with_intervals(region, tag, rotation, retry_timeout)
+      # We intentionally take the first screenshot before starting the timer, to allow the page just a tad more time to
+      # stabilize.
+      Applitools::EyesLogger.debug 'Matching with intervals...'
+      data = prep_match_data(region, tag, rotation, true)
+      start = Time.now
+      as_expected = Applitools::Base::ServerConnector.match_window(session, data)
+      Applitools::EyesLogger.debug "First call result: #{as_expected}"
+      return true if as_expected
+      Applitools::EyesLogger.debug "Not as expected, performing retry (total timeout #{retry_timeout})"
+      match_retry = Time.now - start
+      while match_retry < retry_timeout
+        Applitools::EyesLogger.debug 'Waiting before match...'
+        sleep(MATCH_INTERVAL)
+        Applitools::EyesLogger.debug 'Done! Matching...'
+        return true if match(region, tag, rotation, true)
+        match_retry = Time.now - start
+        Applitools::EyesLogger.debug "Elapsed time: #{match_retry}"
+      end
+      # Let's try one more time if we still don't have a match.
+      Applitools::EyesLogger.debug 'Last attempt to match...'
+      as_expected = match(region, tag, rotation)
+      Applitools::EyesLogger.debug "Match result: #{as_expected}"
+      as_expected
+    end
+
+    private
+
+    def get_clipped_region(region, image)
+      left, top = [region.left, 0].max, [region.top, 0].max
+      max_width = image.width - left
+      max_height = image.height - top
+      width, height = [region.width, max_width].min, [region.height, max_height].min
+      Applitools::Base::Region.new(left, top, width, height)
+    end
+
+    def prep_match_data(region, tag, rotation, ignore_mismatch)
+      Applitools::EyesLogger.debug 'Preparing match data...'
+      title = eyes.title
+      Applitools::EyesLogger.debug 'Getting screenshot...'
+      current_screenshot_encoded = driver.screenshot_as(:png, rotation)
+      Applitools::EyesLogger.debug 'Done! Creating image object from PNG...'
+      @current_screenshot = ChunkyPNG::Image.from_blob(current_screenshot_encoded)
+      Applitools::EyesLogger.debug 'Done!'
+      # If a region was defined, we refer to the sub-image defined by the region.
+      unless region.empty?
+        Applitools::EyesLogger.debug 'Calculating clipped region...'
+        # If the region is out of bounds, clip it
+        clipped_region = get_clipped_region(region, @current_screenshot)
+        raise Applitools::EyesError.new("Region is outside the viewport: #{region}") if clipped_region.empty?
+        Applitools::EyesLogger.debug 'Done! Cropping region...'
+        @current_screenshot.crop!(clipped_region.left, clipped_region.top, clipped_region.width, clipped_region.height)
+        Applitools::EyesLogger.debug 'Done! Creating cropped image object...'
+        current_screenshot_encoded = @current_screenshot.to_blob.force_encoding('BINARY')
+        Applitools::EyesLogger.debug 'Done!'
+      end
+      Applitools::EyesLogger.debug 'Compressing screenshot...'
+      compressed_screenshot = Applitools::Utils::ImageDeltaCompressor.compress_by_raw_blocks(@current_screenshot,
+        current_screenshot_encoded, last_checked_window)
+      Applitools::EyesLogger.debug 'Done! Creating AppOuptut...'
+      app_output = AppOuptut.new(title, nil)
+      user_inputs = []
+      Applitools::EyesLogger.debug 'Handling user inputs...'
+      if !last_checked_window.nil?
+        driver.user_inputs.each do |trigger|
+          Applitools::EyesLogger.debug 'Handling trigger...'
+          if trigger.is_a?(Applitools::Base::MouseTrigger)
+            updated_trigger = nil
+            trigger_left = trigger.control.left + trigger.location.x
+            trigger_top = trigger.control.top + trigger.location.y
+            if last_screenshot_bounds.contains?(trigger_left, trigger_top)
+              trigger.control.intersect(last_screenshot_bounds)
+              if trigger.control.empty?
+                trigger_left -= - last_screenshot_bounds.left
+                trigger_top = trigger_top - last_screenshot_bounds.top
+                updated_trigger = Applitools::Base::MouseTrigger.new(trigger.mouse_action, trigger.control,
+                  Applitools::Base::Point.new(trigger_left, trigger_top))
+              else
+                trigger_left = trigger_left - trigger.control.left
+                trigger_top = trigger_top - trigger.control.top
+                control_left = trigger.control.left - last_screenshot_bounds.left
+                control_top = trigger.control.top - last_screenshot_bounds.top
+                updated_control = Applitools::Base::Region.new(control_left, control_top, trigger.control.width,
+                  trigger.control.height)
+                updated_trigger = Applitools::Base::MouseTrigger.new(trigger.mouse_action, updated_control,
+                  Applitools::Base::Point.new(trigger_left, trigger_top))
+              end
+              Applitools::EyesLogger.debug 'Done with trigger!'
+              user_inputs << updated_trigger
+            else
+              Applitools::EyesLogger.info "Trigger ignored: #{trigger} (out of bounds)"
+            end
+          elsif trigger.is_a?(Applitools::Base::TextTrigger)
+            unless trigger.control.empty?
+              trigger.control.intersect(last_screenshot_bounds)
+              unless trigger.control.empty?
+                control_left = trigger.control.left - last_screenshot_bounds.left
+                control_top = trigger.control.top - last_screenshot_bounds.top
+                updated_control = Applitools::Base::Region.new(control_left, control_top, trigger.control.width,
+                  trigger.control.height)
+                updated_trigger = Applitools::Base::TextTrigger.new(trigger.text, updated_control)
+                Applitools::EyesLogger.debug 'Done with trigger!'
+                user_inputs << updated_trigger
+              else
+                Applitools::EyesLogger.info "Trigger ignored: #{trigger} (control out of bounds)"
+              end
+            else
+              Applitools::EyesLogger.info "Trigger ignored: #{trigger} (out of bounds)"
+            end
+          else
+            Applitools::EyesLogger.info "Trigger ignored: #{trigger} (Unrecognized trigger)"
+          end
+        end
+      else
+        Applitools::EyesLogger.info 'Triggers ignored: no previous window checked'
+      end
+      Applitools::EyesLogger.debug 'Creating MatchWindowData object..'
+      match_window_data_obj = Applitools::Selenium::MatchWindowData.new(app_output, user_inputs, tag, ignore_mismatch,
+        compressed_screenshot)
+      Applitools::EyesLogger.debug 'Done creating MatchWindowData object!'
+      match_window_data_obj
+    end
+
+    def match(region, tag, rotation, ignore_mismatch=false)
+      Applitools::EyesLogger.debug 'Match called...'
+      data = prep_match_data(region, tag, rotation, ignore_mismatch)
+      match_result = Applitools::Base::ServerConnector.match_window(session, data)
+      Applitools::EyesLogger.debug 'Match done!'
+      match_result
+    end
+  end
+end