framework_gem 0.1.0

data/lib/lib/selenium/selenium.rb

@@ -0,0 +1,466 @@
+require 'net/http'
+require 'uri'
+require 'json'
+require './lib/element/element'
+require './lib/helpers/tmc_helpers/tmc_helpers'
+
+# Webdriver defines all the Webdriver methods in a module so that they can be included by other classes
+
+module Selenium
+
+  @id = nil
+  @is_appium = false
+
+  # Public: Gets all elements matching the search criteria.
+  #         For any String criteria, a Regular Expression may be used by adding the 'regexp:' prefix.
+  #
+  # name              - String name of the element (default: nil). Corresponds to Android 'resource-id' and Ios 'name'.
+  # text              - String text of the element (default: nil). Corresponds to Android 'text' and Ios 'value'.
+  # type              - String type of the element (default: nil). Corresponds to element class/tag.
+  # description       - String description of the element (default: nil).
+  #                     Corresponds to Android 'content-desc' and Ios 'label'.
+  # selector          - String automation selector (default: nil).
+  # is_visible        - Boolean indicating whether the element is visible (default: nil).
+  #                     Corresponds to Ios 'visible'. Always true for Android.
+  # is_on_screen      - Boolean indicating whether any part of the element is within screen boundaries (default: nil).
+  # is_tappable       - Boolean indicating whether the element may be tapped (default: nil).
+  #                     Corresponds to Android 'clickable'. Android only.
+  # is_password       - Boolean indicating whether the element is a password field (default: nil).
+  #                     Corresponds to Android 'password'. Android only.
+  # is_enabled        - Boolean indicating whether the element is enabled (default: nil).
+  #                     Corresponds to Android and Ios 'enabled'.
+  # is_checked        - Boolean indicating whether the element is checked (default: nil).
+  #                     Corresponds to Android 'checked'. Android only.
+  # is_selected       - Boolean indicating whether the element is selected (default: nil).
+  #                     Corresponds to Android 'selected'.
+  # is_checkable      - Boolean indicating whether the element can be checked (default: nil).
+  #                     Corresponds to Android 'checkable'. Android only.
+  # is_focusable      - Boolean indicating whether the element can be focused (default: nil).
+  #                     Corresponds to Android 'focusable'. Android only.
+  # is_long_pressable - Boolean indicating whether the element can be long-pressed (default: nil).
+  #                     Corresponds to Android 'long-clickable'. Android only.
+  # is_scrollable     - Boolean indicating whether the element can be scrolled (default: nil).
+  #                     Corresponds to Android 'scrollable'. Android only.
+  # is_recordable     - Boolean indicating whether the element can be recorded (default: nil).
+  # x                 - Integer x coordinate of the element (default: nil).
+  # y                 - Integer y coordinate of the element (default: nil).
+  # width             - Integer width of the element (default: nil).
+  # height            - Integer height of the element (default: nil).
+  # number            - Integer channel number (default: nil). Channel elements only.
+  # start_time        - Integer start time (default: nil). Channel/show elements only.
+  # end_time          - Integer end time (default: nil). Channel/show elements only.
+  # coordinates       - Boolean indicating whether absolute coordinates are given (default: false).
+  # info              - Array of Symbols specifying attributes to retrieve (default: []).
+  #                     By default, all attributes will be retrieved.
+  # min               - Integer minimum number of matching elements to require (default: 0).
+  #                     By default, no restriction is imposed.
+  # max               - Integer maximum number of matching elements to require (default: nil).
+  #                     By default, no restriction is imposed.
+  # timeout           - Integer total milliseconds to allow for element search (default: 30.sec).
+  #
+  # Returns an Array of matching Elements, or nil if no elements matched.
+  def elements(attrs={})
+    elems = (selenium_post('elements', attrs) || {})['elements']
+    if elems.nil?
+      nil
+    elsif attrs.fetch(:info, []).count == 1
+      elems.map {|e| Element.new(e)[attrs[:info].first]}
+    else
+      elems.map {|e| Element.new(e)}
+    end
+  end
+
+  # Public: Check if any elements matched the search criteria.
+  #         For any String criteria, a Regular Expression may be used by adding the 'regexp:' prefix.
+  #
+  # name              - String name of the element (default: nil). Corresponds to Android 'resource-id' and Ios 'name'.
+  # text              - String text of the element (default: nil). Corresponds to Android 'text' and Ios 'value'.
+  # type              - String type of the element (default: nil). Corresponds to element class/tag.
+  # description       - String description of the element (default: nil).
+  #                     Corresponds to Android 'content-desc' and Ios 'label'.
+  # selector          - String automation selector (default: nil).
+  # is_visible        - Boolean indicating whether the element is visible (default: nil).
+  #                     Corresponds to Ios 'visible'. Always true for Android.
+  # is_on_screen      - Boolean indicating whether any part of the element is within screen boundaries (default: nil).
+  # is_tappable       - Boolean indicating whether the element may be tapped (default: nil).
+  #                     Corresponds to Android 'clickable'. Android only.
+  # is_password       - Boolean indicating whether the element is a password field (default: nil).
+  #                     Corresponds to Android 'password'. Android only.
+  # is_enabled        - Boolean indicating whether the element is enabled (default: nil).
+  #                     Corresponds to Android and Ios 'enabled'.
+  # is_checked        - Boolean indicating whether the element is checked (default: nil).
+  #                     Corresponds to Android 'checked'. Android only.
+  # is_selected       - Boolean indicating whether the element is selected (default: nil).
+  #                     Corresponds to Android 'selected'.
+  # is_checkable      - Boolean indicating whether the element can be checked (default: nil).
+  #                     Corresponds to Android 'checkable'. Android only.
+  # is_focusable      - Boolean indicating whether the element can be focused (default: nil).
+  #                     Corresponds to Android 'focusable'. Android only.
+  # is_long_pressable - Boolean indicating whether the element can be long-pressed (default: nil).
+  #                     Corresponds to Android 'long-clickable'. Android only.
+  # is_scrollable     - Boolean indicating whether the element can be scrolled (default: nil).
+  #                     Corresponds to Android 'scrollable'. Android only.
+  # is_recordable     - Boolean indicating whether the element can be recorded (default: nil).
+  # x                 - Integer x coordinate of the element (default: nil).
+  # y                 - Integer y coordinate of the element (default: nil).
+  # width             - Integer width of the element (default: nil).
+  # height            - Integer height of the element (default: nil).
+  # number            - Integer channel number (default: nil). Channel elements only.
+  # start_time        - Integer start time (default: nil). Channel/show elements only.
+  # end_time          - Integer end time (default: nil). Channel/show elements only.
+  # coordinates       - Boolean indicating whether absolute coordinates are given (default: false).
+  # info              - Array of Symbols specifying attributes to retrieve (default: []).
+  #                     By default, all attributes will be retrieved.
+  # min               - Integer minimum number of matching elements to require (default: 0).
+  #                     By default, no restriction is imposed.
+  # max               - Integer maximum number of matching elements to require (default: nil).
+  #                     By default, no restriction is imposed.
+  # timeout           - Integer total milliseconds to allow for element search (default: 30.sec).
+  #
+  # Returns a Boolean true if any elements matched, otherwise false.
+  def elements?(attrs={})
+    attrs[:info] = []
+    elems = elements(attrs)
+    elems.nil? ? false : elems.size > 0
+  end
+
+  # Public: Measures time to find any matching elements.
+  #         For any String criteria, a Regular Expression may be used by adding the 'regexp:' prefix.
+  #
+  # name              - String name of the element (default: nil). Corresponds to Android 'resource-id' and Ios 'name'.
+  # text              - String text of the element (default: nil). Corresponds to Android 'text' and Ios 'value'.
+  # type              - String type of the element (default: nil). Corresponds to element class/tag.
+  # description       - String description of the element (default: nil).
+  #                     Corresponds to Android 'content-desc' and Ios 'label'.
+  # selector          - String automation selector (default: nil).
+  # is_visible        - Boolean indicating whether the element is visible (default: nil).
+  #                     Corresponds to Ios 'visible'. Always true for Android.
+  # is_on_screen      - Boolean indicating whether any part of the element is within screen boundaries (default: nil).
+  # is_tappable       - Boolean indicating whether the element may be tapped (default: nil).
+  #                     Corresponds to Android 'clickable'. Android only.
+  # is_password       - Boolean indicating whether the element is a password field (default: nil).
+  #                     Corresponds to Android 'password'. Android only.
+  # is_enabled        - Boolean indicating whether the element is enabled (default: nil).
+  #                     Corresponds to Android and Ios 'enabled'.
+  # is_checked        - Boolean indicating whether the element is checked (default: nil).
+  #                     Corresponds to Android 'checked'. Android only.
+  # is_selected       - Boolean indicating whether the element is selected (default: nil).
+  #                     Corresponds to Android 'selected'.
+  # is_checkable      - Boolean indicating whether the element can be checked (default: nil).
+  #                     Corresponds to Android 'checkable'. Android only.
+  # is_focusable      - Boolean indicating whether the element can be focused (default: nil).
+  #                     Corresponds to Android 'focusable'. Android only.
+  # is_long_pressable - Boolean indicating whether the element can be long-pressed (default: nil).
+  #                     Corresponds to Android 'long-clickable'. Android only.
+  # is_scrollable     - Boolean indicating whether the element can be scrolled (default: nil).
+  #                     Corresponds to Android 'scrollable'. Android only.
+  # is_recordable     - Boolean indicating whether the element can be recorded (default: nil).
+  # x                 - Integer x coordinate of the element (default: nil).
+  # y                 - Integer y coordinate of the element (default: nil).
+  # width             - Integer width of the element (default: nil).
+  # height            - Integer height of the element (default: nil).
+  # number            - Integer channel number (default: nil). Channel elements only.
+  # start_time        - Integer start time (default: nil). Channel/show elements only.
+  # end_time          - Integer end time (default: nil). Channel/show elements only.
+  # coordinates       - Boolean indicating whether absolute coordinates are given (default: false).
+  # info              - Array of Symbols specifying attributes to retrieve (default: []).
+  #                     By default, all attributes will be retrieved.
+  # min               - Integer minimum number of matching elements to require (default: 0).
+  #                     By default, no restriction is imposed.
+  # max               - Integer maximum number of matching elements to require (default: nil).
+  #                     By default, no restriction is imposed.
+  # timeout           - Integer total milliseconds to allow for element search (default: 30.sec).
+  #
+  # Returns the Integer total milliseconds to match any elements, or nil if no elements matched.
+  def time_to_elements(attrs={})
+    start_time = Time.now
+    if elements?(attrs)
+      ((Time.now - start_time) * 1000).round
+    else
+      nil
+    end
+  end
+
+  # Public: Gets exactly one element matching the search criteria.
+  #         For any String criteria, a Regular Expression may be used by adding the 'regexp:' prefix.
+  #
+  # name              - String name of the element (default: nil). Corresponds to Android 'resource-id' and Ios 'name'.
+  # text              - String text of the element (default: nil). Corresponds to Android 'text' and Ios 'value'.
+  # type              - String type of the element (default: nil). Corresponds to element class/tag.
+  # description       - String description of the element (default: nil).
+  #                     Corresponds to Android 'content-desc' and Ios 'label'.
+  # selector          - String automation selector (default: nil).
+  # index             - Integer index of element to use among all matching elements (default: nil).
+  #                     By default, exactly one element must match.
+  # is_visible        - Boolean indicating whether the element is visible (default: nil).
+  #                     Corresponds to Ios 'visible'. Always true for Android.
+  # is_on_screen      - Boolean indicating whether any part of the element is within screen boundaries (default: nil).
+  # is_tappable       - Boolean indicating whether the element may be tapped (default: nil).
+  #                     Corresponds to Android 'clickable'. Android only.
+  # is_password       - Boolean indicating whether the element is a password field (default: nil).
+  #                     Corresponds to Android 'password'. Android only.
+  # is_enabled        - Boolean indicating whether the element is enabled (default: nil).
+  #                     Corresponds to Android and Ios 'enabled'.
+  # is_checked        - Boolean indicating whether the element is checked (default: nil).
+  #                     Corresponds to Android 'checked'. Android only.
+  # is_selected       - Boolean indicating whether the element is selected (default: nil).
+  #                     Corresponds to Android 'selected'.
+  # is_checkable      - Boolean indicating whether the element can be checked (default: nil).
+  #                     Corresponds to Android 'checkable'. Android only.
+  # is_focusable      - Boolean indicating whether the element can be focused (default: nil).
+  #                     Corresponds to Android 'focusable'. Android only.
+  # is_long_pressable - Boolean indicating whether the element can be long-pressed (default: nil).
+  #                     Corresponds to Android 'long-clickable'. Android only.
+  # is_scrollable     - Boolean indicating whether the element can be scrolled (default: nil).
+  #                     Corresponds to Android 'scrollable'. Android only.
+  # is_recordable     - Boolean indicating whether the element can be recorded (default: nil).
+  # x                 - Integer x coordinate of the element (default: nil).
+  # y                 - Integer y coordinate of the element (default: nil).
+  # width             - Integer width of the element (default: nil).
+  # height            - Integer height of the element (default: nil).
+  # number            - Integer channel number (default: nil). Channel elements only.
+  # start_time        - Integer start time (default: nil). Channel/show elements only.
+  # end_time          - Integer end time (default: nil). Channel/show elements only.
+  # coordinates       - Boolean indicating whether absolute coordinates are given (default: false).
+  # info              - Array of Symbols specifying attributes to retrieve (default: []).
+  #                     By default, all attributes will be retrieved.
+  # min               - Integer minimum number of matching elements to require (default: 0).
+  #                     By default, no restriction is imposed.
+  # max               - Integer maximum number of matching elements to require (default: nil).
+  #                     By default, no restriction is imposed.
+  # timeout           - Integer total milliseconds to allow for element search (default: 30.sec).
+  #
+  # Returns the matching Element, or nil if exactly one matching element was not found.
+  def element(attrs={})
+    elem = selenium_post('element', attrs)
+    if elem.nil?
+      nil
+    elsif attrs.fetch(:info, []).count == 1
+      Element.new(elem)[attrs[:info].first]
+    else
+      Element.new(elem)
+    end
+  end
+
+  # Public: Checks if exactly one element matched the search criteria.
+  #         For any String criteria, a Regular Expression may be used by adding the 'regexp:' prefix.
+  #
+  # name              - String name of the element (default: nil). Corresponds to Android 'resource-id' and Ios 'name'.
+  # text              - String text of the element (default: nil). Corresponds to Android 'text' and Ios 'value'.
+  # type              - String type of the element (default: nil). Corresponds to element class/tag.
+  # description       - String description of the element (default: nil).
+  #                     Corresponds to Android 'content-desc' and Ios 'label'.
+  # selector          - String automation selector (default: nil).
+  # index             - Integer index of element to use among all matching elements (default: nil).
+  #                     By default, exactly one element must match.
+  # is_visible        - Boolean indicating whether the element is visible (default: nil).
+  #                     Corresponds to Ios 'visible'. Always true for Android.
+  # is_on_screen      - Boolean indicating whether any part of the element is within screen boundaries (default: nil).
+  # is_tappable       - Boolean indicating whether the element may be tapped (default: nil).
+  #                     Corresponds to Android 'clickable'. Android only.
+  # is_password       - Boolean indicating whether the element is a password field (default: nil).
+  #                     Corresponds to Android 'password'. Android only.
+  # is_enabled        - Boolean indicating whether the element is enabled (default: nil).
+  #                     Corresponds to Android and Ios 'enabled'.
+  # is_checked        - Boolean indicating whether the element is checked (default: nil).
+  #                     Corresponds to Android 'checked'. Android only.
+  # is_selected       - Boolean indicating whether the element is selected (default: nil).
+  #                     Corresponds to Android 'selected'.
+  # is_checkable      - Boolean indicating whether the element can be checked (default: nil).
+  #                     Corresponds to Android 'checkable'. Android only.
+  # is_focusable      - Boolean indicating whether the element can be focused (default: nil).
+  #                     Corresponds to Android 'focusable'. Android only.
+  # is_long_pressable - Boolean indicating whether the element can be long-pressed (default: nil).
+  #                     Corresponds to Android 'long-clickable'. Android only.
+  # is_scrollable     - Boolean indicating whether the element can be scrolled (default: nil).
+  #                     Corresponds to Android 'scrollable'. Android only.
+  # is_recordable     - Boolean indicating whether the element can be recorded (default: nil).
+  # x                 - Integer x coordinate of the element (default: nil).
+  # y                 - Integer y coordinate of the element (default: nil).
+  # width             - Integer width of the element (default: nil).
+  # height            - Integer height of the element (default: nil).
+  # number            - Integer channel number (default: nil). Channel elements only.
+  # start_time        - Integer start time (default: nil). Channel/show elements only.
+  # end_time          - Integer end time (default: nil). Channel/show elements only.
+  # coordinates       - Boolean indicating whether absolute coordinates are given (default: false).
+  # info              - Array of Symbols specifying attributes to retrieve (default: []).
+  #                     By default, all attributes will be retrieved.
+  # min               - Integer minimum number of matching elements to require (default: 0).
+  #                     By default, no restriction is imposed.
+  # max               - Integer maximum number of matching elements to require (default: nil).
+  #                     By default, no restriction is imposed.
+  # timeout           - Integer total milliseconds to allow for element search (default: 30.sec).
+  #
+  # Returns a Boolean true if exactly one element matched, otherwise false.
+  def element?(attrs={})
+    attrs[:info] = []
+    !element(attrs).nil?
+  end
+
+  # Public: Measures time to find exactly one matching element.
+  #         For any String criteria, a Regular Expression may be used by adding the 'regexp:' prefix.
+  #
+  # name              - String name of the element (default: nil). Corresponds to Android 'resource-id' and Ios 'name'.
+  # text              - String text of the element (default: nil). Corresponds to Android 'text' and Ios 'value'.
+  # type              - String type of the element (default: nil). Corresponds to element class/tag.
+  # description       - String description of the element (default: nil).
+  #                     Corresponds to Android 'content-desc' and Ios 'label'.
+  # selector          - String automation selector (default: nil).
+  # index             - Integer index of element to use among all matching elements (default: nil).
+  #                     By default, exactly one element must match.
+  # is_visible        - Boolean indicating whether the element is visible (default: nil).
+  #                     Corresponds to Ios 'visible'. Always true for Android.
+  # is_on_screen      - Boolean indicating whether any part of the element is within screen boundaries (default: nil).
+  # is_tappable       - Boolean indicating whether the element may be tapped (default: nil).
+  #                     Corresponds to Android 'clickable'. Android only.
+  # is_password       - Boolean indicating whether the element is a password field (default: nil).
+  #                     Corresponds to Android 'password'. Android only.
+  # is_enabled        - Boolean indicating whether the element is enabled (default: nil).
+  #                     Corresponds to Android and Ios 'enabled'.
+  # is_checked        - Boolean indicating whether the element is checked (default: nil).
+  #                     Corresponds to Android 'checked'. Android only.
+  # is_selected       - Boolean indicating whether the element is selected (default: nil).
+  #                     Corresponds to Android 'selected'.
+  # is_checkable      - Boolean indicating whether the element can be checked (default: nil).
+  #                     Corresponds to Android 'checkable'. Android only.
+  # is_focusable      - Boolean indicating whether the element can be focused (default: nil).
+  #                     Corresponds to Android 'focusable'. Android only.
+  # is_long_pressable - Boolean indicating whether the element can be long-pressed (default: nil).
+  #                     Corresponds to Android 'long-clickable'. Android only.
+  # is_scrollable     - Boolean indicating whether the element can be scrolled (default: nil).
+  #                     Corresponds to Android 'scrollable'. Android only.
+  # is_recordable     - Boolean indicating whether the element can be recorded (default: nil).
+  # x                 - Integer x coordinate of the element (default: nil).
+  # y                 - Integer y coordinate of the element (default: nil).
+  # width             - Integer width of the element (default: nil).
+  # height            - Integer height of the element (default: nil).
+  # number            - Integer channel number (default: nil). Channel elements only.
+  # start_time        - Integer start time (default: nil). Channel/show elements only.
+  # end_time          - Integer end time (default: nil). Channel/show elements only.
+  # coordinates       - Boolean indicating whether absolute coordinates are given (default: false).
+  # info              - Array of Symbols specifying attributes to retrieve (default: []).
+  #                     By default, all attributes will be retrieved.
+  # min               - Integer minimum number of matching elements to require (default: 0).
+  #                     By default, no restriction is imposed.
+  # max               - Integer maximum number of matching elements to require (default: nil).
+  #                     By default, no restriction is imposed.
+  # timeout           - Integer total milliseconds to allow for element search (default: 30.sec).
+  #
+  # Returns the Integer total milliseconds to match exactly one element,
+  #   or nil if exactly one matching element was not found.
+  def time_to_element(attrs={})
+    start_time = Time.now
+    if element?(attrs)
+      ((Time.now - start_time) * 1000).round
+    else
+      nil
+    end
+  end
+
+  # Public: Presses device Back button.
+  #
+  # sleep_time - Integer total milliseconds to wait after pressing Back (default: 0).
+  #
+  # Returns a Boolean true if successfully pressed Back, otherwise false.
+  def back?(args={})
+    ret = selenium_post('back', {})
+    sleep(args.fetch(:sleep_time, 0.sec))
+    !ret.nil?
+  end
+
+  # Public: Types on the device. The keys will be typed into the selected/focused element.
+  #
+  # keys       - String or Array of String keys to type.
+  # touch      - Boolean indicating whether to simulate physical key presses (default: false).
+  # sleep_time - Integer total milliseconds to sleep after typing (default: 0).
+  #
+  # Returns a Boolean true if successfully typed, otherwise false.
+  def type?(keys, args={})
+    unless keys.is_a?(Hash)
+      keys = {:keys => keys}
+    end
+    args = keys.merge(args)
+    args[:touch] ||= false
+    unless args[:keys].is_a?(Array)
+      args[:keys] = args[:keys].split('')
+    end
+    ret = selenium_post('type', args)
+    sleep(args.fetch(:sleep_time, 0.sec))
+    !ret.nil?
+  end
+
+  private
+
+  # Internal: Performs an Appium POST request for the given command, slot, and JSON parameters hash.
+  #
+  # Returns the result.
+  def selenium_post(cmd, json_params)
+    selenium_request(:post, cmd, json_params)
+  end
+
+  # Internal: Performs an Appium PUT request for the given command, slot, and JSON parameters hash.
+  #
+  # Returns the result.
+  def selenium_put(cmd, json_params)
+    selenium_request(:put, cmd, json_params)
+  end
+
+  # Internal: Performs an Appium DELETE request for the given command and slot.
+  #
+  # Returns the result.
+  def selenium_delete(cmd, json_params)
+    selenium_request(:delete, cmd, json_params)
+  end
+
+  # Internal: Performs an Appium GET request for the given command and slot.
+  #
+  # Returns the result.
+  def selenium_get(cmd)
+    selenium_request(:get, cmd)
+  end
+
+  # Internal: Performs a basic Appium request for the given command, slot, and optional JSON parameters hash.
+  #
+  # Returns the result.
+  def selenium_request(http_method, cmd, json=nil)
+    screenshot = nil
+    default_timeout = 30.sec
+    unless json.nil?
+      if json.include?(:from)
+        json[:from][:timeout] ||= default_timeout
+      end
+      if json.include?(:to)
+        json[:to][:timeout] ||= default_timeout
+      end
+      json[:timeout] ||= default_timeout
+    end
+    # TODO: use a pattern here
+    if @is_appium
+      resource = "/api/mobile/#{cmd}/#{@id}/"
+      if !json.nil? && (json.include?(:xpath) || json.include?(:selector))
+        logger.debug("SURGEON GENERAL'S WARNING: Use of Xpath or Selectors Greatly Increases Risk of Code Refactoring.")
+      end
+    else
+      resource = '/api/browsers'
+      unless @id.nil?
+        resource = "#{resource}/#{@id}"
+        # Take a screenshot first
+        screenshot_cmd = 'screenshot'
+        unless cmd == screenshot_cmd
+          screenshot = selenium_request(:post, screenshot_cmd, {})['path']
+        end
+      end
+      resource = "#{resource}/#{cmd}" unless cmd.nil?
+    end
+    start_time = Time.now
+    ret = @test_case.send(:tmc_request, http_method, resource, json: @test_case.jsonify(json), timeout: 1.hr,
+                          screen_image: screenshot)
+    delta_sec = Time.now - start_time
+    delta_str = "[#{'%.3f' % delta_sec} s]"
+    if delta_sec > 60 && cmd != 'session'
+      logger.info("*** WARNING *** Long request #{delta_str}, use alternate locator strategy to improve performance")
+    end
+    ret
+  end
+
+end