appium_lib 9.3.3 → 9.3.4

data/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

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

@@ -125,6 +125,22 @@ describe 'common/helper.rb' do
     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 @@ describe 'common/helper.rb' do
     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 @@ describe 'common/helper.rb' do
     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
 

data/ios_tests/lib/ios/specs/device/device.rb

@@ -52,6 +52,11 @@ describe 'device/device' do
     tag(UI::Inventory.navbar).name.must_equal 'UICatalog'
   end
 
+  t 'background_app homescreen' do
+    background_app(-1) # background_app(nil) should work as same.
+    screen.must_raise ::Selenium::WebDriver::Error::NoSuchElementError
+  end
+
   t 'reset' do
     reset
   end

data/ios_tests/lib/ios/specs/ios/element/textfield.rb

@@ -34,10 +34,13 @@ describe 'ios/element/textfield' do
   end
 
   t 'predicate textfields' do
-    raise NotImplementedError, "XCUITest(Appium1.6.2) doesn't support UIAutomation script" if UI::Inventory.xcuitest?
+    textfields = if UI::Inventory.xcuitest?
+                   find_elements(:predicate, "type contains[c] 'textfield'")
+                 else
+                   execute_script(%(au.mainApp().getAllWithPredicate("type contains[c] 'textfield'", true)))
+                 end
 
-    textfield_count = execute_script(%(au.mainApp().getAllWithPredicate("type contains[c] 'textfield'", true))).length
-    textfield_count.must_equal 4
+    textfields.length.must_equal 4
   end
 
   t 'first_textfield' do

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

@@ -32,19 +32,28 @@ describe 'ios/helper' do
   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

data/lib/appium_lib/common/version.rb

@@ -1,5 +1,5 @@
 module Appium
   # Version and Date are defined on the 'Appium' module, not 'Appium::Common'
-  VERSION = '9.3.3'.freeze unless defined? ::Appium::VERSION
-  DATE    = '2017-02-18'.freeze unless defined? ::Appium::DATE
+  VERSION = '9.3.4'.freeze unless defined? ::Appium::VERSION
+  DATE    = '2017-03-16'.freeze unless defined? ::Appium::DATE
 end

data/lib/appium_lib/device/device.rb

@@ -13,7 +13,13 @@ module Appium
     # @!method background_app
     #  Backgrounds the app for a set number of seconds.
     #  This is a blocking application
-    # @param seconds (int) How many seconds to background the app for.
+    # @param [Integer] seconds How many seconds to background the app for.
+    #
+    #   ```ruby
+    #   background_app
+    #   background_app(5)
+    #   background_app(-1) #=> the app never come back. https://github.com/appium/appium/issues/7741
+    #   ```
 
     # @!method current_activity
 
@@ -202,8 +208,14 @@ module Appium
         end
 
         add_endpoint_method(:background_app) do
-          def background_app(duration)
-            execute :background_app, {}, seconds: duration
+          def background_app(duration = 0)
+            # https://github.com/appium/ruby_lib/issues/500, https://github.com/appium/appium/issues/7741
+            if $driver.automation_name_is_xcuitest? && $driver.appium_server_status['build']['version'] >= '1.6.4'
+              duration_milli_sec = duration.nil? ? nil : duration * 1000
+              execute :background_app, {}, seconds: { timeout: duration_milli_sec }
+            else
+              execute :background_app, {}, seconds: duration
+            end
           end
         end
 

data/lib/appium_lib/driver.rb

@@ -299,7 +299,7 @@ module Appium
     # If automation_name is nil, it is not set both client side and server side.
     attr_reader :automation_name
     # Appium's server version
-    attr_reader :appium_server_version
+    attr_reader :appium_server_status
     # Boolean debug mode for the Appium Ruby bindings
     attr_accessor :appium_debug
     # instance of AbstractEventListener for logging support
@@ -476,7 +476,7 @@ module Appium
     # If the Appium server is under REQUIRED_VERSION_XCUITEST, then error is raised.
     # @return [Boolean]
     def check_server_version_xcuitest
-      if automation_name_is_xcuitest? && (@appium_server_version['build']['version'] < REQUIRED_VERSION_XCUITEST)
+      if automation_name_is_xcuitest? && (@appium_server_status['build']['version'] < REQUIRED_VERSION_XCUITEST)
         raise Appium::Error::NotSupportedAppiumServer, "XCUITest requires Appium version >= #{REQUIRED_VERSION_XCUITEST}"
       end
       true
@@ -618,7 +618,7 @@ module Appium
         raise "ERROR: Unable to connect to Appium. Is the server running on #{server_url}?"
       end
 
-      @appium_server_version = appium_server_version
+      @appium_server_status = appium_server_version
 
       check_server_version_xcuitest
       set_automation_name_if_nil

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

@@ -32,8 +32,8 @@ module Appium
       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 @@ module Appium
     # @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

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

@@ -16,7 +16,7 @@ module Appium
     # @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 @@ module Appium
     # @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 @@ module Appium
       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?)

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

@@ -31,8 +31,8 @@ module Appium
       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 @@ module Appium
     # @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

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

@@ -20,20 +20,14 @@ module Appium
 
     # @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 @@ module Appium
       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 @@ module Appium
     # @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 @@ module Appium
     # @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 @@ module Appium
     # @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 @@ module Appium
     # @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

data/lib/appium_lib/ios/helper.rb

@@ -273,6 +273,31 @@ module Appium
       end
     end
 
+    # Find the first element exactly matching attribute case insensitive value.
+    # Note: Uses Predicate
+    # @param value [String] the expected value of the attribute
+    # @return [Element]
+    def find_ele_by_predicate(class_name: '*', value:)
+      elements = find_eles_by_predicate(class_name: class_name, value: value)
+      raise _no_such_element if elements.empty?
+      elements.first
+    end
+
+    # Find all elements exactly matching attribute case insensitive value.
+    # Note: Uses Predicate
+    # @param value [String] the value of the attribute that the element must have
+    # @param class_name [String] the tag name to match
+    # @return [Array<Element>]
+    def find_eles_by_predicate(class_name: '*', value:)
+      predicate =  if class_name == '*'
+                     %(name ==[c] "#{value}" || label ==[c] "#{value}" || value ==[c] "#{value}")
+                   else
+                     %(type == "#{class_name}" && ) +
+                       %((name ==[c] "#{value}" || label ==[c] "#{value}" || value ==[c] "#{value}"))
+                   end
+      @driver.find_elements_with_appium :predicate, predicate
+    end
+
     # Get the first tag by attribute that exactly matches value.
     # Note: Uses XPath
     # @param class_name [String] the tag name to match
@@ -293,6 +318,31 @@ module Appium
       @driver.find_elements :xpath, string_attr_include(class_name, attr, value)
     end
 
+    # Get the first elements that include insensitive value.
+    # Note: Uses Predicate
+    # @param value [String] the value of the attribute that the element must include
+    # @return [Element] the element of type tag who's attribute includes value
+    def find_ele_by_predicate_include(class_name: '*', value:)
+      elements = find_eles_by_predicate_include(class_name: class_name, value: value)
+      raise _no_such_element if elements.empty?
+      elements.first
+    end
+
+    # Get elements that include case insensitive value.
+    # Note: Uses Predicate
+    # @param value [String] the value of the attribute that the element must include
+    # @param class_name [String] the tag name to match
+    # @return [Array<Element>] the elements of type tag who's attribute includes value
+    def find_eles_by_predicate_include(class_name: '*', value:)
+      predicate = if class_name == '*'
+                    %(name contains[c] "#{value}" || label contains[c] "#{value}" || value contains[c] "#{value}")
+                  else
+                    %(type == "#{class_name}" && ) +
+                      %((name contains[c] "#{value}" || label contains[c] "#{value}" || value contains[c] "#{value}"))
+                  end
+      @driver.find_elements_with_appium :predicate, predicate
+    end
+
     # Get the first tag that matches class_name
     # @param class_name [String] the tag to match
     # @return [Element]
@@ -348,11 +398,20 @@ module Appium
     def tags_include(class_names:, value: nil)
       return unless class_names.is_a? Array
 
-      class_names.flat_map do |class_name|
-        if automation_name_is_xcuitest?
-          visible_elements = tags(class_name)
-          value ? elements_include(visible_elements, value) : visible_elements
-        else
+      if automation_name_is_xcuitest?
+        c_names = class_names.map { |class_name| %(type == "#{class_name}") }.join(' || ')
+
+        predicate = if value
+                      %((#{c_names}) && ) +
+                        %((name contains[c] "#{value}" || label contains[c] "#{value}" || value contains[c] "#{value}"))
+                    else
+                      c_names
+                    end
+
+        elements = @driver.find_elements_with_appium :predicate, predicate
+        select_visible_elements elements
+      else
+        class_names.flat_map do |class_name|
           value ? eles_by_json_visible_contains(class_name, value) : tags(class_name)
         end
       end
@@ -368,11 +427,20 @@ module Appium
     def tags_exact(class_names:, value: nil)
       return unless class_names.is_a? Array
 
-      class_names.flat_map do |class_name|
-        if automation_name_is_xcuitest?
-          visible_elements = tags(class_name)
-          value ? elements_exact(visible_elements, value) : visible_elements
-        else
+      if automation_name_is_xcuitest?
+        c_names = class_names.map { |class_name| %(type == "#{class_name}") }.join(' || ')
+
+        predicate = if value
+                      %((#{c_names}) && ) +
+                        %((name ==[c] "#{value}" || label ==[c] "#{value}" || value ==[c] "#{value}"))
+                    else
+                      c_names
+                    end
+
+        elements = @driver.find_elements_with_appium :predicate, predicate
+        select_visible_elements elements
+      else
+        class_names.flat_map do |class_name|
           value ? eles_by_json_visible_exact(class_name, value) : tags(class_name)
         end
       end