Add class chain (#515)

* add class chain

* fix rubocop

* add documentations

Author: KazuCocoa

docs/ios_xcuitest.md

@@ -53,6 +53,13 @@ textfield(value) # Return a XCUIElementTypeSecureTextField or XCUIElementTypeTex
 finds_exact(value) # Return any elements include `value` as its name attributes.
 ```
 
+### with Class Chain
+- require Appium 1.6.4+
+    - https://github.com/appium/appium-xcuitest-driver/pull/391
+    - https://github.com/appium/java-client/pull/599/files
+- WebDriverAgent
+    - https://github.com/facebook/WebDriverAgent/wiki/Queries
+
 ### with XPath
 - It is better to avoid XPath strategy.
     - https://github.com/appium/appium/blob/v1.6.2/docs/en/advanced-concepts/migrating-to-xcuitest.md#xpath-locator-strategy

ios_tests/lib/ios/specs/ios/mobile_methods.rb

@@ -0,0 +1,20 @@
+# rake ios[ios/mobile_methods]
+describe 'ios/mobile_methods' do
+  def before_first
+    screen.must_equal catalog
+  end
+
+  t 'an element with class chain' do
+    element = find_element :class_chain, 'XCUIElementTypeWindow/*/*/XCUIElementTypeStaticText'
+
+    element.name.must_equal catalog
+  end
+
+  t 'elements with class chain' do
+    elements = find_elements :class_chain, 'XCUIElementTypeWindow/*/*'
+
+    elements.size.must_equal 2
+    elements[0].name.must_equal catalog
+    elements[1].name.must_be_nil
+  end
+end

lib/appium_lib/ios/mobile_methods.rb

@@ -16,9 +16,23 @@ class << self
       #    find_elements :predicate, 'wdName == "Buttons"'
       #    find_elements :predicate, 'wdValue == "SearchBar" AND isWDDivisible == 1'
       #   ```
+      #
+      # @!method ios_class_chain_find
+      #   Only for XCUITest(WebDriverAgent)
+      #   find_element/s can be used with a [class chain]( https://github.com/facebook/WebDriverAgent/wiki/Queries)
+      #
+      #   ```ruby
+      #    # select the third child button of the first child window element
+      #    find_elements :class_chain, 'XCUIElementTypeWindow/XCUIElementTypeButton[3]'
+      #    # select all the children windows
+      #    find_elements :class_chain, 'XCUIElementTypeWindow'
+      #    # select the second last child of the second child window
+      #    find_elements :class_chain, 'XCUIElementTypeWindow[2]/XCUIElementTypeAny[-2]'
+      #   ```
       def extended(_mod)
         ::Appium::Driver::SearchContext::FINDERS[:uiautomation] = '-ios uiautomation'
         ::Appium::Driver::SearchContext::FINDERS[:predicate] = '-ios predicate string'
+        ::Appium::Driver::SearchContext::FINDERS[:class_chain] = '-ios class chain'
       end
     end # class << self
   end # module Ios