Move search context methods from webdriver and webelement to search_context (#461)

* Move ios search context methods to search_context file

* Move android search text methods

* Move windows search context

* Move mobile search context

* Divided search_context into each class

* Move custom and image methods

* Move contents in search_context.py to __init__.py

* Add rtype to each docstring for auto completion in IDE

* Add comments

Author: ki4070ma

appium/webdriver/extensions/search_context/__init__.py

@@ -0,0 +1,43 @@
+#!/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.
+
+# pylint: disable=abstract-method
+
+from selenium import webdriver
+from selenium.webdriver.remote.webelement import \
+    WebElement as SeleniumWebElement
+
+from .android import AndroidSearchContext
+from .custom import CustomSearchContext
+from .ios import iOSSearchContext
+from .mobile import MobileSearchContext
+from .windows import WindowsSearchContext
+
+
+class AppiumSearchContext(webdriver.Remote,
+                          AndroidSearchContext,
+                          CustomSearchContext,
+                          iOSSearchContext,
+                          MobileSearchContext,
+                          WindowsSearchContext):
+    """Returns appium driver search conext"""
+
+
+class AppiumWebElementSearchContext(SeleniumWebElement,
+                                    AndroidSearchContext,
+                                    CustomSearchContext,
+                                    iOSSearchContext,
+                                    MobileSearchContext,
+                                    WindowsSearchContext):
+    """Returns appium web element search context"""

appium/webdriver/extensions/search_context.py renamed to appium/webdriver/extensions/search_context/android.py

@@ -16,21 +16,9 @@
 
 import json
 
-from selenium import webdriver
-from selenium.webdriver.remote.webelement import \
-    WebElement as SeleniumWebElement
-
 from appium.webdriver.common.mobileby import MobileBy
 
-
-class BaseSearchContext(object):
-    """Used by each search context. Dummy find_element/s are for preventing pylint error"""
-
-    def find_element(self, by=None, value=None):
-        raise NotImplementedError
-
-    def find_elements(self, by=None, value=None):
-        raise NotImplementedError
+from .base_search_context import BaseSearchContext
 
 
 class AndroidSearchContext(BaseSearchContext):
@@ -58,6 +46,9 @@ def find_element_by_android_data_matcher(self, name=None, args=None, className=N
 
         Usage:
             driver.find_element_by_android_data_matcher(name='hasEntry', args=['title', 'Animation'])
+
+        # To enable auto completion in PyCharm(IDE)
+        :rtype: `appium.webdriver.webelement.WebElement`
         """
 
         return self.find_element(
@@ -83,6 +74,8 @@ def find_elements_by_android_data_matcher(self, name=None, args=None, className=
 
         Usage:
             driver.find_elements_by_android_data_matcher(name='hasEntry', args=['title', 'Animation'])
+
+        :rtype: `appium.webdriver.webelement.WebElement`
         """
 
         return self.find_elements(
@@ -99,12 +92,70 @@ def _build_data_matcher(self, name=None, args=None, className=None):
 
         return json.dumps(result)
 
+    def find_element_by_android_uiautomator(self, uia_string):
+        """Finds element by uiautomator in Android.
+
+        Args:
+            uia_string: The element name in the Android UIAutomator library
+
+        Usage:
+            driver.find_element_by_android_uiautomator('.elements()[1].cells()[2]')
+
+        Returns:
+            `appium.webdriver.webelement.WebElement`
+
+        :rtype: `appium.webdriver.webelement.WebElement`
+        """
+        return self.find_element(by=MobileBy.ANDROID_UIAUTOMATOR, value=uia_string)
+
+    def find_elements_by_android_uiautomator(self, uia_string):
+        """Finds elements by uiautomator in Android.
+
+        Args:
+            uia_string (str): The element name in the Android UIAutomator library
+
+        Usage:
+            driver.find_elements_by_android_uiautomator('.elements()[1].cells()[2]')
+
+        Returns:
+            :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`
+
+        :rtype: list of `appium.webdriver.webelement.WebElement`
+        """
+        return self.find_elements(by=MobileBy.ANDROID_UIAUTOMATOR, value=uia_string)
+
+    def find_element_by_android_viewtag(self, tag):
+        """Finds element by [View#tags](https://developer.android.com/reference/android/view/View#tags) in Android.
 
-class AppiumSearchContext(webdriver.Remote,
-                          AndroidSearchContext):
-    """Returns appium driver search conext"""
+        It works with [Espresso Driver](https://github.com/appium/appium-espresso-driver).
+
+        Args:
+            tag (str): The tag name of the view to look for
 
+        Usage:
+            driver.find_element_by_android_viewtag('a tag name')
+
+        Returns:
+            `appium.webdriver.webelement.WebElement`
+
+        :rtype: `appium.webdriver.webelement.WebElement`
+        """
+        return self.find_element(by=MobileBy.ANDROID_VIEWTAG, value=tag)
 
-class AppiumWebElementSearchContext(SeleniumWebElement,
-                                    AndroidSearchContext):
-    """Returns appium web element search context"""
+    def find_elements_by_android_viewtag(self, tag):
+        """Finds element by [View#tags](https://developer.android.com/reference/android/view/View#tags) in Android.
+
+        It works with [Espresso Driver](https://github.com/appium/appium-espresso-driver).
+
+        Args:
+            tag (str): The tag name of the view to look for
+
+        Usage:
+            driver.find_elements_by_android_viewtag('a tag name')
+
+        Returns:
+            :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`
+
+        :rtype: list of `appium.webdriver.webelement.WebElement`
+        """
+        return self.find_elements(by=MobileBy.ANDROID_VIEWTAG, value=tag)

appium/webdriver/extensions/search_context/base_search_context.py

@@ -0,0 +1,25 @@
+#!/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.
+
+# pylint: disable=abstract-method
+
+
+class BaseSearchContext(object):
+    """Used by each search context. Dummy find_element/s are for preventing pylint error"""
+
+    def find_element(self, by=None, value=None):
+        raise NotImplementedError
+
+    def find_elements(self, by=None, value=None):
+        raise NotImplementedError

appium/webdriver/extensions/search_context/custom.py

@@ -0,0 +1,62 @@
+#!/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.
+
+# pylint: disable=abstract-method
+
+from appium.webdriver.common.mobileby import MobileBy
+
+from .base_search_context import BaseSearchContext
+
+
+class CustomSearchContext(BaseSearchContext):
+    """Define search context for custom plugin"""
+
+    def find_element_by_custom(self, selector):
+        """Finds an element in conjunction with a custom element finding plugin
+
+        Args:
+            selector (str): a string of the form "module:selector", where "module" is
+                the shortcut name given in the customFindModules capability, and
+                "selector" is the string that will be passed to the custom element
+                finding plugin itself
+
+        Usage:
+            driver.find_element_by_custom("foo:bar")
+
+        Returns:
+            `appium.webdriver.webelement.WebElement`
+
+        # To enable auto completion in PyCharm(IDE)
+        :rtype: `appium.webdriver.webelement.WebElement`
+        """
+        return self.find_element(by=MobileBy.CUSTOM, value=selector)
+
+    def find_elements_by_custom(self, selector):
+        """Finds elements in conjunction with a custom element finding plugin
+
+        Args:
+            selector: a string of the form "module:selector", where "module" is
+                the shortcut name given in the customFindModules capability, and
+                "selector" is the string that will be passed to the custom element
+                finding plugin itself
+
+        Usage:
+            driver.find_elements_by_custom("foo:bar")
+
+        Returns:
+            :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`
+
+        :rtype: list of `appium.webdriver.webelement.WebElement`
+        """
+        return self.find_elements(by=MobileBy.CUSTOM, value=selector)

appium/webdriver/extensions/search_context/ios.py

@@ -0,0 +1,120 @@
+#!/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.
+
+# pylint: disable=abstract-method
+
+from appium.webdriver.common.mobileby import MobileBy
+
+from .base_search_context import BaseSearchContext
+
+
+class iOSSearchContext(BaseSearchContext):
+    """Define search context for iOS"""
+
+    def find_element_by_ios_uiautomation(self, uia_string):
+        """Finds an element by uiautomation in iOS.
+
+        Args:
+            uia_string (str): The element name in the iOS UIAutomation library
+
+        Usage:
+            driver.find_element_by_ios_uiautomation('.elements()[1].cells()[2]')
+
+        Returns:
+            `appium.webdriver.webelement.WebElement`
+
+        # To enable auto completion in PyCharm(IDE)
+        :rtype: `appium.webdriver.webelement.WebElement`
+        """
+        return self.find_element(by=MobileBy.IOS_UIAUTOMATION, value=uia_string)
+
+    def find_elements_by_ios_uiautomation(self, uia_string):
+        """Finds elements by uiautomation in iOS.
+
+        Args:
+            uia_string (str): The element name in the iOS UIAutomation library
+
+        Usage:
+            driver.find_elements_by_ios_uiautomation('.elements()[1].cells()[2]')
+
+        Returns:
+            :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`
+
+        :rtype: list of `appium.webdriver.webelement.WebElement`
+        """
+        return self.find_elements(by=MobileBy.IOS_UIAUTOMATION, value=uia_string)
+
+    def find_element_by_ios_predicate(self, predicate_string):
+        """Find an element by ios predicate string.
+
+        Args:
+            predicate_string (str): The predicate string
+
+        Usage:
+            driver.find_element_by_ios_predicate('label == "myLabel"')
+
+        Returns:
+            `appium.webdriver.webelement.WebElement`
+
+        :rtype: `appium.webdriver.webelement.WebElement`
+        """
+        return self.find_element(by=MobileBy.IOS_PREDICATE, value=predicate_string)
+
+    def find_elements_by_ios_predicate(self, predicate_string):
+        """Finds elements by ios predicate string.
+
+        Args:
+            predicate_string (str): The predicate string
+
+        Usage:
+            driver.find_elements_by_ios_predicate('label == "myLabel"')
+
+        Returns:
+            :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`
+
+        :rtype: list of `appium.webdriver.webelement.WebElement`
+        """
+        return self.find_elements(by=MobileBy.IOS_PREDICATE, value=predicate_string)
+
+    def find_element_by_ios_class_chain(self, class_chain_string):
+        """Find an element by ios class chain string.
+
+        Args:
+            class_chain_string (str): The class chain string
+
+        Usage:
+            driver.find_element_by_ios_class_chain('XCUIElementTypeWindow/XCUIElementTypeButton[3]')
+
+        Returns:
+            `appium.webdriver.webelement.WebElement`
+
+        :rtype: `appium.webdriver.webelement.WebElement`
+        """
+        return self.find_element(by=MobileBy.IOS_CLASS_CHAIN, value=class_chain_string)
+
+    def find_elements_by_ios_class_chain(self, class_chain_string):
+        """Finds elements by ios class chain string.
+
+        Args:
+            class_chain_string (str): The class chain string
+
+        Usage:
+            driver.find_elements_by_ios_class_chain('XCUIElementTypeWindow[2]/XCUIElementTypeAny[-2]')
+
+        Returns:
+            :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`
+
+        :rtype: list of `appium.webdriver.webelement.WebElement`
+        """
+        return self.find_elements(by=MobileBy.IOS_CLASS_CHAIN, value=class_chain_string)