Add 'find_element(s)' to public API (robotframework#965)

* Add 'find_element(s)' to public API * Cleanup internal find_element(s) API Make (table_)element_finder private. We cannot promise that we keep these objects stable in the future. Better not to have them in the public API either. Related to robotframework#882.

Author: pekkaklarck

src/SeleniumLibrary/__init__.py

@@ -344,8 +344,8 @@ def __init__(self, timeout=5.0, implicit_wait=0.0,
  self._browsers = BrowserCache()
  DynamicCore.__init__(self, libraries)
  self.ROBOT_LIBRARY_LISTENER = LibraryListener()
- self.element_finder = ElementFinder(self)
- self.table_element_finder = TableElementFinder(self)
+ self._element_finder = ElementFinder(self)
+ self._table_element_finder = TableElementFinder(self)
 
  _speed_in_secs = Deprecated('_speed_in_secs', 'speed')
  _timeout_in_secs = Deprecated('_timeout_in_secs', 'timeout')
@@ -389,6 +389,31 @@ def browser(self):
  raise RuntimeError('No browser is open')
  return self._browsers.current
 
+ 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.
+
+ :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``.
+ :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``.
+
+ 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.
+ """
+ return self._element_finder.find(locator, first_only=False,
+ required=False, parent=parent)
+
  @property
  def _cache(self):
  warnings.warn('"SeleniumLibrary._cache" is deprecated, '

src/SeleniumLibrary/base/context.py

@@ -37,33 +37,29 @@ def browsers(self):
 
  @property
  def element_finder(self):
- return self.ctx.element_finder
+ return self.ctx._element_finder
 
  @property
  def table_element_finder(self):
- return self.ctx.table_element_finder
+ return self.ctx._table_element_finder
 
- def find_element(self, locator, tag=None, first_only=True, required=True,
- parent=None):
+ def find_element(self, locator, tag=None, required=True, parent=None):
  """Find element matching `locator`.
 
  :param locator: Locator to use when searching the element.
  See library documentation for the supported locator syntax.
  :param tag: Limit searching only to these elements.
- :param first_only: Return only first matching element if true,
- a list of elements otherwise.
  :param required: Raise `ElementNotFound` if element not found when
  true, return `None` otherwise.
- :param parent: Possible parent `WebElememt` element to search
- elements from. By default search starts from `WebDriver`.
+ :param parent: Optional parent `WebElememt` to search child elements
+ from. By default search starts from the root using `WebDriver`.
  :return: Found `WebElement` or `None` if element not found and
  `required` is false.
  :rtype: selenium.webdriver.remote.webelement.WebElement
  :raises SeleniumLibrary.errors.ElementNotFound: If element not found
  and `required` is true.
  """
- return self.element_finder.find(locator, tag, first_only,
- required, parent)
+ return self.element_finder.find(locator, tag, True, required, parent)
 
  def find_elements(self, locator, tag=None, parent=None):
  """Find all elements matching `locator`.
@@ -72,7 +68,7 @@ def find_elements(self, locator, tag=None, parent=None):
  is found, the list is empty. Otherwise semantics are exactly same
  as with :meth:`find_element`.
  """
- return self.find_element(locator, tag, False, False, parent)
+ return self.element_finder.find(locator, tag, False, False, parent)
 
  def is_text_present(self, text):
  locator = "xpath://*[contains(., %s)]" % escape_xpath_value(text)

test/acceptance/public_api.robot

@@ -0,0 +1,27 @@
+*** Settings ***
+Resource resource.robot
+Library CustomSeleniumKeywords
+Suite Setup Run Keywords
+... Set Library Search Order CustomSeleniumKeywords AND
+... Open Browser To Start Page
+Suite Teardown Close Browser
+
+*** Test Cases ***
+Find Element
+ ${first} = Use Find Element first
+ Should Be Equal ${first.text} This is the haystack and somewhere on this page is a needle.
+ ${em} = Use Find Element css:em ${first}
+ Should Be Equal ${em.text} needle
+ Run Keyword And Expect Error
+ ... Element with locator 'nonex' not found.
+ ... Use Find Element nonex
+
+Find Elements
+ ${paras} = Use Find Elements //p
+ Should Be Equal ${paras[0].text} This is the haystack and somewhere on this page is a needle.
+ Length Should Be ${paras} 2
+ ${ems} = Use Find Elements tag:em ${paras[0]}
+ Should Be Equal ${ems[0].text} needle
+ Length Should Be ${ems} 1
+ ${nonex} = Use Find Elements nonex
+ Length Should Be ${nonex} 0

test/resources/html/index.html

@@ -3,7 +3,7 @@
 <title>(root)/index.html</title>
 </head>
 <body>
-<p>This is the haystack and somewhere on this page is a <em>needle</em>.</p>
+<p id="first">This is the haystack and somewhere on this page is a <em>needle</em>.</p>
 <!-- this is a comment -->
 <p>This is more text</p>
 <span id="some_id">This text is inside an identified element</span>

test/resources/testlibs/CustomSeleniumKeywords.py

@@ -21,3 +21,11 @@ def custom_selenium_keyword(self):
  @keyword
  def custom_selenium_keyword_inner(self):
  raise AssertionError
+
+ @keyword
+ def use_find_element(self, locator, parent=None):
+ return self.find_element(locator, parent)
+
+ @keyword
+ def use_find_elements(self, locator, parent=None):
+ return self.find_elements(locator, parent)

test/unit/api/test_public_api_objects.py

@@ -9,7 +9,7 @@ class ElementFinderTest(unittest.TestCase):
 
  def setUp(self):
  self.ctx = mock()
- self.ctx.element_finder = mock()
+ self.ctx._element_finder = mock()
  self.finder = TableElementFinder(self.ctx)
 
  def tearDown(self):
@@ -48,8 +48,8 @@ def test_by_search_in_locators(self):
  element1.text = 'not here'
  element2.text = 'content'
  table_elements = [element1, element2]
- when(self.ctx.element_finder).find(
+ when(self.ctx._element_finder).find(
  'css=table', None, True, True, None).thenReturn(table)
- when(self.ctx.element_finder).find(
+ when(self.ctx._element_finder).find(
  xpath[0], None, False, False, table).thenReturn(table_elements)
  self.finder._search_in_locators('css=table', xpath, 'content')