Search with predicate (#504)

* add find elements with predicate

* use predicate strategy in find/s and find/s_exact

* fix rubocop

* remove elements_include and elements_exact

* add tests and update find elements

* fix text field

* fix rubocop

* add some documentations

* remove redundant lines

* remove redundant find elemenets

* fix lint

Author: KazuCocoa

.rubocop.yml

@@ -38,6 +38,8 @@ Style/IndentHash:
   Enabled: false
 Style/VariableNumber:
   EnforcedStyle: 'snake_case'
+Style/MultilineOperationIndentation:
+  Enabled: false
 Lint/NestedMethodDefinition:
   Enabled: false
 # Should enable and fix for Ruby3

docs/ios_xcuitest.md

@@ -13,7 +13,7 @@
 - Mapping
     - https://github.com/facebook/WebDriverAgent/blob/master/WebDriverAgentLib/Utilities/FBElementTypeTransformer.m#L19
 
-### with except for XPath
+### with except for XPath and Predicate
 #### examples
 - [button_class](https://github.com/appium/ruby_lib/blob/master/lib/appium_lib/ios/element/button.rb#L8), [static_text_class](https://github.com/appium/ruby_lib/blob/master/lib/appium_lib/ios/element/text.rb#L8), [text_field_class](https://github.com/appium/ruby_lib/blob/master/lib/appium_lib/ios/element/textfield.rb#L10) and [secure_text_field_class](https://github.com/appium/ruby_lib/blob/master/lib/appium_lib/ios/element/textfield.rb#L15) provide class name.
     - If `automationName` is `Appium` or `nil`, then they provide `UIAxxxx`
@@ -36,6 +36,22 @@ find_element(:accessibility_id, element) # Return a element which has accessibil
 buttons(value) # Return button elements include `value` as its name attributes.
 ```
 
+### with Predicate
+- We recommend to use predicate strategy instead of XPath strategy.
+    - e.g. `find_ele_by_predicate/find_eles_by_predicate`,  `find_ele_by_predicate_include/find_eles_by_predicate_include`
+- A helpful cheatsheet for predicate
+    - https://realm.io/news/nspredicate-cheatsheet/
+- For XCUITest(WebDriverAgent), without 'wd' prefixes are supported.
+    - https://github.com/facebook/WebDriverAgent/wiki/Queries
+    - For example, `%(name ==[c] "#{value}" || label ==[c] "#{value}" || value ==[c] "#{value}")` is equal to `%(wdName ==[c] "#{value}" || wdLabel ==[c] "#{value}" || wdValue ==[c] "#{value}")` in WebDriverAgent.
+
+#### examples
+- `textfield/s(value)`, `find/s`, `find_exact/finds_exact`, `find_ele_by_predicate/find_eles_by_predicate` and `find_ele_by_predicate_include/find_eles_by_predicate_include` use predicate strategy in their method.
+
+```ruby
+textfield(value) # Return a XCUIElementTypeSecureTextField or XCUIElementTypeTextField element which has `value` text.
+finds_exact(value) # Return any elements include `value` as its name attributes.
+```
 
 ### with XPath
 - It is better to avoid XPath strategy.
@@ -48,11 +64,9 @@ buttons(value) # Return button elements include `value` as its name attributes.
     - https://github.com/facebook/WebDriverAgent/blob/2158a8d0f305549532f1338fe1e4628cfbd53cd9/WebDriverAgentLib/Categories/XCElementSnapshot%2BFBHelpers.m#L57
 
 #### examples
-- `textfield/s(value)`, `find/s`, `find_exact/finds_exact` uses XPath in their method. So, these methods are slower than other find_element directly.
 
 ```ruby
-textfield(value) # Return a XCUIElementTypeSecureTextField or XCUIElementTypeTextField element which has `value` text.
-finds_exact(value) # Return any elements include `value` as its name attributes.
+xpaths("//some xpaths")
 ```
 
 ## Other actions

ios_tests/lib/ios/specs/common/helper.rb

@@ -125,6 +125,22 @@ def uibutton_text
     set_wait
   end
 
+  t 'find_ele_by_predicate' do
+    el_text = find_ele_by_predicate(value: uibutton_text).text
+    el_text.must_equal uibutton_text
+
+    el_name = find_ele_by_predicate(value: uibutton_text).name
+    el_name.must_equal uibutton_text
+  end
+
+  t 'find_eles_by_predicate' do
+    ele_count = find_eles_by_predicate(value: uibutton_text).length
+    ele_count.must_equal 1
+
+    ele_count = find_eles_by_predicate(value: 'zz').length
+    ele_count.must_equal 0
+  end
+
   # TODO: 'string_attr_include'
 
   t 'find_ele_by_attr_include' do
@@ -141,6 +157,18 @@ def uibutton_text
     ele_count.must_equal expected
   end
 
+  t 'find_ele_by_predicate_include' do
+    el_text = find_ele_by_predicate_include(value: 'button').text
+    el_text.must_equal uibutton_text
+
+    el_name = find_ele_by_predicate_include(value: 'button').name
+    el_name.must_equal uibutton_text
+  end
+
+  t 'find_eles_by_predicate_include' do
+    find_eles_by_predicate_include(value: 'e').length.must_equal 21
+  end
+
   t 'first_ele' do
     first_ele(UI::Inventory.static_text).name.must_equal 'UICatalog'
   end
@@ -174,7 +202,7 @@ def uibutton_text
     tags(UI::Inventory.table_cell).length.must_equal 12
   end
 
-  t 'find_eles_by_attr_include' do
+  t 'find_eles_by_attr_include_length' do
     find_eles_by_attr_include(UI::Inventory.static_text, 'name', 'Use').length.must_equal 7
   end
 

ios_tests/lib/ios/specs/ios/helper.rb

@@ -32,19 +32,28 @@ def before_first
   end
 
   t 'tags_include' do
+    elements = tags_include class_names: %w(XCUIElementTypeTextView)
+    elements.length.must_equal 0
+
     elements = tags_include class_names: %w(XCUIElementTypeTextView XCUIElementTypeStaticText)
-    elements.length.must_be 24
+    elements.length.must_equal 24
 
     elements = tags_include class_names: %w(XCUIElementTypeTextView XCUIElementTypeStaticText), value: 'u'
-    elements.length.must_be 13
+    elements.length.must_equal 13
   end
 
-  t 'tags_include' do
+  t 'tags_exact' do
+    elements = tags_exact class_names: %w()
+    elements.length.must_equal 0
+
+    elements = tags_exact class_names: %w(XCUIElementTypeStaticText)
+    elements.length.must_equal 24
+
     elements = tags_exact class_names: %w(XCUIElementTypeTextView XCUIElementTypeStaticText)
-    elements.length.must_be 24
+    elements.length.must_equal 24
 
     elements = tags_exact class_names: %w(XCUIElementTypeTextView XCUIElementTypeStaticText), value: 'Buttons'
-    elements.length.must_be 1
+    elements.length.must_equal 1
     elements.first.value.must_equal 'Buttons'
   end
 end

lib/appium_lib/ios/element/button.rb

@@ -32,8 +32,8 @@ def buttons(value = false)
       return tags button_class unless value
 
       if automation_name_is_xcuitest?
-        visible_elements = tags button_class
-        elements_include visible_elements, value
+        elements = find_eles_by_predicate_include(class_name: button_class, value: value)
+        select_visible_elements elements
       else
         eles_by_json_visible_contains button_class, value
       end
@@ -69,8 +69,8 @@ def button_exact(value)
     # @return [Array<UIAButton|XCUIElementTypeButton>]
     def buttons_exact(value)
       if automation_name_is_xcuitest?
-        visible_elements = tags button_class
-        elements_exact visible_elements, value
+        elements = find_eles_by_predicate(class_name: button_class, value: value)
+        select_visible_elements elements
       else
         eles_by_json_visible_exact button_class, value
       end

lib/appium_lib/ios/element/generic.rb

@@ -16,7 +16,7 @@ def find(value)
     # @return [Array<Element>]
     def finds(value)
       if automation_name_is_xcuitest?
-        elements = find_eles_by_attr_include '*', '*', value
+        elements = find_eles_by_predicate_include value: value
         select_visible_elements elements
       else
         eles_by_json_visible_contains '*', value
@@ -39,7 +39,7 @@ def find_exact(value)
     # @return [Array<Element>]
     def finds_exact(value)
       if automation_name_is_xcuitest?
-        elements = find_eles_by_attr '*', '*', value
+        elements = find_eles_by_predicate value: value
         select_visible_elements elements
       else
         eles_by_json_visible_exact '*', value
@@ -54,34 +54,6 @@ def raise_error_if_no_element(element)
       element
     end
 
-    # Return all elements include not displayed elements.
-    def elements_include(elements, value)
-      return [] if elements.empty?
-      elements.select do |element|
-        # `text` is equal to `value` if value is not `nil`
-        # `text` is equal to `name` if value is `nil`
-        name = element.name
-        text = element.value
-        name_result = name.nil? ? false : name.downcase.include?(value.downcase)
-        text_result = text.nil? ? false : text.downcase.include?(value.downcase)
-        name_result || text_result
-      end
-    end
-
-    # Return all elements include not displayed elements.
-    def elements_exact(elements, value)
-      return [] if elements.empty?
-      elements.select do |element|
-        # `text` is equal to `value` if value is not `nil`
-        # `text` is equal to `name` if value is `nil`
-        name = element.name
-        text = element.value
-        name_result = name.nil? ? false : name.casecmp(value).zero?
-        text_result = text.nil? ? false : text.casecmp(value).zero?
-        name_result || text_result
-      end
-    end
-
     # Return visible elements.
     def select_visible_elements(elements)
       elements.select(&:displayed?)

lib/appium_lib/ios/element/text.rb

@@ -31,8 +31,8 @@ def texts(value = false)
       return tags static_text_class unless value
 
       if automation_name_is_xcuitest?
-        visible_elements = tags static_text_class
-        elements_include visible_elements, value
+        elements = find_eles_by_predicate_include(class_name: static_text_class, value: value)
+        select_visible_elements elements
       else
         eles_by_json_visible_contains static_text_class, value
       end
@@ -66,8 +66,8 @@ def text_exact(value)
     # @return [Array<UIAStaticText|XCUIElementTypeStaticText>]
     def texts_exact(value)
       if automation_name_is_xcuitest?
-        visible_elements = tags static_text_class
-        elements_exact visible_elements, value
+        elements = find_eles_by_predicate(class_name: static_text_class, value: value)
+        select_visible_elements elements
       else
         eles_by_json_visible_exact static_text_class, value
       end

lib/appium_lib/ios/element/textfield.rb

@@ -20,20 +20,14 @@ def secure_text_field_class
 
     # @private
     # for XCUITest
-    def _textfields
-      %(#{text_field_class} | //#{secure_text_field_class})
+    def _textfield_with_predicate
+      raise_error_if_no_element _textfields_with_predicate.first
     end
 
     # @private
     # for XCUITest
-    def _textfield_with_xpath
-      raise_error_if_no_element _textfields_with_xpath.first
-    end
-
-    # @private
-    # for XCUITest
-    def _textfields_with_xpath
-      elements = xpaths "//#{_textfields}"
+    def _textfields_with_predicate
+      elements = tags_include(class_names: [text_field_class, secure_text_field_class])
       select_visible_elements elements
     end
 
@@ -67,9 +61,9 @@ def textfield(value)
       if value.is_a? Numeric
         index = value
         raise "#{index} is not a valid index. Must be >= 1" if index <= 0
-        index -= 1 # eles_by_json and _textfields_with_xpath is 0 indexed.
+        index -= 1 # eles_by_json and _textfields_with_predicate is 0 indexed.
         result = if automation_name_is_xcuitest?
-                   _textfields_with_xpath[index]
+                   _textfields_with_predicate[index]
                  else
                    eles_by_json(_textfield_visible)[index]
                  end
@@ -91,8 +85,9 @@ def textfield(value)
     # @return [Array<TextField>]
     def textfields(value = false)
       if automation_name_is_xcuitest?
-        return _textfields_with_xpath unless value
-        elements = find_eles_by_attr_include _textfields, '*', value
+        return tags_include(class_names: [text_field_class, secure_text_field_class]) unless value
+
+        elements = tags_include class_names: [text_field_class, secure_text_field_class], value: value
         select_visible_elements elements
       else
         return eles_by_json _textfield_visible unless value
@@ -104,7 +99,7 @@ def textfields(value = false)
     # @return [TextField]
     def first_textfield
       if automation_name_is_xcuitest?
-        _textfield_with_xpath
+        _textfield_with_predicate
       else
         ele_by_json _textfield_visible
       end
@@ -114,7 +109,7 @@ def first_textfield
     # @return [TextField]
     def last_textfield
       result = if automation_name_is_xcuitest?
-                 _textfields_with_xpath.last
+                 _textfields_with_predicate.last
                else
                  eles_by_json(_textfield_visible).last
                end
@@ -138,7 +133,7 @@ def textfield_exact(value)
     # @return [Array<TextField>]
     def textfields_exact(value)
       if automation_name_is_xcuitest?
-        elements = find_eles_by_attr _textfields, '*', value
+        elements = tags_exact class_names: [text_field_class, secure_text_field_class], value: value
         select_visible_elements elements
       else
         eles_by_json _textfield_exact_string value