appium_lib 4.1.0 → 5.0.0

data/lib/appium_lib/ios/element/textfield.rb

@@ -6,27 +6,41 @@ module Appium
     private
 
     # @private
-    def _textfield_visible_string opts={}
-      index = opts.fetch :index, false
-      if index
-        %Q(//#{UIATextField}[@visible="true"][#{index}] | //#{UIASecureTextField}[@visible="true"][#{index}])
-      else
-        %Q(//#{UIATextField}[@visible="true"] | //#{UIASecureTextField}[@visible="true"])
-      end
+    def _textfield_visible
+      {
+        typeArray:   [UIATextField, UIASecureTextField],
+        onlyVisible: true,
+      }
     end
 
     # @private
     def _textfield_exact_string value
-      textfield = string_visible_exact UIATextField, value
-      secure    = string_visible_exact UIASecureTextField, value
-      "#{textfield} | #{secure}"
+      exact     = {
+        target:      value,
+        substring:   false,
+        insensitive: false,
+      }
+      exact_obj = {
+        name:  exact,
+        label: exact,
+        value: exact,
+      }
+      _textfield_visible.merge(exact_obj)
     end
 
     # @private
     def _textfield_contains_string value
-      textfield = string_visible_contains UIATextField, value
-      secure    = string_visible_contains UIASecureTextField, value
-      "#{textfield} | #{secure}"
+      contains     = {
+        target:      value,
+        substring:   true,
+        insensitive: true,
+      }
+      contains_obj = {
+        name:  contains,
+        label: contains,
+        value: contains,
+      }
+      _textfield_visible.merge(contains_obj)
     end
 
     public
@@ -40,12 +54,15 @@ module Appium
       # iOS needs to combine textfield and secure to match Android.
       if value.is_a? Numeric
         index = value
-        raise "#{index} is not a valid xpath index. Must be >= 1" if index <= 0
+        raise "#{index} is not a valid index. Must be >= 1" if index <= 0
+        index -= 1 # eles_by_json is 0 indexed.
 
-        return xpath _textfield_visible_string index: index
+        result = eles_by_json(_textfield_visible)[index]
+        raise _no_such_element if result.nil?
+        return result
       end
 
-      xpath _textfield_contains_string value
+      ele_by_json _textfield_contains_string value
     end
 
     # Find all TextFields containing value.
@@ -53,34 +70,36 @@ module Appium
     # @param value [String] the value to search for
     # @return [Array<TextField>]
     def textfields value=false
-      return xpaths _textfield_visible_string unless value
-      xpaths _textfield_contains_string value
+      return eles_by_json _textfield_visible unless value
+      eles_by_json _textfield_contains_string value
     end
 
     # Find the first TextField.
     # @return [TextField]
     def first_textfield
-      xpath _textfield_visible_string
+      ele_by_json _textfield_visible
     end
 
     # Find the last TextField.
     # @return [TextField]
     def last_textfield
-      xpath _textfield_visible_string index: 'last()'
+      result = eles_by_json(_textfield_visible).last
+      raise _no_such_element if result.nil?
+      result
     end
 
     # Find the first TextField that exactly matches value.
     # @param value [String] the value to match exactly
     # @return [TextField]
     def textfield_exact value
-      xpath _textfield_exact_string value
+      ele_by_json _textfield_exact_string value
     end
 
     # Find all TextFields that exactly match value.
     # @param value [String] the value to match exactly
     # @return [Array<TextField>]
     def textfields_exact value
-      xpaths _textfield_exact_string value
+      eles_by_json _textfield_exact_string value
     end
   end # module Ios
 end # module Appium

data/lib/appium_lib/ios/helper.rb

@@ -157,7 +157,7 @@ module Appium
     def source_window window_number=0
       # appium 1.0 still returns JSON when getTree() is invoked so this
       # doesn't need to change to XML. If getTree() is removed then
-      # source_window will need to parse the results of getTreeForXML()\
+      # source_window will need to parse the elements of getTreeForXML()\
       # https://github.com/appium/appium-uiauto/blob/247eb71383fa1a087ff8f8fc96fac25025731f3f/uiauto/appium/element.js#L145
       execute_script "UIATarget.localTarget().frontMostApp().windows()[#{window_number}].getTree()"
     end
@@ -177,11 +177,7 @@ module Appium
     # @param id [String] the id to search for
     # @return [Element]
     def id id
-      value = resolve_id id
-      raise "Invalid id `#{id}`" unless value
-      exact    = string_visible_exact '*', value
-      contains = string_visible_contains '*', value
-      xpath "#{exact} | #{contains}"
+      find_element :id, id
     end
 
     # Return the iOS version as an array of integers
@@ -196,11 +192,19 @@ module Appium
     # @param index [Integer] the index
     # @return [Element]
     def ele_index class_name, index
-      unless index == 'last()'
-        # XPath index starts at 1.
-        raise "#{index} is not a valid xpath index. Must be >= 1" if index <= 0
+      raise 'Index must be >= 1' unless index == 'last()' || (index.is_a?(Integer) && index >= 1)
+      elements = tags(class_name)
+
+      if index == 'last()'
+        result = elements.last
+      else
+        # elements array is 0 indexed
+        index  -= 1
+        result = elements[index]
       end
-      find_element :xpath, %Q(//#{class_name}[@visible="true"][#{index}])
+
+      raise _no_such_element if result.nil?
+      result
     end
 
     # @private
@@ -209,6 +213,7 @@ module Appium
     end
 
     # Find the first element exactly matching class and attribute value.
+    # Note: Uses XPath
     # @param class_name [String] the class name to search for
     # @param attr [String] the attribute to inspect
     # @param value [String] the expected value of the attribute
@@ -218,6 +223,7 @@ module Appium
     end
 
     # Find all elements exactly matching class and attribute value.
+    # Note: Uses XPath
     # @param class_name [String] the class name to match
     # @param attr [String] the attribute to compare
     # @param value [String] the value of the attribute that the element must have
@@ -232,6 +238,7 @@ module Appium
     end
 
     # Get the first tag by attribute that exactly matches value.
+    # Note: Uses XPath
     # @param class_name [String] the tag name to match
     # @param attr [String] the attribute to compare
     # @param value [String] the value of the attribute that the element must include
@@ -241,6 +248,7 @@ module Appium
     end
 
     # Get tags by attribute that include value.
+    # Note: Uses XPath
     # @param class_name [String] the tag name to match
     # @param attr [String] the attribute to compare
     # @param value [String] the value of the attribute that the element must include
@@ -264,95 +272,103 @@ module Appium
       ele_index class_name, 'last()'
     end
 
-    # Returns the first element matching class_name
+    # Returns the first visible element matching class_name
     #
     # @param class_name [String] the class_name to search for
     # @return [Element]
     def tag class_name
-      xpath %Q(//#{class_name}[@visible="true"])
+      ele_by_json({
+                    typeArray:   [class_name],
+                    onlyVisible: true,
+                  })
     end
 
-    # Returns all elements matching class_name
+    # Returns all visible elements matching class_name
     #
     # @param class_name [String] the class_name to search for
     # @return [Element]
     def tags class_name
-      xpaths %Q(//#{class_name}[@visible="true"])
+      eles_by_json({
+                     typeArray:   [class_name],
+                     onlyVisible: true,
+                   })
     end
 
     # @private
-    # Returns a string xpath that matches the first element that contains value
+    # Returns an object that matches the first element that contains value
     #
-    # example: xpath_visible_contains 'UIATextField', 'sign in'
+    # example: ele_by_json_visible_contains 'UIATextField', 'sign in'
     #
     # @param element [String] the class name for the element
     # @param value [String] the value to search for
     # @return [String]
     def string_visible_contains element, value
-      result     = []
-      attributes = %w[name hint label value]
-
-      value_up   = value.upcase
-      value_down = value.downcase
-
-      attributes.each do |attribute|
-        result << %Q(contains(translate(@#{attribute},"#{value_up}","#{value_down}"), "#{value_down}"))
-      end
+      contains = {
+        target:      value,
+        substring:   true,
+        insensitive: true,
+      }
 
-      result = result.join(' or ')
-      result = %Q(@visible="true" and (#{result}))
-      "//#{element}[#{result}]"
+      {
+        typeArray:   [element],
+        onlyVisible: true,
+        name:        contains,
+        label:       contains,
+        value:       contains,
+      }
     end
 
     # Find the first element that contains value
     # @param element [String] the class name for the element
     # @param value [String] the value to search for
     # @return [Element]
-    def xpath_visible_contains element, value
-      xpath string_visible_contains element, value
+    def ele_by_json_visible_contains element, value
+      ele_by_json string_visible_contains element, value
     end
 
     # Find all elements containing value
     # @param element [String] the class name for the element
     # @param value [String] the value to search for
     # @return [Array<Element>]
-    def xpaths_visible_contains element, value
-      xpaths string_visible_contains element, value
+    def eles_by_json_visible_contains element, value
+      eles_by_json string_visible_contains element, value
     end
 
     # @private
-    # Create an xpath string to exactly match the first element with target value
+    # Create an object to exactly match the first element with target value
     # @param element [String] the class name for the element
     # @param value [String] the value to search for
     # @return [String]
     def string_visible_exact element, value
-      result     = []
-      attributes = %w[name hint label value]
-
-      attributes.each do |attribute|
-        result << %Q(@#{attribute}="#{value}")
-      end
-
-      result = result.join(' or ')
-      result = %Q(@visible="true" and (#{result}))
+      exact = {
+        target:      value,
+        substring:   false,
+        insensitive: false,
+      }
 
-      "//#{element}[#{result}]"
+      {
+        typeArray:   [element],
+        onlyVisible: true,
+        name:        exact,
+        label:       exact,
+        value:       exact,
+      }
     end
 
     # Find the first element exactly matching value
     # @param element [String] the class name for the element
     # @param value [String] the value to search for
     # @return [Element]
-    def xpath_visible_exact element, value
-      xpath string_visible_exact element, value
+    def ele_by_json_visible_exact element, value
+      ele_by_json string_visible_exact element, value
     end
 
     # Find all elements exactly matching value
     # @param element [String] the class name for the element
     # @param value [String] the value to search for
     # @return [Element]
-    def xpaths_visible_exact element, value
-      xpaths string_visible_exact element, value
+    def eles_by_json_visible_exact element, value
+      eles_by_json string_visible_exact element, value
     end
 
     # @private
@@ -363,12 +379,18 @@ module Appium
     # @return [void]
     def hide_ios_keyboard close_key='Done'
 =begin
+todo: there are many various ways to hide the keyboard that work in different
+app specific circumstances. webview keyboard will require a window.tap for example.
+
 Find the top left corner of the keyboard and move up 10 pixels (origin.y - 10)
 now swipe down until the end of the window - 10 pixels.
 -10 to ensure we're not going outside the window bounds.
 
 Swiping inside the keyboard will not dismiss it.
 
+If the 'Done' key exists then that should be pressed to dismiss the keyboard
+because swiping to dismiss works only if such key doesn't exist.
+
 Don't use window.tap. See https://github.com/appium/appium-uiauto/issues/28
 =end
       dismiss_keyboard = (<<-JS).strip
@@ -403,5 +425,152 @@ Don't use window.tap. See https://github.com/appium/appium-uiauto/issues/28
         execute_script 'au.mainApp().keyboard().isNil()'
       end
     end
+
+    #
+    # predicate - the predicate to evaluate on the main app
+    #
+    # visible - if true, only visible elements are returned. default true
+    #
+    def _all_pred opts
+      predicate = opts[:predicate]
+      raise 'predicate must be provided' unless predicate
+      visible = opts.fetch :visible, true
+      %Q($.mainApp().getAllWithPredicate("#{predicate}", #{visible});)
+    end
+
+    # returns element matching predicate contained in the main app
+    #
+    # predicate - the predicate to evaluate on the main app
+    #
+    # visible - if true, only visible elements are returned. default true
+    # @return [Element]
+    def ele_with_pred opts
+      # true = return only visible
+      find_element(:uiautomation, _all_pred(opts))
+    end
+
+    # returns elements matching predicate contained in the main app
+    #
+    # predicate - the predicate to evaluate on the main app
+    #
+    # visible - if true, only visible elements are returned. default true
+    # @return [Array<Element>]
+    def eles_with_pred opts
+      find_elements(:uiautomation, _all_pred(opts))
+    end
+
+    # Prints xml of the current page
+    # @return [void]
+    def source
+      _print_source get_source
+    end
+
+    def _validate_object *objects
+      raise 'objects must be an array' unless objects.is_a? Array
+      objects.each do |obj|
+        next unless obj # obj may be nil. if so, ignore.
+
+        valid_keys   = [:target, :substring, :insensitive]
+        unknown_keys = obj.keys - valid_keys
+        raise "Unknown keys: #{unknown_keys}" unless unknown_keys.empty?
+
+        target = obj[:target]
+        raise 'target must be a string' unless target.is_a? String
+
+        substring = obj[:substring]
+        raise 'substring must be a boolean' unless [true, false].include? substring
+
+        insensitive = obj[:insensitive]
+        raise 'insensitive must be a boolean' unless [true, false].include? insensitive
+      end
+    end
+
+    # typeArray - array of string types to search for. Example: ["UIAStaticText"]
+    # onlyFirst - boolean. returns only the first result if true. Example: true
+    # onlyVisible - boolean. returns only visible elements if true. Example: true
+    # target - string. the target value to search for. Example: "Buttons, Various uses of UIButton"
+    # substring - boolean. matches on substrings if true otherwise an exact mathc is required. Example: true
+    # insensitive - boolean. ignores case sensitivity if true otherwise it's case sensitive. Example: true
+    #
+    # opts = {
+    #   typeArray: ["UIAStaticText"],
+    #   onlyFirst: true,
+    #   onlyVisible: true,
+    #   name: {
+    #     target: "Buttons, Various uses of UIButton",
+    #     substring: false,
+    #     insensitive: false,
+    #   },
+    #   label: {
+    #     target: "Buttons, Various uses of UIButton",
+    #     substring: false,
+    #     insensitive: false,
+    #   },
+    #   value: {
+    #     target: "Buttons, Various uses of UIButton",
+    #     substring: false,
+    #     insensitive: false,
+    #   }
+    # }
+    #
+    def _by_json opts
+      valid_keys   = [:typeArray, :onlyFirst, :onlyVisible, :name, :label, :value]
+      unknown_keys = opts.keys - valid_keys
+      raise "Unknown keys: #{unknown_keys}" unless unknown_keys.empty?
+
+      typeArray = opts[:typeArray]
+      raise 'typeArray must be an array' unless typeArray.is_a? Array
+
+      onlyFirst = opts[:onlyFirst]
+      raise 'onlyFirst must be a boolean' unless [true, false].include? onlyFirst
+
+      onlyVisible = opts[:onlyVisible]
+      raise 'onlyVisible must be a boolean' unless [true, false].include? onlyVisible
+
+      # name/label/value are optional. when searching for class only, then none
+      # will be present.
+      _validate_object opts[:name], opts[:label], opts[:value]
+
+      element_or_elements_by_type = <<-JS
+        (function() {
+        var opts = #{opts.to_json}
+
+        return $.mainWindow()._elementOrElementsByType(opts);
+        })();
+      JS
+
+      execute_script element_or_elements_by_type
+    end
+
+    # example usage:
+    #
+    # eles_by_json({
+    #   typeArray: ["UIAStaticText"],
+    #   onlyVisible: true,
+    #   name: {
+    #     target: "Buttons, Various uses of UIButton",
+    #     substring: false,
+    #     insensitive: false,
+    #   },
+    # })
+    def eles_by_json opts
+      opts[:onlyFirst] = false
+      return _by_json opts
+    end
+
+    # see eles_by_json
+    def ele_by_json opts
+      opts[:onlyFirst] = true
+      result           = _by_json(opts).first
+      raise _no_such_element if result.nil?
+      result
+    end
+
+    # Returns XML string for the current page
+    # Same as driver.page_source
+    # @return [String]
+    def get_source
+      @driver.page_source
+    end
   end # module Ios
 end # module Appium