From 8b09e8a847370a31bb32aec2249a8296598e478b Mon Sep 17 00:00:00 2001 From: Kazuaki Matsuo Date: Wed, 24 Nov 2021 01:27:42 -0800 Subject: [PATCH] chore: add deprecated mark for find_element_by* --- .../extensions/search_context/android.py | 54 ++++++++++++++++--- .../extensions/search_context/custom.py | 17 +++++- .../extensions/search_context/ios.py | 49 ++++++++++++++--- .../extensions/search_context/mobile.py | 18 ++++++- appium/webdriver/webdriver.py | 24 ++++++--- appium/webdriver/webelement.py | 19 +++---- 6 files changed, 145 insertions(+), 36 deletions(-) diff --git a/appium/webdriver/extensions/search_context/android.py b/appium/webdriver/extensions/search_context/android.py index 87a87e3d..659a4cd8 100644 --- a/appium/webdriver/extensions/search_context/android.py +++ b/appium/webdriver/extensions/search_context/android.py @@ -17,6 +17,7 @@ import json from typing import TYPE_CHECKING, Any, List, Optional, TypeVar, Union +from appium.common.logger import logger from appium.webdriver.common.mobileby import MobileBy from .base_search_context import BaseSearchContext @@ -33,7 +34,10 @@ class AndroidSearchContext(BaseSearchContext): def find_element_by_android_view_matcher( self: T, name: Optional[str] = None, args: Optional[Any] = None, className: Optional[str] = None ) -> 'WebElement': - """Finds element by [onView](https://developer.android.com/training/testing/espresso/basics) in Android + """ + [Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_VIEW_MATCHER' instead. + + Finds element by [onView](https://developer.android.com/training/testing/espresso/basics) in Android It works with [Espresso Driver](https://github.com/appium/appium-espresso-driver). @@ -57,6 +61,8 @@ def find_element_by_android_view_matcher( driver.find_element_by_android_view_matcher(name='withText', args=['Accessibility'], className='ViewMatchers') """ + logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_VIEW_MATCHER' instead.") + return self.find_element( by=MobileBy.ANDROID_VIEW_MATCHER, value=self._build_data_matcher(name=name, args=args, className=className) ) @@ -64,7 +70,10 @@ def find_element_by_android_view_matcher( def find_element_by_android_data_matcher( self: T, name: Optional[str] = None, args: Optional[Any] = None, className: Optional[str] = None ) -> 'WebElement': - """Finds element by + """ + [Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_DATA_MATCHER' instead. + + Finds element by [onData](https://medium.com/androiddevelopers/adapterviews-and-espresso-f4172aa853cf) in Android It works with [Espresso Driver](https://github.com/appium/appium-espresso-driver). @@ -89,6 +98,8 @@ def find_element_by_android_data_matcher( driver.find_element_by_android_data_matcher(name='hasEntry', args=['title', 'Animation']) """ + logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_DATA_MATCHER' instead.") + return self.find_element( by=MobileBy.ANDROID_DATA_MATCHER, value=self._build_data_matcher(name=name, args=args, className=className) ) @@ -96,7 +107,10 @@ def find_element_by_android_data_matcher( def find_elements_by_android_data_matcher( self: T, name: Optional[str] = None, args: Optional[Any] = None, className: Optional[str] = None ) -> List['WebElement']: - """Finds elements by + """ + [Deprecated] Please use 'find_elements' with 'MobileBy.ANDROID_DATA_MATCHER' instead. + + Finds elements by [onData](https://medium.com/androiddevelopers/adapterviews-and-espresso-f4172aa853cf) in Android It works with [Espresso Driver](https://github.com/appium/appium-espresso-driver). @@ -117,6 +131,8 @@ def find_elements_by_android_data_matcher( driver.find_elements_by_android_data_matcher(name='hasEntry', args=['title', 'Animation']) """ + logger.warning("[Deprecated] Please use 'find_elements' with 'MobileBy.ANDROID_DATA_MATCHER' instead.") + return self.find_elements( by=MobileBy.ANDROID_DATA_MATCHER, value=self._build_data_matcher(name=name, args=args, className=className) ) @@ -133,7 +149,10 @@ def _build_data_matcher( return json.dumps(result) def find_element_by_android_uiautomator(self: T, uia_string: str) -> 'WebElement': - """Finds element by uiautomator in Android. + """ + [Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_UIAUTOMATOR' instead. + + Finds element by uiautomator in Android. Args: uia_string: The element name in the Android UIAutomator library @@ -144,10 +163,16 @@ def find_element_by_android_uiautomator(self: T, uia_string: str) -> 'WebElement Returns: `appium.webdriver.webelement.WebElement`: The found element """ + + logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_UIAUTOMATOR' instead.") + return self.find_element(by=MobileBy.ANDROID_UIAUTOMATOR, value=uia_string) def find_elements_by_android_uiautomator(self: T, uia_string: str) -> List['WebElement']: - """Finds elements by uiautomator in Android. + """ + [Deprecated] Please use 'find_elements' with 'MobileBy.ANDROID_UIAUTOMATOR' instead. + + Finds elements by uiautomator in Android. Args: uia_string: The element name in the Android UIAutomator library @@ -158,10 +183,16 @@ def find_elements_by_android_uiautomator(self: T, uia_string: str) -> List['WebE Returns: :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`: The found elements """ + + logger.warning("[Deprecated] Please use 'find_elements' with 'MobileBy.ANDROID_UIAUTOMATOR' instead.") + return self.find_elements(by=MobileBy.ANDROID_UIAUTOMATOR, value=uia_string) def find_element_by_android_viewtag(self: T, tag: str) -> 'WebElement': - """Finds element by [View#tags](https://developer.android.com/reference/android/view/View#tags) in Android. + """ + [Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_VIEWTAG' instead. + + 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). @@ -174,10 +205,16 @@ def find_element_by_android_viewtag(self: T, tag: str) -> 'WebElement': Returns: `appium.webdriver.webelement.WebElement`: The found element """ + + logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_VIEWTAG' instead.") + return self.find_element(by=MobileBy.ANDROID_VIEWTAG, value=tag) def find_elements_by_android_viewtag(self: T, tag: str) -> List['WebElement']: - """Finds element by [View#tags](https://developer.android.com/reference/android/view/View#tags) in Android. + """ + [Deprecated] Please use 'find_elements' with 'MobileBy.ANDROID_VIEWTAG' instead. + + 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). @@ -190,4 +227,7 @@ def find_elements_by_android_viewtag(self: T, tag: str) -> List['WebElement']: Returns: :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`: The found elements """ + + logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_VIEWTAG' instead.") + return self.find_elements(by=MobileBy.ANDROID_VIEWTAG, value=tag) diff --git a/appium/webdriver/extensions/search_context/custom.py b/appium/webdriver/extensions/search_context/custom.py index e202728e..f58594e9 100644 --- a/appium/webdriver/extensions/search_context/custom.py +++ b/appium/webdriver/extensions/search_context/custom.py @@ -16,6 +16,7 @@ from typing import TYPE_CHECKING, List, TypeVar, Union +from appium.common.logger import logger from appium.webdriver.common.mobileby import MobileBy from .base_search_context import BaseSearchContext @@ -30,7 +31,10 @@ class CustomSearchContext(BaseSearchContext): """Define search context for custom plugin""" def find_element_by_custom(self: T, selector: str) -> 'WebElement': - """Finds an element in conjunction with a custom element finding plugin + """ + [Deprecated] Please use 'find_element' with 'MobileBy.CUSTOM' instead. + + Finds an element in conjunction with a custom element finding plugin Args: selector: a string of the form "module:selector", where "module" is @@ -45,10 +49,16 @@ def find_element_by_custom(self: T, selector: str) -> 'WebElement': `appium.webdriver.webelement.WebElement`: The found element """ + + logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.CUSTOM' instead.") + return self.find_element(by=MobileBy.CUSTOM, value=selector) def find_elements_by_custom(self: T, selector: str) -> List['WebElement']: - """Finds elements in conjunction with a custom element finding plugin + """ + [Deprecated] Please use 'find_elements' with 'MobileBy.CUSTOM' instead. + + Finds elements in conjunction with a custom element finding plugin Args: selector: a string of the form "module:selector", where "module" is @@ -62,4 +72,7 @@ def find_elements_by_custom(self: T, selector: str) -> List['WebElement']: Returns: :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`: The found elements """ + + logger.warning("[Deprecated] Please use 'find_elements' with 'MobileBy.CUSTOM' instead.") + return self.find_elements(by=MobileBy.CUSTOM, value=selector) diff --git a/appium/webdriver/extensions/search_context/ios.py b/appium/webdriver/extensions/search_context/ios.py index b97bfa9c..826b4a79 100644 --- a/appium/webdriver/extensions/search_context/ios.py +++ b/appium/webdriver/extensions/search_context/ios.py @@ -16,6 +16,7 @@ from typing import TYPE_CHECKING, List, TypeVar, Union +from appium.common.logger import logger from appium.webdriver.common.mobileby import MobileBy from .base_search_context import BaseSearchContext @@ -30,7 +31,10 @@ class iOSSearchContext(BaseSearchContext): """Define search context for iOS""" def find_element_by_ios_uiautomation(self: T, uia_string: str) -> 'WebElement': - """Finds an element by uiautomation in iOS. + """ + [Deprecated] Please use 'find_element' with 'MobileBy.IOS_UIAUTOMATION' instead. + + Finds an element by uiautomation in iOS. Args: uia_string: The element name in the iOS UIAutomation library @@ -42,10 +46,16 @@ def find_element_by_ios_uiautomation(self: T, uia_string: str) -> 'WebElement': `appium.webdriver.webelement.WebElement`: The found element """ + + logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.IOS_UIAUTOMATION' instead.") + return self.find_element(by=MobileBy.IOS_UIAUTOMATION, value=uia_string) def find_elements_by_ios_uiautomation(self: T, uia_string: str) -> List['WebElement']: - """Finds elements by uiautomation in iOS. + """ + [Deprecated] Please use 'find_elements' with 'MobileBy.IOS_UIAUTOMATION' instead. + + Finds elements by uiautomation in iOS. Args: uia_string: The element name in the iOS UIAutomation library @@ -57,10 +67,16 @@ def find_elements_by_ios_uiautomation(self: T, uia_string: str) -> List['WebElem :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`: The found elements """ + + logger.warning("[Deprecated] Please use 'find_elements' with 'MobileBy.IOS_UIAUTOMATION' instead.") + return self.find_elements(by=MobileBy.IOS_UIAUTOMATION, value=uia_string) def find_element_by_ios_predicate(self: T, predicate_string: str) -> 'WebElement': - """Find an element by ios predicate string. + """ + [Deprecated] Please use 'find_element' with 'MobileBy.IOS_PREDICATE' instead. + + Find an element by ios predicate string. Args: predicate_string: The predicate string @@ -72,10 +88,16 @@ def find_element_by_ios_predicate(self: T, predicate_string: str) -> 'WebElement `appium.webdriver.webelement.WebElement`: The found element """ + + logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.IOS_PREDICATE' instead.") + return self.find_element(by=MobileBy.IOS_PREDICATE, value=predicate_string) def find_elements_by_ios_predicate(self: T, predicate_string: str) -> List['WebElement']: - """Finds elements by ios predicate string. + """ + [Deprecated] Please use 'find_elements' with 'MobileBy.IOS_PREDICATE' instead. + + Finds elements by ios predicate string. Args: predicate_string: The predicate string @@ -86,10 +108,16 @@ def find_elements_by_ios_predicate(self: T, predicate_string: str) -> List['WebE Returns: :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`: The found elements """ + + logger.warning("[Deprecated] Please use 'find_elements' with 'MobileBy.IOS_PREDICATE' instead.") + return self.find_elements(by=MobileBy.IOS_PREDICATE, value=predicate_string) def find_element_by_ios_class_chain(self: T, class_chain_string: str) -> 'WebElement': - """Find an element by ios class chain string. + """ + [Deprecated] Please use 'find_element' with 'MobileBy.IOS_CLASS_CHAIN' instead. + + Find an element by ios class chain string. Args: class_chain_string: The class chain string @@ -100,10 +128,16 @@ def find_element_by_ios_class_chain(self: T, class_chain_string: str) -> 'WebEle Returns: `appium.webdriver.webelement.WebElement`: The found element """ + + logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.IOS_CLASS_CHAIN' instead.") + return self.find_element(by=MobileBy.IOS_CLASS_CHAIN, value=class_chain_string) def find_elements_by_ios_class_chain(self: T, class_chain_string: str) -> List['WebElement']: - """Finds elements by ios class chain string. + """ + [Deprecated] Please use 'find_elements' with 'MobileBy.IOS_CLASS_CHAIN' instead. + + Finds elements by ios class chain string. Args: class_chain_string: The class chain string @@ -114,4 +148,7 @@ def find_elements_by_ios_class_chain(self: T, class_chain_string: str) -> List[' Returns: :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`: The found elements """ + + logger.warning("[Deprecated] Please use 'find_elements' with 'MobileBy.IOS_CLASS_CHAIN' instead.") + return self.find_elements(by=MobileBy.IOS_CLASS_CHAIN, value=class_chain_string) diff --git a/appium/webdriver/extensions/search_context/mobile.py b/appium/webdriver/extensions/search_context/mobile.py index 52b16d71..14ce7508 100644 --- a/appium/webdriver/extensions/search_context/mobile.py +++ b/appium/webdriver/extensions/search_context/mobile.py @@ -17,6 +17,7 @@ import base64 from typing import TYPE_CHECKING, List, TypeVar, Union +from appium.common.logger import logger from appium.webdriver.common.mobileby import MobileBy from .base_search_context import BaseSearchContext @@ -31,7 +32,10 @@ class MobileSearchContext(BaseSearchContext): """Define search context for Mobile(Android, iOS)""" def find_element_by_accessibility_id(self: T, accessibility_id: str) -> 'WebElement': - """Finds an element by accessibility id. + """ + [Deprecated] Please use 'find_element' with 'MobileBy.ACCESSIBILITY_ID' instead. + + Finds an element by accessibility id. Args: accessibility_id: A string corresponding to a recursive element search using the @@ -44,10 +48,16 @@ def find_element_by_accessibility_id(self: T, accessibility_id: str) -> 'WebElem `appium.webdriver.webelement.WebElement`: The found element """ + + logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.ACCESSIBILITY_ID' instead.") + return self.find_element(by=MobileBy.ACCESSIBILITY_ID, value=accessibility_id) def find_elements_by_accessibility_id(self: T, accessibility_id: str) -> List['WebElement']: - """Finds elements by accessibility id. + """ + [Deprecated] Please use 'find_elements' with 'MobileBy.ACCESSIBILITY_ID' instead. + + Finds elements by accessibility id. Args: accessibility_id: a string corresponding to a recursive element search using the @@ -60,6 +70,9 @@ def find_elements_by_accessibility_id(self: T, accessibility_id: str) -> List['W :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`: The found elements """ + + logger.warning("[Deprecated] Please use 'find_elements' with 'MobileBy.ACCESSIBILITY_ID' instead.") + return self.find_elements(by=MobileBy.ACCESSIBILITY_ID, value=accessibility_id) def find_element_by_image(self: T, img_path: str) -> 'WebElement': @@ -73,6 +86,7 @@ def find_element_by_image(self: T, img_path: str) -> 'WebElement': Returns: `appium.webdriver.webelement.WebElement`: The found element """ + with open(img_path, 'rb') as i_file: b64_data = base64.b64encode(i_file.read()).decode('UTF-8') diff --git a/appium/webdriver/webdriver.py b/appium/webdriver/webdriver.py index 98b11b55..f5661bc1 100644 --- a/appium/webdriver/webdriver.py +++ b/appium/webdriver/webdriver.py @@ -377,13 +377,16 @@ def _merge_capabilities(self, capabilities: Dict) -> Dict[str, Any]: w3c_caps = _make_w3c_caps(capabilities) return {'capabilities': w3c_caps, 'desiredCapabilities': capabilities} - def find_element(self, by: str = By.ID, value: Union[str, Dict] = None) -> MobileWebElement: - """'Private' method used by the find_element_by_* methods. + def find_element(self, by: str = MobileBy.ID, value: Union[str, Dict] = None) -> MobileWebElement: + """ + Find an element given a MobileBy strategy and locator - Override for Appium + Args: + by: The strategy + value: The locator Usage: - Use the corresponding find_element_by_* instead of this. + driver.find_element(by=MobileBy.ACCESSIBILITY_ID, value='accessibility_id') Returns: `appium.webdriver.webelement.WebElement`: The found element @@ -404,13 +407,18 @@ def find_element(self, by: str = By.ID, value: Union[str, Dict] = None) -> Mobil return self.execute(RemoteCommand.FIND_ELEMENT, {'using': by, 'value': value})['value'] - def find_elements(self, by: str = By.ID, value: Union[str, Dict] = None) -> Union[List[MobileWebElement], List]: - """'Private' method used by the find_elements_by_* methods. + def find_elements( + self, by: str = MobileBy.ID, value: Union[str, Dict] = None + ) -> Union[List[MobileWebElement], List]: + """ + Find elements given a MobileBy strategy and locator - Override for Appium + Args: + by: The strategy + value: The locator Usage: - Use the corresponding find_elements_by_* instead of this. + driver.find_elements(by=MobileBy.ACCESSIBILITY_ID, value='accessibility_id') Returns: :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`: The found elements diff --git a/appium/webdriver/webelement.py b/appium/webdriver/webelement.py index 9542377f..17456dd5 100644 --- a/appium/webdriver/webelement.py +++ b/appium/webdriver/webelement.py @@ -14,10 +14,11 @@ from typing import Dict, List, Optional, TypeVar, Union -from selenium.webdriver.common.by import By from selenium.webdriver.common.utils import keys_to_typing from selenium.webdriver.remote.command import Command as RemoteCommand +from appium.webdriver.common.mobileby import MobileBy + from .extensions.search_context import AppiumWebElementSearchContext from .mobilecommand import MobileCommand as Command @@ -77,8 +78,8 @@ def is_displayed(self) -> bool: """ return self._execute(RemoteCommand.IS_ELEMENT_DISPLAYED)['value'] - def find_element(self, by: str = By.ID, value: Union[str, Dict] = None) -> T: - """Find an element given a By strategy and locator + def find_element(self, by: str = MobileBy.ID, value: Union[str, Dict] = None) -> T: + """Find an element given a MobileBy strategy and locator Override for Appium @@ -89,7 +90,7 @@ def find_element(self, by: str = By.ID, value: Union[str, Dict] = None) -> T: value: The locator Usage: - element = element.find_element(By.ID, 'foo') + element = element.find_element(MobileBy.ID, 'foo') Returns: `appium.webdriver.webelement.WebElement` @@ -109,19 +110,15 @@ def find_element(self, by: str = By.ID, value: Union[str, Dict] = None) -> T: return self._execute(RemoteCommand.FIND_CHILD_ELEMENT, {"using": by, "value": value})['value'] - def find_elements(self, by: str = By.ID, value: Union[str, Dict] = None) -> List[T]: - """Find elements given a By strategy and locator - - Override for Appium - - Prefer the find_elements_by_* methods when possible. + def find_elements(self, by: str = MobileBy.ID, value: Union[str, Dict] = None) -> List[T]: + """Find elements given a MobileBy strategy and locator Args: by: The strategy value: The locator Usage: - element = element.find_elements(By.CLASS_NAME, 'foo') + element = element.find_elements(MobileBy.CLASS_NAME, 'foo') Returns: :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`