Add accessibility id locator strategy

imurchie · imurchie · commit 8b4b7dfbe5ce · 2014-04-09T15:07:20.000-07:00
diff --git a/README.md b/README.md
@@ -28,6 +28,8 @@ As a base for the following code examples, the following sets up the [UnitTest](
 environment:
 
 ```python
+# Android environment
+import unittest
 from appium import webdriver
 
 desired_caps = {}
@@ -41,6 +43,18 @@ desired_caps['app-activity'] = '.HomeScreenActivity'
 self.driver = webdriver.Remote('http://localhost:4723/wd/hub', desired_caps)
 ```
 
+```python
+# iOS environment
+import unittest
+from appium import webdriver
+
+desired_caps = {}
+desired_caps['app'] = PATH('../../apps/UICatalog.app.zip')
+
+self.driver = webdriver.Remote('http://localhost:4723/wd/hub', desired_caps)
+```
+
+
 ## Changed or added functionality
 
 The methods that do change are...
@@ -81,9 +95,46 @@ This allows elements in iOS applications to be found using recursive element
 search using the UIAutomation library. Adds the methods `driver.find_element_by_ios_uiautomation`
 and `driver.find_elements_by_ios_uiautomation`.
 
+```python
+el = self.driver.find_element_by_ios_uiautomation('.elements()[0]')
+self.assertEqual('UICatalog', el.get_attribute('name'))
+```
+
+```python
+els = self.driver.find_elements_by_ios_uiautomation('elements()')
+self.assertIsInstance(els, list)
+```
+
 
 ### Finding elements by Android UIAutomator search
 
 This allows elements in an Android application to be found using recursive element
 search using the UIAutomator library. Adds the methods `driver.find_element_by_android_uiautomator`
 and `driver.find_elements_by_android_uiautomator`.
+
+```python
+el = self.driver.find_element_by_android_uiautomator('new UiSelector().description("Animation")')
+self.assertIsNotNone(el)
+```
+
+```python
+els = self.driver.find_elements_by_android_uiautomator('new UiSelector().clickable(true)')
+self.assertIsInstance(els, list)
+```
+
+
+### Finding elements by Accessibility ID
+
+Allows for elements to be found using the "Accessibility ID". The methods take a
+string representing the accessibility id or label attached to a given element, e.g., for iOS the accessibility identifier and for Android the content-description. Adds the methods
+`driver.find_element_by_accessibility_id` and `find_elements_by_accessibility_id`.
+
+```python
+el = self.driver.find_element_by_accessibility_id('Animation')
+self.assertIsNotNone(el)
+```
+
+```python
+els = self.driver.find_elements_by_accessibility_id('Animation')
+self.assertIsInstance(els, list)
+```
diff --git a/appium/webdriver/common/mobileby.py b/appium/webdriver/common/mobileby.py
@@ -17,3 +17,4 @@
 class MobileBy(By):
     IOS_UIAUTOMATION = '-ios uiautomation'
     ANDROID_UIAUTOMATOR = '-android uiautomator'
+    ACCESSIBILITY_ID = 'accessibility id'
diff --git a/appium/webdriver/webdriver.py b/appium/webdriver/webdriver.py
@@ -36,6 +36,7 @@ def __init__(self, command_executor='http://127.0.0.1:4444/wd/hub',
         # add new method to the `find_by_*` pantheon
         By.IOS_UIAUTOMATION = MobileBy.IOS_UIAUTOMATION
         By.ANDROID_UIAUTOMATOR = MobileBy.ANDROID_UIAUTOMATOR
+        By.ACCESSIBILITY_ID = MobileBy.ACCESSIBILITY_ID
 
     @property
     def contexts(self):
@@ -101,6 +102,28 @@ def find_elements_by_android_uiautomator(self, uia_string):
         """
         return self.find_elements(by=By.ANDROID_UIAUTOMATOR, value=uia_string)
 
+    def find_element_by_accessibility_id(self, id):
+        """Finds an element by accessibility id.
+
+        :Args:
+         - id - a string corresponding to a recursive element search using the Id/Name that the native Accessibility options utilize
+
+        :Usage:
+            driver.find_element_by_accessibility_id()
+        """
+        return self.find_element(by=By.ACCESSIBILITY_ID, value=id)
+
+    def find_elements_by_accessibility_id(self, id):
+        """Finds elements by accessibility id.
+
+        :Args:
+         - id - a string corresponding to a recursive element search using the Id/Name that the native Accessibility options utilize
+
+        :Usage:
+            driver.find_elements_by_accessibility_id()
+        """
+        return self.find_elements(by=By.ACCESSIBILITY_ID, value=id)
+
     def _addCommands(self):
         self.command_executor._commands[Command.CONTEXTS] = \
             ('GET', '/session/$sessionId/contexts')
diff --git a/test/functional/android/find_by_accessibility_id_tests.py b/test/functional/android/find_by_accessibility_id_tests.py
@@ -0,0 +1,51 @@
+#!/usr/bin/env python
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+from time import sleep
+
+from appium import webdriver
+
+import unittest
+
+# Returns abs path relative to this file and not cwd
+PATH = lambda p: os.path.abspath(
+    os.path.join(os.path.dirname(__file__), p)
+)
+
+class FindByAccessibilityIDTests(unittest.TestCase):
+    def setUp(self):
+        desired_caps = {}
+        desired_caps['device'] = 'Android'
+        desired_caps['browserName'] = ''
+        desired_caps['version'] = '4.2'
+        desired_caps['app'] = PATH('../../apps/ApiDemos-debug.apk')
+        desired_caps['app-package'] = 'com.example.android.apis'
+        desired_caps['app-activity'] = '.ApiDemos'
+
+        self.driver = webdriver.Remote('http://localhost:4723/wd/hub', desired_caps)
+
+    def tearDown(self):
+        self.driver.quit()
+
+    def test_find_single_element(self):
+        el = self.driver.find_element_by_accessibility_id('Animation')
+        self.assertIsNotNone(el)
+
+    def test_find_multiple_elements(self):
+        els = self.driver.find_elements_by_accessibility_id('Animation')
+        self.assertIsInstance(els, list)
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/test/functional/android/find_by_uiautomator_tests.py b/test/functional/android/find_by_uiautomator_tests.py
@@ -16,7 +16,6 @@
 from time import sleep
 
 from appium import webdriver
-from appium.common.exceptions import NoSuchContextException
 
 import unittest
 
