add android datamatcher (#190)

* add android datamatcher

* update changelog

* add data matcher

* update the test and example

* tweak readme

Author: KazuCocoa

CHANGELOG.md

@@ -5,6 +5,7 @@ Read `release_notes.md` for commit level details.
 ## [Unreleased]
 
 ### Enhancements
+- Add `:data_matcher` find_element/s attribute [appium-espresso-driver#386](https://github.com/appium/appium-espresso-driver/pull/386)
 
 ### Bug fixes
 

README.md

@@ -40,7 +40,7 @@ $ appium --relaxed-security # To run all tests in local
  ```bash
 $ bundle install
 $ rake test:func:android # Andorid, uiautomator2
-$ AUTOMATION_NAME=espresso rake test:func:android # Andorid, uiautomator2
+$ AUTOMATION_NAME_DROID=espresso rake test:func:android # Andorid, uiautomator2
 $ rake test:func:ios     # iOS
 ```
 

lib/appium_lib_core/common/base/search_context.rb

@@ -12,13 +12,14 @@ module SearchContext
           # Android
           uiautomator:          '-android uiautomator', # Unavailable in Espresso
           viewtag:              '-android viewtag',     # Available in Espresso
+          data_matcher:         '-android datamatcher', # Available in Espresso
           # iOS
           uiautomation:         '-ios uiautomation',
           predicate:            '-ios predicate string',
           class_chain:          '-ios class chain',
-          # Windows
+          # Windows with windows prefix
           windows_uiautomation: '-windows uiautomation',
-          # Tizen
+          # Tizen with Tizen prefix
           tizen_uiautomation:   '-tizen uiautomation'
         )
         # rubocop:enable Layout/AlignHash
@@ -49,47 +50,49 @@ module SearchContext
         # @example Find element with each keys
         #
         #     # with accessibility id. All platforms.
-        #     find_elements :accessibility_id, 'Animation'
-        #     find_elements :accessibility_id, 'Animation'
+        #     @driver.find_elements :accessibility_id, 'Animation'
+        #     @driver.find_elements :accessibility_id, 'Animation'
         #
         #     # with base64 encoded template image. All platforms.
-        #     find_elements :image, Base64.strict_encode64(File.read(file_path))
+        #     @driver.find_elements :image, Base64.strict_encode64(File.read(file_path))
         #
         #     # For Android
         #     ## With uiautomator
-        #     find_elements :uiautomator, 'new UiSelector().clickable(true)'
+        #     @driver.find_elements :uiautomator, 'new UiSelector().clickable(true)'
         #     ## With viewtag, but only for Espresso
         #     ## `setTag`/`getTag` in https://developer.android.com/reference/android/view/View
-        #     find_elements :viewtag, 'new UiSelector().clickable(true)'
+        #     @driver.find_elements :viewtag, 'new UiSelector().clickable(true)'
+        #     # With data_matcher. The argument should be JSON format.
+        #     @driver.find_elements :data_matcher, { name: 'hasEntry', args: %w(title Animation) }.to_json
         #
         #     # For iOS
         #     ## With :predicate
-        #     find_elements :predicate, "isWDVisible == 1"
-        #     find_elements :predicate, 'wdName == "Buttons"'
-        #     find_elements :predicate, 'wdValue == "SearchBar" AND isWDDivisible == 1'
+        #     @driver.find_elements :predicate, "isWDVisible == 1"
+        #     @driver.find_elements :predicate, 'wdName == "Buttons"'
+        #     @driver.find_elements :predicate, 'wdValue == "SearchBar" AND isWDDivisible == 1'
         #
         #     ## With Class Chain
         #     ### select the third child button of the first child window element
-        #     find_elements :class_chain, 'XCUIElementTypeWindow/XCUIElementTypeButton[3]'
+        #     @driver.find_elements :class_chain, 'XCUIElementTypeWindow/XCUIElementTypeButton[3]'
         #     ### select all the children windows
-        #     find_elements :class_chain, 'XCUIElementTypeWindow'
+        #     @driver.find_elements :class_chain, 'XCUIElementTypeWindow'
         #     ### select the second last child of the second child window
-        #     find_elements :class_chain, 'XCUIElementTypeWindow[2]/XCUIElementTypeAny[-2]'
+        #     @driver.find_elements :class_chain, 'XCUIElementTypeWindow[2]/XCUIElementTypeAny[-2]'
         #     ### matching predicate. <code>`</code> is the mark.
-        #     find_elements :class_chain, 'XCUIElementTypeWindow[`visible = 1][`name = "bla"`]'
+        #     @driver.find_elements :class_chain, 'XCUIElementTypeWindow[`visible = 1][`name = "bla"`]'
         #     ### containing predicate. `$` is the mark.
         #     ### Require appium-xcuitest-driver 2.54.0+. PR: https://github.com/facebook/WebDriverAgent/pull/707/files
-        #     find_elements :class_chain, 'XCUIElementTypeWindow[$name = \"bla$$$bla\"$]'
+        #     @driver.find_elements :class_chain, 'XCUIElementTypeWindow[$name = \"bla$$$bla\"$]'
         #     e = find_element :class_chain, "**/XCUIElementTypeWindow[$name == 'Buttons'$]"
         #     e.tag_name #=> "XCUIElementTypeWindow"
         #     e = find_element :class_chain, "**/XCUIElementTypeStaticText[$name == 'Buttons'$]"
         #     e.tag_name #=> "XCUIElementTypeStaticText"
         #
         #     # For Windows
-        #     find_elements :windows_uiautomation, '....'
+        #     @driver.find_elements :windows_uiautomation, '....'
         #
         #     # For Tizen
-        #     find_elements :tizen_uiautomation, '....'
+        #     @driver.find_elements :tizen_uiautomation, '....'
         #
         def find_element(*args)
           how, what = extract_args(args)

test/functional/android/android/search_context_test.rb

@@ -29,6 +29,17 @@ def test_viewtag
         e = @driver.find_elements :viewtag, 'example'
         assert_equal 0, e.size
       end
+
+      def test_datamatcher
+        skip 'UiAutomator2 does not support viewtag' if @@core.automation_name != :espresso
+
+        e = @driver.find_elements :data_matcher, { name: 'hasEntry', args: %w(title Animation) }.to_json
+        assert_equal 1, e.size
+
+        e.first.click
+        @driver.find_element :accessibility_id, 'Cloning' # no error
+        @driver.back
+      end
     end
   end
 end

test/unit/driver_test.rb

@@ -103,7 +103,7 @@ def test_default_timeout_for_http_client_with_direct
 
     # https://www.w3.org/TR/webdriver1/
     def test_search_context_in_element_class
-      assert_equal 20, ::Selenium::WebDriver::Element::FINDERS.length
+      assert_equal 21, ::Selenium::WebDriver::Element::FINDERS.length
       assert_equal({ class: 'class name',
                      class_name: 'class name',
                      css: 'css selector',                    # Defined in W3C spec
@@ -119,6 +119,7 @@ def test_search_context_in_element_class
                      custom: '-custom',
                      uiautomator: '-android uiautomator',
                      viewtag: '-android viewtag',
+                     data_matcher: '-android datamatcher',
                      uiautomation: '-ios uiautomation',
                      predicate: '-ios predicate string',
                      class_chain: '-ios class chain',