diff --git a/src/SeleniumLibrary/__init__.py b/src/SeleniumLibrary/__init__.py index 17321ec1a..8884818e6 100644 --- a/src/SeleniumLibrary/__init__.py +++ b/src/SeleniumLibrary/__init__.py @@ -363,6 +363,15 @@ def run_keyword(self, name, args, kwargs): raise def register_driver(self, driver, alias): + """Add's a `driver` to the library WebDriverCache. + + :param driver: Instance of the Selenium `WebDriver`. + :type driver: selenium.webdriver.remote.webdriver.WebDriver + :param alias: Alias given for this `WebDriver` instance. + :type alias: str + :return: The index of the `WebDriver` instance. + :rtype: int + """ return self._drivers.register(driver, alias) def failure_occurred(self): @@ -402,26 +411,31 @@ def browser(self): return self.driver def find_element(self, locator, parent=None): - """Find element matching ``locator``. - - This method and :meth:`find_elements` form the recommended - public API for external tools to get elements via SeleniumLibrary. + """Find element matching `locator`. :param locator: Locator to use when searching the element. See library documentation for the supported locator syntax. - :param parent: Optional parent ``WebElememt`` to search child elements - from. By default search starts from the root using ``WebDriver``. + :type locator: str or selenium.webdriver.remote.webelement.WebElement + :param parent: Optional parent `WebElememt` to search child elements + from. By default search starts from the root using `WebDriver`. + :type parent: selenium.webdriver.remote.webelement.WebElement + :return: Found `WebElement`. :rtype: selenium.webdriver.remote.webelement.WebElement :raises SeleniumLibrary.errors.ElementNotFound: If element not found. """ return self._element_finder.find(locator, parent=parent) def find_elements(self, locator, parent=None): - """Find all elements matching ``locator``. + """Find all elements matching `locator`. - Returns a list of ``WebElement`` objects. If no matching elements - are found, the list is empty. Otherwise semantics are exactly same - as with the :meth:`find_element` method. + :param locator: Locator to use when searching the element. + See library documentation for the supported locator syntax. + :type locator: str or selenium.webdriver.remote.webelement.WebElement + :param parent: Optional parent `WebElememt` to search child elements + from. By default search starts from the root using `WebDriver`. + :type parent: selenium.webdriver.remote.webelement.WebElement + :return: list of found `WebElement` or e,mpty if elements are not found. + :rtype: list[selenium.webdriver.remote.webelement.WebElement] """ return self._element_finder.find(locator, first_only=False, required=False, parent=parent) @@ -430,7 +444,7 @@ def find_elements(self, locator, parent=None): def _cache(self): warnings.warn('"SeleniumLibrary._cache" is deprecated, ' 'use public API instead.', DeprecationWarning) - return self._browsers + return self._drivers def _current_browser(self): warnings.warn('"SeleniumLibrary._current_browser" is deprecated, ' diff --git a/src/SeleniumLibrary/base/context.py b/src/SeleniumLibrary/base/context.py index 266959462..e210d6606 100644 --- a/src/SeleniumLibrary/base/context.py +++ b/src/SeleniumLibrary/base/context.py @@ -22,8 +22,8 @@ class ContextAware(object): def __init__(self, ctx): """Base class exposing attributes from the common context. - :param SeleniumLibrary.SeleniumLibrary ctx: - The library itself as a context object. + :param ctx: The library itself as a context object. + :type ctx: SeleniumLibrary.SeleniumLibrary """ self.ctx = ctx @@ -44,11 +44,15 @@ def find_element(self, locator, tag=None, required=True, parent=None): :param locator: Locator to use when searching the element. See library documentation for the supported locator syntax. + :type locator: str or selenium.webdriver.remote.webelement.WebElement :param tag: Limit searching only to these elements. + :type tag: str :param required: Raise `ElementNotFound` if element not found when true, return `None` otherwise. + :type required: True or False :param parent: Optional parent `WebElememt` to search child elements from. By default search starts from the root using `WebDriver`. + :type parent: selenium.webdriver.remote.webelement.WebElement :return: Found `WebElement` or `None` if element not found and `required` is false. :rtype: selenium.webdriver.remote.webelement.WebElement @@ -60,9 +64,16 @@ def find_element(self, locator, tag=None, required=True, parent=None): def find_elements(self, locator, tag=None, parent=None): """Find all elements matching `locator`. - Always returns a list of `WebElement` objects. If no matching element - is found, the list is empty. Otherwise semantics are exactly same - as with :meth:`find_element`. + :param locator: Locator to use when searching the element. + See library documentation for the supported locator syntax. + :type locator: str or selenium.webdriver.remote.webelement.WebElement + :param tag: Limit searching only to these elements. + :type tag: str + :param parent: Optional parent `WebElememt` to search child elements + from. By default search starts from the root using `WebDriver`. + :type parent: selenium.webdriver.remote.webelement.WebElement + :return: list of found `WebElement` or empty if elements are not found. + :rtype: list[selenium.webdriver.remote.webelement.WebElement] """ return self.element_finder.find(locator, tag, False, False, parent)