diff --git a/src/Selenium2Library/__init__.py b/src/Selenium2Library/__init__.py index fffdf9c51..fad8a88c5 100644 --- a/src/Selenium2Library/__init__.py +++ b/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: diff --git a/src/Selenium2Library/keywords/_element.py b/src/Selenium2Library/keywords/_element.py index 2137aacb6..3117e7d1d 100644 --- a/src/Selenium2Library/keywords/_element.py +++ b/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): diff --git a/test/acceptance/keywords/elements.txt b/test/acceptance/keywords/elements.txt index f6b4d2029..d488b6a90 100644 --- a/test/acceptance/keywords/elements.txt +++ b/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