def __init__(self, timeout=5.0, implicit_wait=0.0, run_on_failure='Capture Page Screenshot', screenshot_root_directory=None): """SeleniumLibrary can be imported with optional arguments. `timeout` is the default timeout used to wait for all waiting actions. It can be later set with `Set Selenium Timeout`. 'implicit_wait' is the implicit timeout that Selenium waits when looking for elements. It can be later set with `Set Selenium Implicit Wait`. See `WebDriver: Advanced Usage`__ section of the SeleniumHQ documentation for more information about WebDriver's implicit wait functionality. __ http://seleniumhq.org/docs/04_webdriver_advanced.html#explicit-and-implicit-waits `run_on_failure` specifies the name of a keyword (from any available libraries) to execute when a SeleniumLibrary keyword fails. By default `Capture Page Screenshot` will be used to take a screenshot of the current page. Using the value "Nothing" will disable this feature altogether. See `Register Keyword To Run On Failure` keyword for more information about this functionality. `screenshot_root_directory` specifies the default root directory that screenshots should be stored in. If not provided the default directory will be where robotframework places its logfile. Examples: | Library `|` SeleniumLibrary `|` 15 | # Sets default timeout to 15 seconds | | Library `|` SeleniumLibrary `|` 0 `|` 5 | # Sets default timeout to 0 seconds and default implicit_wait to 5 seconds | | Library `|` SeleniumLibrary `|` 5 `|` run_on_failure=Log Source | # Sets default timeout to 5 seconds and runs `Log Source` on failure | | Library `|` SeleniumLibrary `|` implicit_wait=5 `|` run_on_failure=Log Source | # Sets default implicit_wait to 5 seconds and runs `Log Source` on failure | | Library `|` SeleniumLibrary `|` timeout=10 `|` run_on_failure=Nothing | # Sets default timeout to 10 seconds and does nothing on failure | """ self.timeout = timestr_to_secs(timeout) self.implicit_wait = timestr_to_secs(implicit_wait) self.speed = 0.0 self.run_on_failure_keyword \ = RunOnFailureKeywords.resolve_keyword(run_on_failure) self._running_on_failure_keyword = False self.screenshot_root_directory = screenshot_root_directory libraries = [ AlertKeywords(self), BrowserManagementKeywords(self), RunOnFailureKeywords(self), ElementKeywords(self), TableElementKeywords(self), FormElementKeywords(self), SelectElementKeywords(self), JavaScriptKeywords(self), CookieKeywords(self), ScreenshotKeywords(self), WaitingKeywords(self) ] self._browsers = BrowserCache() DynamicCore.__init__(self, libraries) self.ROBOT_LIBRARY_LISTENER = LibraryListener() self.element_finder = ElementFinder(self) self._table_element_finder = TableElementFinder(self)
def test_close_only_called_once(self): cache = BrowserCache() browser1 = mock() browser2 = mock() browser3 = mock() cache.register(browser1) cache.register(browser2) cache.register(browser3) cache.close() verify(browser3, times=1).quit() cache.close_all() verify(browser1, times=1).quit() verify(browser2, times=1).quit() verify(browser3, times=1).quit()
def test_browsers_property(self): cache = BrowserCache() browser1 = mock() browser2 = mock() browser3 = mock() index1 = cache.register(browser1) index2 = cache.register(browser2) index3 = cache.register(browser3) self.assertEqual(len(cache.browsers), 3) self.assertEqual(cache.browsers[0], browser1) self.assertEqual(cache.browsers[1], browser2) self.assertEqual(cache.browsers[2], browser3) self.assertEqual(index1, 1) self.assertEqual(index2, 2) self.assertEqual(index3, 3)
def __init__(self, timeout=5.0, implicit_wait=0.0, run_on_failure='Capture Page Screenshot', screenshot_root_directory=None): """SeleniumLibrary can be imported with several optional arguments. - ``timeout``: Default value for `timeouts` used with ``Wait ...`` keywords. - ``implicit_wait``: Default value for `implicit wait` used when locating elements. - ``run_on_failure``: Default action for the `run-on-failure functionality`. - ``screenshot_root_directory``: Location where possible screenshots are created. If not given, the directory where the log file is written is used. """ self.timeout = timestr_to_secs(timeout) self.implicit_wait = timestr_to_secs(implicit_wait) self.speed = 0.0 self.run_on_failure_keyword \ = RunOnFailureKeywords.resolve_keyword(run_on_failure) self._running_on_failure_keyword = False self.screenshot_root_directory = screenshot_root_directory libraries = [ AlertKeywords(self), BrowserManagementKeywords(self), CookieKeywords(self), ElementKeywords(self), FormElementKeywords(self), FrameKeywords(self), JavaScriptKeywords(self), RunOnFailureKeywords(self), ScreenshotKeywords(self), SelectElementKeywords(self), TableElementKeywords(self), WaitingKeywords(self), WindowKeywords(self) ] self._browsers = BrowserCache() DynamicCore.__init__(self, libraries) self.ROBOT_LIBRARY_LISTENER = LibraryListener() self._element_finder = ElementFinder(self) self._table_element_finder = TableElementFinder(self)
def test_get_open_browsers(self): cache = BrowserCache() browser1 = mock() browser2 = mock() browser3 = mock() cache.register(browser1) cache.register(browser2) cache.register(browser3) browsers = cache.get_open_browsers() self.assertEqual(len(browsers), 3) self.assertEqual(browsers[0], browser1) self.assertEqual(browsers[1], browser2) self.assertEqual(browsers[2], browser3) cache.close() browsers = cache.get_open_browsers() self.assertEqual(len(browsers), 2) self.assertEqual(browsers[0], browser1) self.assertEqual(browsers[1], browser2)
def test_close(self): cache = BrowserCache() browser = mock() cache.register(browser) verify(browser, times=0).quit() # sanity check cache.close() verify(browser, times=1).quit()
def __init__(self, timeout=5.0, implicit_wait=0.0, run_on_failure='Capture Page Screenshot', screenshot_root_directory=None): """SeleniumLibrary can be imported with several optional arguments. - ``timeout``: Default value for `timeouts` used with ``Wait ...`` keywords. - ``implicit_wait``: Default value for `implicit wait` used when locating elements. - ``run_on_failure``: Default action for the `run-on-failure functionality`. - ``screenshot_root_directory``: Location where possible screenshots are created. If not given, the directory where the log file is written is used. """ self.timeout = timestr_to_secs(timeout) self.implicit_wait = timestr_to_secs(implicit_wait) self.speed = 0.0 self.run_on_failure_keyword \ = RunOnFailureKeywords.resolve_keyword(run_on_failure) self._running_on_failure_keyword = False self.screenshot_root_directory = screenshot_root_directory libraries = [ AlertKeywords(self), BrowserManagementKeywords(self), RunOnFailureKeywords(self), ElementKeywords(self), TableElementKeywords(self), FormElementKeywords(self), SelectElementKeywords(self), JavaScriptKeywords(self), CookieKeywords(self), ScreenshotKeywords(self), WaitingKeywords(self) ] self._browsers = BrowserCache() DynamicCore.__init__(self, libraries) self.ROBOT_LIBRARY_LISTENER = LibraryListener() self.element_finder = ElementFinder(self) self.table_element_finder = TableElementFinder(self)
class SeleniumLibrary(DynamicCore): """SeleniumLibrary is a web testing library for Robot Framework. This document explains how to use keywords provided by SeleniumLibrary. For information about installation, support, and more, please visit the [https://github.com/robotframework/SeleniumLibrary|project pages]. For more information about Robot Framework, see http://robotframework.org. SeleniumLibrary uses the Selenium WebDriver modules internally to control a web browser. See http://seleniumhq.org for more information about Selenium in general. == Table of contents == - `Locating elements` - `Timeouts, waits and delays` - `Run-on-failure functionality` - `Boolean arguments` - `Importing` - `Shortcuts` - `Keywords` = Locating elements = All keywords in SeleniumLibrary that need to interact with an element on a web page take an argument typically named ``locator`` that specifies how to find the element. Most often the locator is given as a string using the locator syntax described below, but `using WebElements` is possible too. == Locator syntax == SeleniumLibrary supports finding elements based on different strategies such as the element id, XPath expressions, or CSS selectors. The strategy can either be explicitly specified with a prefix or the strategy can be implicit. === Default locator strategy === By default locators are considered to use the keyword specific default locator strategy. All keywords support finding elements based on ``id`` and ``name`` attributes, but some keywords support additional _key attributes_ that make sense in their context. For example, `Click Link` supports the link text and the ``href`` attribute in addition to the normal ``id`` and ``name``. Examples: | `Click Element` | example | # Match based on ``id`` or ``name``. | | `Click Link` | example | # Match also based on link text and ``href``. | | `Click Button` | example | # Match based on ``id``, ``name`` or ``value``. | If a locator accidentally starts with a prefix recognized as `explicit locator strategy` or `implicit XPath strategy`, it is possible to use the explicit ``default`` prefix to enable the default strategy. Examples: | `Click Element` | name:foo | # Find element with name ``foo``. | | `Click Element` | default:name:foo | # Use default strategy with value ``name:foo``. | | `Click Element` | //foo | # Find element using XPath ``//foo``. | | `Click Element` | default: //foo | # Use default strategy with value ``//foo``. | === Explicit locator strategy === The explicit locator strategy is specified with a prefix using either syntax ``strategy:value`` or ``strategy=value``. The former syntax is preferred, because the latter is identical to Robot Framework's [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#named-argument-syntax| named argument syntax] and that can cause problems. Spaces around the separator are ignored, so ``id:foo``, ``id: foo`` and ``id : foo`` are all equivalent. Locator strategies that are supported by default are listed in the table below. In addition to them, it is possible to register `custom locators`. | = Strategy = | = Match based on = | = Example = | | id | Element ``id``. | ``id:example`` | | name | ``name`` attribute. | ``name:example`` | | identifier | Either ``id`` or ``name``. | ``identifier:example`` | | class | Element ``class``. | ``class:example`` | | tag | Tag name. | ``tag:div`` | | xpath | XPath expression. | ``xpath://div[@id="example"]`` | | css | CSS selector. | ``css:div#example`` | | dom | DOM expression. | ``dom:document.images[5]`` | | link | Exact text a link has. | ``link:The example`` | | partial link | Partial link text. | ``partial link:he ex`` | | sizzle | Sizzle selector provided by jQuery. | ``sizzle:div.example`` | | jquery | Same as the above. | ``jquery:div.example`` | | default | Keyword specific default behavior. | ``default:example`` | See the `Default locator strategy` section below for more information about how the default strategy works. Using the explicit ``default`` prefix is only necessary if the locator value itself accidentally matches some of the explicit strategies. Different locator strategies have different pros and cons. Using ids, either explicitly like ``id:foo`` or by using the `default locator strategy` simply like ``foo``, is recommended when possible, because the syntax is simple and locating elements by an id is fast for browsers. If an element does not have an id or the id is not stable, other solutions need to be used. If an element has a unique tag name or class, using ``tag``, ``class`` or ``css`` strategy like ``tag:h1``, ``class:example`` or ``css:h1.example`` is often an easy solution. In more complex cases using XPath expressions is typically the best approach. They are very powerful but a downside is that they can also get complex. Examples: | `Click Element` | id:foo | # Element with id 'foo'. | | `Click Element` | css:div#foo h1 | # h1 element under div with id 'foo'. | | `Click Element` | xpath: //div[@id="foo"]//h1 | # Same as the above using XPath, not CSS. | | `Click Element` | xpath: //*[contains(text(), "example")] | # Element containing text 'example'. | *NOTE:* - The ``strategy:value`` syntax is only supported by SeleniumLibrary 3.0 and newer. - Using the ``sizzle`` strategy or its alias ``jquery`` requires that the system under test contains the jQuery library. - Prior to SeleniumLibrary 3.0, table related keywords only supported ``xpath``, ``css`` and ``sizzle/jquery`` strategies. === Implicit XPath strategy === If the locator starts with ``//`` or ``(//``, the locator is considered to be an XPath expression. In other words, using ``//div`` is equivalent to using explicit ``xpath://div``. Examples: | `Click Element` | //div[@id="foo"]//h1 | | `Click Element` | (//div)[2] | The support for the ``(//`` prefix is new in SeleniumLibrary 3.0. == Using WebElements == In addition to specifying a locator as a string, it is possible to use Selenium's WebElement objects. This requires first getting a WebElement, for example, by using the `Get WebElement` keyword. | ${elem} = | `Get WebElement` | id=example | | `Click Element` | ${elem} | | == Custom locators == If more complex lookups are required than what is provided through the default locators, custom lookup strategies can be created. Using custom locators is a two part process. First, create a keyword that returns a WebElement that should be acted on: | Custom Locator Strategy | [Arguments] | ${browser} | ${strategy} | ${tag} | ${constraints} | | | ${element}= | Execute Javascript | return window.document.getElementById('${criteria}'); | | | [Return] | ${element} | This keyword is a reimplementation of the basic functionality of the ``id`` locator where ``${browser}`` is a reference to a WebDriver instance and ``${strategy}`` is name of the locator strategy. To use this locator it must first be registered by using the `Add Location Strategy` keyword: | `Add Location Strategy` | custom | Custom Locator Strategy | The first argument of `Add Location Strategy` specifies the name of the strategy and it must be unique. After registering the strategy, the usage is the same as with other locators: | `Click Element` | custom:example | See the `Add Location Strategy` keyword for more details. = Timeouts, waits and delays = This section discusses different ways how to wait for elements to appear on web pages and to slow down execution speed otherwise. It also explains the `time format` that can be used when setting various timeouts, waits and delays. == Timeout == SeleniumLibrary contains various keywords that have an optional ``timeout`` argument that specifies how long these keywords should wait for certain events or actions. These keywords include, for example, ``Wait ...`` keywords and keywords related to alerts. The default timeout these keywords use can be set globally either by using the `Set Selenium Timeout` keyword or with the ``timeout`` argument when `importing` the library. See `time format` below for supported timeout syntax. == Implicit wait == Implicit wait specifies the maximum time how long Selenium waits when searching for elements. It can be set by using the `Set Selenium Implicit Wait` keyword or with the ``implicit_wait`` argument when `importing` the library. See [http://seleniumhq.org/docs/04_webdriver_advanced.html| Selenium documentation] for more information about this functionality. See `time format` below for supported syntax. == Selenium speed == Selenium execution speed can be slowed down globally by using `Set Selenium speed` keyword. This functionality is designed to be used for demonstrating or debugging purposes. Using it to make sure that elements appear on a page is not a good idea, and the above explained timeouts and waits should be used instead. See `time format` below for supported syntax. == Time format == All timeouts and waits can be given as numbers considered seconds (e.g. ``0.5`` or ``42``) or in Robot Framework's time syntax (e.g. ``1.5 seconds`` or ``1 min 30 s``). For more information about the time syntax see the [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format|Robot Framework User Guide]. = Run-on-failure functionality = SeleniumLibrary has a handy feature that it can automatically execute a keyword if any of its own keywords fails. By default it uses the `Capture Page Screenshot` keyword, but this can be changed either by using the `Register Keyword To Run On Failure` keyword or with the ``run_on_failure`` argument when `importing` the library. It is possible to use any keyword from any imported library or resource file. The run-on-failure functionality can be disabled by using a special value ``NOTHING`` or anything considered false (see `Boolean arguments`) such as ``NONE``. = Boolean arguments = Some keywords accept arguments that are handled as Boolean values true or false. If such an argument is given as a string, it is considered false if it is either empty or case-insensitively equal to ``false``, ``no`` or ``none``. Other strings are considered true regardless their value, and other argument types are tested using same [https://docs.python.org/2/library/stdtypes.html#truth-value-testing|rules as in Python]. True examples: | `Set Screenshot Directory` | ${RESULTS} | persist=True | # Strings are generally true. | | `Set Screenshot Directory` | ${RESULTS} | persist=yes | # Same as the above. | | `Set Screenshot Directory` | ${RESULTS} | persist=${TRUE} | # Python True is true. | | `Set Screenshot Directory` | ${RESULTS} | persist=${42} | # Numbers other than 0 are true. | False examples: | `Set Screenshot Directory` | ${RESULTS} | persist=False | # String false is false. | | `Set Screenshot Directory` | ${RESULTS} | persist=no | # Also string no is false. | | `Set Screenshot Directory` | ${RESULTS} | persist=NONE | # String NONE is false. | | `Set Screenshot Directory` | ${RESULTS} | persist=${EMPTY} | # Empty string is false. | | `Set Screenshot Directory` | ${RESULTS} | persist=${FALSE} | # Python False is false. | | `Set Screenshot Directory` | ${RESULTS} | persist=${NONE} | # Python None is false. | Note that prior to SeleniumLibrary 3.0, all non-empty strings, including ``false``, ``no`` and ``none``, were considered true. """ ROBOT_LIBRARY_SCOPE = 'GLOBAL' ROBOT_LIBRARY_VERSION = __version__ def __init__(self, timeout=5.0, implicit_wait=0.0, run_on_failure='Capture Page Screenshot', screenshot_root_directory=None): """SeleniumLibrary can be imported with several optional arguments. - ``timeout``: Default value for `timeouts` used with ``Wait ...`` keywords. - ``implicit_wait``: Default value for `implicit wait` used when locating elements. - ``run_on_failure``: Default action for the `run-on-failure functionality`. - ``screenshot_root_directory``: Location where possible screenshots are created. If not given, the directory where the log file is written is used. """ self.timeout = timestr_to_secs(timeout) self.implicit_wait = timestr_to_secs(implicit_wait) self.speed = 0.0 self.run_on_failure_keyword \ = RunOnFailureKeywords.resolve_keyword(run_on_failure) self._running_on_failure_keyword = False self.screenshot_root_directory = screenshot_root_directory libraries = [ AlertKeywords(self), BrowserManagementKeywords(self), CookieKeywords(self), ElementKeywords(self), FormElementKeywords(self), FrameKeywords(self), JavaScriptKeywords(self), RunOnFailureKeywords(self), ScreenshotKeywords(self), SelectElementKeywords(self), TableElementKeywords(self), WaitingKeywords(self) ] self._browsers = BrowserCache() DynamicCore.__init__(self, libraries) self.ROBOT_LIBRARY_LISTENER = LibraryListener() 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') _implicit_wait_in_secs = Deprecated('_implicit_wait_in_secs', 'implicit_wait') _run_on_failure_keyword = Deprecated('_run_on_failure_keyword', 'run_on_failure_keyword') def run_keyword(self, name, args, kwargs): try: return DynamicCore.run_keyword(self, name, args, kwargs) except Exception: self.failure_occurred() raise def register_browser(self, browser, alias): return self._browsers.register(browser, alias) def failure_occurred(self): """Method that is executed when a SeleniumLibrary keyword fails. By default executes the registered run-on-failure keyword. Libraries extending SeleniumLibrary can overwrite this hook method if they want to provide custom functionality instead. """ if self._running_on_failure_keyword or not self.run_on_failure_keyword: return try: self._running_on_failure_keyword = True BuiltIn().run_keyword(self.run_on_failure_keyword) except Exception as err: logger.warn("Keyword '%s' could not be run on failure: %s" % (self.run_on_failure_keyword, err)) finally: self._running_on_failure_keyword = False @property def browser(self): """Current active browser""" if not self._browsers.current: raise RuntimeError('No browser is open') return self._browsers.current @property def _cache(self): warnings.warn( '"SeleniumLibrary._cache" is deprecated, ' 'use public API instead.', DeprecationWarning) return self._browsers def _current_browser(self): warnings.warn( '"SeleniumLibrary._current_browser" is deprecated, ' 'use "SeleniumLibrary.browser" instead.', DeprecationWarning) return self.browser def _run_on_failure(self): warnings.warn( '"SeleniumLibrary._run_on_failure" is deprecated, ' 'use "SeleniumLibrary.failure_occurred" instead.', DeprecationWarning) self.failure_occurred()
def test_no_current_message(self): cache = BrowserCache() try: self.assertRaises(RuntimeError, cache.current.anyMember()) except RuntimeError as e: self.assertEqual(str(e), "No current browser")
class SeleniumLibrary(DynamicCore): """SeleniumLibrary is a web testing library for Robot Framework. This document is about using SeleniumLibrary. For information about installation, support, and more please visit the [https://github.com/robotframework/SeleniumLibrary|project page]. SeleniumLibrary uses the Selenium 2 (WebDriver) libraries internally to control a web browser. See http://seleniumhq.org/docs/03_webdriver.html for more information on Selenium 2 and WebDriver. SeleniumLibrary runs tests in a real browser instance. It should work in most modern browsers and can be used with both Python and Jython interpreters. = Before running tests = Prior to running test cases using SeleniumLibrary, SeleniumLibrary must be 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. *--- Note important change starting with Version 1.7.0 release ---* = Locating or specifying elements = All keywords in SeleniumLibrary that need to find an element on the page 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 locators* --------------- The locator can be used in two ways. In explicit way, where the strategy of the locator is defined as prefix in the locator or in implicit way, where there strategy is determined from the locator. The implicit way supports two strategies: `xpath` and matching against `id` and `name` attributes. If locator starts with `//` or `(//` then `xpath` strategy will be used. Determining `(//` as xpath is supported from release 3.0.0 onwards. If locator does not start with `//` or `(//`, then it is matched against the `id` and `name` key attributes of elements. Example | Click Element my_element # id and name attribute matching | Click Element //div # xpath | Click Element (//div)[2] # xpath In the explicit way, it is possible to specify the approach SeleniumLibrary should take to find an element by specifying a lookup strategy with a locator prefix. Supported strategies are: | *Strategy* | *Example* | *Description* | | identifier | Click Element `|` identifier=my_element | Matches by @id or @name attribute | | id | Click Element `|` id=my_element | Matches by @id attribute | | name | Click Element `|` name=my_element | Matches by @name attribute | | xpath | Click Element `|` xpath=//div[@id='my_element'] | Matches with arbitrary XPath expression | | dom | Click Element `|` dom=document.images[56] | Matches with arbitrary DOM express | | link | Click Element `|` link=My Link | Matches anchor elements by their link text | | partial link | Click Element `|` partial link=y Lin | Matches anchor elements by their partial link text | | css | Click Element `|` css=div.my_class | Matches by CSS selector | | class | Click Element `|` class=my_class | Matches by class name selector | | jquery | Click Element `|` jquery=div.my_class | Matches by jQuery/sizzle selector | | sizzle | Click Element `|` sizzle=div.my_class | Matches by jQuery/sizzle selector | | tag | Click Element `|` tag=div | Matches by HTML tag name | | default* | Click Link `|` default=page?a=b | Matches key attributes with value after first '=' | * Explicitly specifying the default strategy is only necessary if locating elements by matching key attributes is desired and an attribute value contains a '='. The following would fail because it appears as if _page?a_ is the specified lookup strategy: | Click Link page?a=b This can be fixed by changing the locator to: | Click Link default=page?a=b Please note that jQuery is not provided by SeleniumLibrary and if there is need to use jQuery locators, the system under test must provide the jQuery library. *Using webelements* ------------------ Starting with version 1.7 of the SeleniumLibrary, 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 WebElement | 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: | Table Should Contain my_table text More complex table lookup strategies are also supported: | *Strategy* | *Example* | *Description* | | css | Table Should Contain `|` css=table.my_class `|` text | Matches by @id or @name attribute | | xpath | Table Should Contain `|` xpath=//table/[@name="my_table"] `|` text | Matches by @id or @name attribute | = Custom Locators = If more complex lookups are required than what is provided through the default locators, custom lookup strategies can be created. Using custom locators is a two part process. First, create a keyword that returns the WebElement that should be acted on. | Custom Locator Strategy | [Arguments] | ${browser} | ${criteria} | ${tag} | ${constraints} | | | ${retVal}= | Execute Javascript | return window.document.getElementById('${criteria}'); | | | [Return] | ${retVal} | This keyword is a reimplementation of the basic functionality of the `id` locator where `${browser}` is a reference to the WebDriver instance and `${criteria}` is the text of the locator (i.e. everything that comes after the = sign). To use this locator it must first be registered with `Add Location Strategy`. | Add Location Strategy custom Custom Locator Strategy The first argument of `Add Location Strategy` specifies the name of the lookup strategy (which must be unique). After registration of the lookup strategy, the usage is the same as other locators. See `Add Location Strategy` for more details. = Timeouts = There are several `Wait ...` keywords that take timeout as an argument. All of these timeout arguments are optional. The timeout used by all of them can be set globally using the `Set Selenium Timeout` keyword. The same timeout also applies to `Execute Async Javascript`. All timeouts can be given as numbers considered seconds (e.g. 0.5 or 42) or in Robot Framework's time syntax (e.g. '1.5 seconds' or '1 min 30 s'). For more information about the time syntax see the [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format|Robot Framework User Guide]. = Boolean arguments = Some keywords accept arguments that are handled as Boolean values true or false. If such an argument is given as a string, it is considered false if it is either empty or case-insensitively equal to ``false``, ``no`` or ``none``. Other strings are considered true regardless their value, and other argument types are tested using same [https://docs.python.org/2/library/stdtypes.html#truth-value-testing|rules as in Python]. True examples: | Set Screenshot Directory | ${OUTPUT_DIR}/screenshots | persist=True | # Strings are generally true. | | Set Screenshot Directory | ${OUTPUT_DIR}/screenshots | persist=yes | # Same as the above. | | Set Screenshot Directory | ${OUTPUT_DIR}/screenshots | persist=${TRUE} | # Python True is true. | | Set Screenshot Directory | ${OUTPUT_DIR}/screenshots | persist=${42} | # Numbers other than 0 are true. | False examples: | Set Screenshot Directory | ${OUTPUT_DIR}/screenshots | persist=False | # String false is false. | | Set Screenshot Directory | ${OUTPUT_DIR}/screenshots | persist=no | # Also string no is false. | | Set Screenshot Directory | ${OUTPUT_DIR}/screenshots | persist=NONE | # String NONE is false. | | Set Screenshot Directory | ${OUTPUT_DIR}/screenshots | persist=${EMPTY} | # Empty string is false. | | Set Screenshot Directory | ${OUTPUT_DIR}/screenshots | persist=${FALSE} | # Python False is false. | | Set Screenshot Directory | ${OUTPUT_DIR}/screenshots | persist=${NONE} | # Python None is false. | Note that prior to SeleniumLibrary 3.0, all non-empty strings, including ``false``, ``no`` and ``none``, were considered true. """ ROBOT_LIBRARY_SCOPE = 'GLOBAL' ROBOT_LIBRARY_VERSION = __version__ def __init__(self, timeout=5.0, implicit_wait=0.0, run_on_failure='Capture Page Screenshot', screenshot_root_directory=None): """SeleniumLibrary can be imported with optional arguments. `timeout` is the default timeout used to wait for all waiting actions. It can be later set with `Set Selenium Timeout`. 'implicit_wait' is the implicit timeout that Selenium waits when looking for elements. It can be later set with `Set Selenium Implicit Wait`. See `WebDriver: Advanced Usage`__ section of the SeleniumHQ documentation for more information about WebDriver's implicit wait functionality. __ http://seleniumhq.org/docs/04_webdriver_advanced.html#explicit-and-implicit-waits `run_on_failure` specifies the name of a keyword (from any available libraries) to execute when a SeleniumLibrary keyword fails. By default `Capture Page Screenshot` will be used to take a screenshot of the current page. Using the value "Nothing" will disable this feature altogether. See `Register Keyword To Run On Failure` keyword for more information about this functionality. `screenshot_root_directory` specifies the default root directory that screenshots should be stored in. If not provided the default directory will be where robotframework places its logfile. Examples: | Library `|` SeleniumLibrary `|` 15 | # Sets default timeout to 15 seconds | | Library `|` SeleniumLibrary `|` 0 `|` 5 | # Sets default timeout to 0 seconds and default implicit_wait to 5 seconds | | Library `|` SeleniumLibrary `|` 5 `|` run_on_failure=Log Source | # Sets default timeout to 5 seconds and runs `Log Source` on failure | | Library `|` SeleniumLibrary `|` implicit_wait=5 `|` run_on_failure=Log Source | # Sets default implicit_wait to 5 seconds and runs `Log Source` on failure | | Library `|` SeleniumLibrary `|` timeout=10 `|` run_on_failure=Nothing | # Sets default timeout to 10 seconds and does nothing on failure | """ self.timeout = timestr_to_secs(timeout) self.implicit_wait = timestr_to_secs(implicit_wait) self.speed = 0.0 self.run_on_failure_keyword \ = RunOnFailureKeywords.resolve_keyword(run_on_failure) self._running_on_failure_keyword = False self.screenshot_root_directory = screenshot_root_directory libraries = [ AlertKeywords(self), BrowserManagementKeywords(self), RunOnFailureKeywords(self), ElementKeywords(self), TableElementKeywords(self), FormElementKeywords(self), SelectElementKeywords(self), JavaScriptKeywords(self), CookieKeywords(self), ScreenshotKeywords(self), WaitingKeywords(self) ] self._browsers = BrowserCache() DynamicCore.__init__(self, libraries) self.ROBOT_LIBRARY_LISTENER = LibraryListener() 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') _implicit_wait_in_secs = Deprecated('_implicit_wait_in_secs', 'implicit_wait') _run_on_failure_keyword = Deprecated('_run_on_failure_keyword', 'run_on_failure_keyword') def run_keyword(self, name, args, kwargs): try: return DynamicCore.run_keyword(self, name, args, kwargs) except Exception: self.failure_occurred() raise def register_browser(self, browser, alias): return self._browsers.register(browser, alias) def failure_occurred(self): """Method that is executed when a SeleniumLibrary keyword fails. By default executes the registered run-on-failure keyword. Libraries extending SeleniumLibrary can overwrite this hook method if they want to provide custom functionality instead. """ if self._running_on_failure_keyword or not self.run_on_failure_keyword: return try: self._running_on_failure_keyword = True BuiltIn().run_keyword(self.run_on_failure_keyword) except Exception as err: logger.warn("Keyword '%s' could not be run on failure: %s" % (self.run_on_failure_keyword, err)) finally: self._running_on_failure_keyword = False @property def browser(self): """Current active browser""" if not self._browsers.current: raise RuntimeError('No browser is open') return self._browsers.current @property def _cache(self): warnings.warn( '"SeleniumLibrary._cache" is deprecated, ' 'use public API instead.', DeprecationWarning) return self._browsers def _current_browser(self): warnings.warn( '"SeleniumLibrary._current_browser" is deprecated, ' 'use "SeleniumLibrary.browser" instead.', DeprecationWarning) return self.browser def _run_on_failure(self): warnings.warn( '"SeleniumLibrary._run_on_failure" is deprecated, ' 'use "SeleniumLibrary.failure_occurred" instead.', DeprecationWarning) self.failure_occurred()
class SeleniumLibrary(DynamicCore): """SeleniumLibrary is a web testing library for Robot Framework. This document explains how to use keywords provided by SeleniumLibrary. For information about installation, support, and more, please visit the [https://github.com/robotframework/SeleniumLibrary|project pages]. For more information about Robot Framework, see http://robotframework.org. SeleniumLibrary uses the Selenium WebDriver modules internally to control a web browser. See http://seleniumhq.org for more information about Selenium in general. == Table of contents == - `Locating elements` - `Timeouts, waits and delays` - `Run-on-failure functionality` - `Boolean arguments` - `Importing` - `Shortcuts` - `Keywords` = Locating elements = All keywords in SeleniumLibrary that need to interact with an element on a web page take an argument named ``locator`` that specifies how to find the element. Most often the locator is given as a string using the locator syntax described below, but `using WebElements` is possible too. == Locator syntax == SeleniumLibrary supports finding elements based on different strategies such as the element id, XPath expressions, or CSS selectors. The strategy can either be explicitly specified with a prefix or the strategy can be implicit. === Explicit locator strategy === The explicit locator strategy is specified with a prefix using either syntax ``strategy:value`` or ``strategy=value``. The former syntax is preferred, because the latter is identical to Robot Framework's [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#named-argument-syntax| named argument syntax] and that can cause problems. Notice that the ``strategy:value`` syntax is olny supported by SeleniumLibrary 3.0 and newer, though. Locator strategies that are supported by default are listed in the table below. In addition to them, it is possible to register `custom locators`. | = Strategy = | = Match based on = | = Example = | | id | Element ``id``. | ``id:example`` | | name | ``name`` attribute. | ``name:example`` | | identifier | Either ``id`` or ``name``. | ``identifier:example`` | | class | Element ``class``. | ``class:example`` | | tag | Tag name. | ``tag:div`` | | xpath | XPath expression. | ``xpath://div[@id="example"]`` | | css | CSS selector. | ``css:div#example`` | | dom | DOM expression. | ``dom:document.images[5]`` | | link | Exact text a link has. | ``link:The example`` | | partial link | Partial link text. | ``partial link:he ex`` | | sizzle | Sizzle selector provided by jQuery. | ``sizzle:div.example`` | | jquery | Same as the above. | ``jquery:div.example`` | | default | Keyword specific default behavior. | ``default:example`` | See the `Default locator strategy` section below for more information about how the default strategy works. Using the explicit ``default`` prefix is only necessary if the locator value itself accidentally matches some of the explicit strategies. Spaces around the separator are ignored, so ``id : foo``, ``id: foo`` and ``id:foo`` are all equivalent. Examples: | `Click Element` | id:container | | `Click Element` | css:div#container h1 | | `Click Element` | xpath: //div[@id="container"]//h1 | Notice that using the ``sizzle`` strategy or its alias ``jquery`` requires that the system under test contains the jQuery library. === Implicit XPath strategy === If the locator starts with ``//`` or ``(//``, the locator is considered to be an XPath expression. In other words, using ``//div`` is equivalent to using explicit ``xpath://div``. Examples: | `Click Element` | //div[@id="container"] | | `Click Element` | (//div)[2] | The support for the ``(//`` prefix is new in SeleniumLibrary 3.0. === Default locator strategy === By default locators are considered to use the keyword specific default locator strategy. All keywords support finding elements based on ``id`` and ``name`` attributes, but some keywords support additional _key attributes_ that make sense in their context. For example, `Click Link` supports the link text and the ``href`` attribute in addition to the normal ``id`` and ``name``. Examples: | `Click Element` | example | # Match based on ``id`` or ``name``. | | `Click Link` | example | # Match also based on link text and ``href``. | | `Click Button` | example | # Match based on ``id``, ``name`` or ``value``. | If the locator accidentally starts with some of the explicit locator prefixes or with the implicit XPath prefixes, it is possible to use the explicit ``default`` prefix to enable the default strategy. Examples: | `Click Element` | name:foo | # Find element with name ``foo``. | | `Click Element` | default:name:foo | # Use default strategy with value ``name:foo``. | | `Click Element` | //foo | # Find element using XPath ``//foo``. | | `Click Element` | default://foo | # Use default strategy with value ``//foo``. | == Using WebElements == In addition to specifying a locator as a string, it is possible to use Selenium's WebElement objects. This requires first getting a WebElement, for example, by using the `Get WebElement` keyword. | ${elem} = | `Get WebElement` | id=example | | `Click Element` | ${elem} | | == Custom locators == If more complex lookups are required than what is provided through the default locators, custom lookup strategies can be created. Using custom locators is a two part process. First, create a keyword that returns a WebElement that should be acted on: | Custom Locator Strategy | [Arguments] | ${browser} | ${strategy} | ${tag} | ${constraints} | | | ${element}= | Execute Javascript | return window.document.getElementById('${criteria}'); | | | [Return] | ${element} | This keyword is a reimplementation of the basic functionality of the ``id`` locator where ``${browser}`` is a reference to a WebDriver instance and ``${strategy}`` is name of the locator strategy. To use this locator it must first be registered by using the `Add Location Strategy` keyword: | `Add Location Strategy` | custom | Custom Locator Strategy | The first argument of `Add Location Strategy` specifies the name of the strategy and it must be unique. After registering the strategy, the usage is the same as with other locators: | `Click Element` | custom:example | See the `Add Location Strategy` keyword for more details. == Locating tables == Starting from release 3.0.0, it is possible to locate table using all strategies supported by the library. Prior the release 3.0 tables could have been located with limited set of strategies and with limitations in the strategy. = Timeouts, waits and delays = This section discusses different ways how to wait for elements to appear on web pages and to slow down execution speed otherwise. It also explains the `time format` that can be used when setting various timeouts, waits and delays. == Timeout == SeleniumLibrary contains various keywords that have an optional ``timeout`` argument that specifies how long these keywords should wait for certain events or actions. These keywords include, for example, ``Wait ...`` keywords and keywords related to alerts. The default timeout these keywords use can be set globally either by using the `Set Selenium Timeout` keyword or with the ``timeout`` argument when `importing` the library. See `time format` below for supported timeout syntax. == Implicit wait == Implicit wait specifies the maximum time how long Selenium waits when searching for elements. It can be set by using the `Set Selenium Implicit Wait` keyword or with the ``implicit_wait`` argument when `importing` the library. See [http://seleniumhq.org/docs/04_webdriver_advanced.html| Selenium documentation] for more information about this functionality. See `time format` below for supported syntax. == Selenium speed == Selenium execution speed can be slowed down globally by using `Set Selenium speed` keyword. This functionality is designed to be used for demonstrating or debugging purposes. Using it to make sure that elements appear on a page is not a good idea, and the above explained timeouts and waits should be used instead. See `time format` below for supported syntax. == Time format == All timeouts and waits can be given as numbers considered seconds (e.g. ``0.5`` or ``42``) or in Robot Framework's time syntax (e.g. ``1.5 seconds`` or ``1 min 30 s``). For more information about the time syntax see the [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format|Robot Framework User Guide]. = Run-on-failure functionality = SeleniumLibrary has a handy feature that it can automatically execute a keyword if any of its own keywords fails. By default it uses the `Capture Page Screenshot` keyword, but this can be changed either by using the `Register Keyword To Run On Failure` keyword or with the ``run_on_failure`` argument when `importing` the library. It is possible to use any keyword from any imported library or resource file. The run-on-failure functionality can be disabled by using a special value ``NOTHING`` or anything considered false (see `Boolean arguments`) such as ``NONE``. = Boolean arguments = Some keywords accept arguments that are handled as Boolean values true or false. If such an argument is given as a string, it is considered false if it is either empty or case-insensitively equal to ``false``, ``no`` or ``none``. Other strings are considered true regardless their value, and other argument types are tested using same [https://docs.python.org/2/library/stdtypes.html#truth-value-testing|rules as in Python]. True examples: | `Set Screenshot Directory` | ${RESULTS} | persist=True | # Strings are generally true. | | `Set Screenshot Directory` | ${RESULTS} | persist=yes | # Same as the above. | | `Set Screenshot Directory` | ${RESULTS} | persist=${TRUE} | # Python True is true. | | `Set Screenshot Directory` | ${RESULTS} | persist=${42} | # Numbers other than 0 are true. | False examples: | `Set Screenshot Directory` | ${RESULTS} | persist=False | # String false is false. | | `Set Screenshot Directory` | ${RESULTS} | persist=no | # Also string no is false. | | `Set Screenshot Directory` | ${RESULTS} | persist=NONE | # String NONE is false. | | `Set Screenshot Directory` | ${RESULTS} | persist=${EMPTY} | # Empty string is false. | | `Set Screenshot Directory` | ${RESULTS} | persist=${FALSE} | # Python False is false. | | `Set Screenshot Directory` | ${RESULTS} | persist=${NONE} | # Python None is false. | Note that prior to SeleniumLibrary 3.0, all non-empty strings, including ``false``, ``no`` and ``none``, were considered true. """ ROBOT_LIBRARY_SCOPE = 'GLOBAL' ROBOT_LIBRARY_VERSION = __version__ def __init__(self, timeout=5.0, implicit_wait=0.0, run_on_failure='Capture Page Screenshot', screenshot_root_directory=None): """SeleniumLibrary can be imported with several optional arguments. - ``timeout``: Default value for `timeouts` used with ``Wait ...`` keywords. - ``implicit_wait``: Default value for `implicit wait` used when locating elements. - ``run_on_failure``: Default action for the `run-on-failure functionality`. - ``screenshot_root_directory``: Location where possible screenshots are created. If not given, the directory where the log file is written is used. """ self.timeout = timestr_to_secs(timeout) self.implicit_wait = timestr_to_secs(implicit_wait) self.speed = 0.0 self.run_on_failure_keyword \ = RunOnFailureKeywords.resolve_keyword(run_on_failure) self._running_on_failure_keyword = False self.screenshot_root_directory = screenshot_root_directory libraries = [ AlertKeywords(self), BrowserManagementKeywords(self), RunOnFailureKeywords(self), ElementKeywords(self), TableElementKeywords(self), FormElementKeywords(self), SelectElementKeywords(self), JavaScriptKeywords(self), CookieKeywords(self), ScreenshotKeywords(self), WaitingKeywords(self) ] self._browsers = BrowserCache() DynamicCore.__init__(self, libraries) self.ROBOT_LIBRARY_LISTENER = LibraryListener() 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') _implicit_wait_in_secs = Deprecated('_implicit_wait_in_secs', 'implicit_wait') _run_on_failure_keyword = Deprecated('_run_on_failure_keyword', 'run_on_failure_keyword') def run_keyword(self, name, args, kwargs): try: return DynamicCore.run_keyword(self, name, args, kwargs) except Exception: self.failure_occurred() raise def register_browser(self, browser, alias): return self._browsers.register(browser, alias) def failure_occurred(self): """Method that is executed when a SeleniumLibrary keyword fails. By default executes the registered run-on-failure keyword. Libraries extending SeleniumLibrary can overwrite this hook method if they want to provide custom functionality instead. """ if self._running_on_failure_keyword or not self.run_on_failure_keyword: return try: self._running_on_failure_keyword = True BuiltIn().run_keyword(self.run_on_failure_keyword) except Exception as err: logger.warn("Keyword '%s' could not be run on failure: %s" % (self.run_on_failure_keyword, err)) finally: self._running_on_failure_keyword = False @property def browser(self): """Current active browser""" if not self._browsers.current: raise RuntimeError('No browser is open') return self._browsers.current @property def _cache(self): warnings.warn('"SeleniumLibrary._cache" is deprecated, ' 'use public API instead.', DeprecationWarning) return self._browsers def _current_browser(self): warnings.warn('"SeleniumLibrary._current_browser" is deprecated, ' 'use "SeleniumLibrary.browser" instead.', DeprecationWarning) return self.browser def _run_on_failure(self): warnings.warn('"SeleniumLibrary._run_on_failure" is deprecated, ' 'use "SeleniumLibrary.failure_occurred" instead.', DeprecationWarning) self.failure_occurred()