Allow keywords to use Web Elements in addition to Locator.

src/Selenium2Library/__init__.py

@@ -33,13 +33,21 @@ class Selenium2Library(
     imported into your Robot test suite (see `importing` section), and the
     `Open Browser` keyword must be used to open a browser to the desired location.
 
-    = Locating elements =
+    **--- Note important change starting with Version 1.7.0 release ---**
+    = Locating or specifying elements =
 
     All keywords in Selenium2Library that need to find an element on the page
-    take an argument, `locator`. By default, when a locator value is provided,
-    it is matched against the key attributes of the particular element type.
-    For example, `id` and `name` are key attributes to all elements, and
-    locating elements is easy using just the `id` as a `locator`. For example::
+    take an argument, either a `locator` or now a `webelement`. `locator`
+    is a string that describes how to locate an element using a syntax
+    specifying different location strategies. `webelement` is a variable that
+    holds a WebElement instance, which is a representation of the element.
+
+    Using 'locator'
+    ---------------
+    By default, when a locator value is provided, it is matched against the
+    key attributes of the particular element type. For example, `id` and
+    `name` are key attributes to all elements, and locating elements is easy
+    using just the `id` as a `locator`. For example::
 
     Click Element  my_element
 
@@ -68,6 +76,17 @@ class Selenium2Library(
     This can be fixed by changing the locator to:
     | Click Link    default=page?a=b
 
+    Using 'webelement'
+    ------------------
+    Starting with version 1.7 of the Selenium2Library, one can pass an argument
+    that contains a WebElement instead of a string locator. To get a WebElement,
+    use the new `Get WebElements` keyword.  For example:
+
+    | ${elem} =      | Get WebElements | id=my_element |
+    | Click Element  | ${elem} |                       |
+
+    Locating Tables, Table Rows, Columns, etc.
+    ------------------------------------------
     Table related keywords, such as `Table Should Contain`, work differently.
     By default, when a table locator value is provided, it will search for
     a table with the specified `id` attribute. For example:

src/Selenium2Library/keywords/_element.py

@@ -1,15 +1,33 @@
 from selenium.webdriver.common.keys import Keys
 from selenium.webdriver.common.action_chains import ActionChains
+from selenium.webdriver.remote.webelement import WebElement
 from Selenium2Library import utils
 from Selenium2Library.locators import ElementFinder
 from Selenium2Library.locators import CustomLocator
 from keywordgroup import KeywordGroup
 
+try:
+    basestring  # attempt to evaluate basestring
+    def isstr(s):
+        return isinstance(s, basestring)
+except NameError:
+    def isstr(s):
+        return isinstance(s, str)
+
 class _ElementKeywords(KeywordGroup):
 
     def __init__(self):
         self._element_finder = ElementFinder()
 
+    # Public, get element(s)
+
+    def get_webelements(self, locator):
+        """Returns list of WebElement objects matching locator.
+
+        See `introduction` for details about locating elements.
+        """
+        return self._element_find(locator, False, True)
+
     # Public, element lookups
 
     def current_frame_contains(self, text, loglevel='INFO'):
@@ -638,12 +656,17 @@ def remove_location_strategy(self, strategy_name):
 
     def _element_find(self, locator, first_only, required, tag=None):
         browser = self._current_browser()
-        elements = self._element_finder.find(browser, locator, tag)
-        if required and len(elements) == 0:
-            raise ValueError("Element locator '" + locator + "' did not match any elements.")
-        if first_only:
-            if len(elements) == 0: return None
-            return elements[0]
+        if isstr(locator):
+            elements = self._element_finder.find(browser, locator, tag)
+            if required and len(elements) == 0:
+                raise ValueError("Element locator '" + locator + "' did not match any elements.")
+            if first_only:
+                if len(elements) == 0: return None
+                return elements[0]
+        elif isinstance(locator, WebElement):
+            elements = locator
+        # do some other stuff here like deal with list of webelements
+        # ... or raise locator/element specific error if required
         return elements
 
     def _frame_contains(self, locator, text):

test/acceptance/keywords/elements.txt

@@ -1,8 +1,25 @@
 *** Settings ***
-Suite Setup     Go To Page "links.html"
+Test Setup      Go To Page "links.html"
 Resource        ../resource.txt
 
 *** Test Cases ***
+Get Elements
+    @{links}=  Get WebElements  //div[@id="div_id"]/a
+    Length Should Be  ${links}  11
+
+More Get Elements
+    [Setup]  Go To Page "forms/prefilled_email_form.html"
+    @{checkboxes}=  Get WebElements  //input[@type="checkbox"]
+    Length Should Be  ${checkboxes}  2
+    :For   ${checkbox}  in  @{checkboxes}
+    \  Unselect Checkbox  ${checkbox}
+    :For   ${checkbox}  in  @{checkboxes}
+    \  Checkbox Should Not Be Selected  ${checkbox}
+    :For   ${checkbox}  in  @{checkboxes}
+    \  Select Checkbox  ${checkbox}
+    :For   ${checkbox}  in  @{checkboxes}
+    \  Checkbox Should Be Selected  ${checkbox}
+
 Assign Id To Element
     [Documentation]  Tests also Reload Page keyword.
     Page Should Not Contain Element  my id