From cc9e63dcec717b96fc953a85ed6bf478543605d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pekka=20Kl=C3=A4rck?= Date: Mon, 25 Sep 2017 15:43:58 +0300 Subject: [PATCH 1/6] Re-wrote generic library document. Includes explaining the new `strategy:value` syntax (#908). --- src/SeleniumLibrary/__init__.py | 323 +++++++++++++++++++------------- 1 file changed, 191 insertions(+), 132 deletions(-) diff --git a/src/SeleniumLibrary/__init__.py b/src/SeleniumLibrary/__init__.py index 07e658c12..27a8f213b 100644 --- a/src/SeleniumLibrary/__init__.py +++ b/src/SeleniumLibrary/__init__.py @@ -42,133 +42,190 @@ 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. + 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` + - ` Boolean arguments` + - `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 class ``foo``. | + | `Click Element` | default:name:foo | # Use default strategy with value ``class:foo``. | + | `Click Element` | //foo | # Find element using XPath ``//foo``. | + | `Click Element` | //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 == + + Locating tables when using table related keywords, such as + `Table Should Contain`, works differently than locating other elements. + The main differences are: + + - The default strategy is to search only by ``id``, not by ``name``. + - Implicit XPath strategies using format ``//example`` is not supported. + - Only explicit strategies that are supported are ``xpath``, `css`` + and ``sizzle/jquery``. + - Spaces are not allowed around the separator between the strategy and + the value. + + Examples: + + | `Table Should Contain` | example | text | # Match based on ``id``. | + | `Table Should Contain` | css=table.example | text | # Match using CSS selector. | + | `Table Should Contain` | xpath=//table/[@name="example"] | text | # Match using XPath expression. | + + The plan is to uniform locating tables and locating other elements in + the future. = Timeouts = - There are several `Wait ...` keywords that take timeout as an + 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`. + 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 + 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 = @@ -181,18 +238,20 @@ class SeleniumLibrary(DynamicCore): [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. | + + | `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 | ${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. | + + | `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. From 108ea816d7df93598025588ff25ce507963af2a6 Mon Sep 17 00:00:00 2001 From: Tatu Aalto Date: Mon, 25 Sep 2017 21:28:51 +0300 Subject: [PATCH 2/6] Added missing `-character on line 205 --- src/SeleniumLibrary/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/SeleniumLibrary/__init__.py b/src/SeleniumLibrary/__init__.py index 27a8f213b..2cbc810a2 100644 --- a/src/SeleniumLibrary/__init__.py +++ b/src/SeleniumLibrary/__init__.py @@ -202,7 +202,7 @@ class SeleniumLibrary(DynamicCore): - The default strategy is to search only by ``id``, not by ``name``. - Implicit XPath strategies using format ``//example`` is not supported. - - Only explicit strategies that are supported are ``xpath``, `css`` + - Only explicit strategies that are supported are ``xpath``, ``css`` and ``sizzle/jquery``. - Spaces are not allowed around the separator between the strategy and the value. From b6c6e22e5a4e94ce07aef302a9c9968eea20bad1 Mon Sep 17 00:00:00 2001 From: Tatu Aalto Date: Mon, 25 Sep 2017 21:39:52 +0300 Subject: [PATCH 3/6] Fixing import argument. 'implicit_wait' -> `implicit_wait` --- src/SeleniumLibrary/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/SeleniumLibrary/__init__.py b/src/SeleniumLibrary/__init__.py index 2cbc810a2..186e67a2d 100644 --- a/src/SeleniumLibrary/__init__.py +++ b/src/SeleniumLibrary/__init__.py @@ -270,7 +270,7 @@ def __init__(self, `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 + `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 From de193eba03fe302d18150e5c5636d8f825d165e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pekka=20Kl=C3=A4rck?= Date: Mon, 25 Sep 2017 23:04:52 +0300 Subject: [PATCH 4/6] Tuning general docs based on review comments --- src/SeleniumLibrary/__init__.py | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/src/SeleniumLibrary/__init__.py b/src/SeleniumLibrary/__init__.py index 186e67a2d..ffb9bfc77 100644 --- a/src/SeleniumLibrary/__init__.py +++ b/src/SeleniumLibrary/__init__.py @@ -53,9 +53,9 @@ class SeleniumLibrary(DynamicCore): == Table of contents == - - ` Locating elements` - - ` Timeouts` - - ` Boolean arguments` + - `Locating elements` + - `Timeouts` + - `Boolean arguments` - `Shortcuts` - `Keywords` @@ -153,10 +153,10 @@ class SeleniumLibrary(DynamicCore): Examples: - | `Click Element` | name:foo | # Find element with class ``foo``. | - | `Click Element` | default:name:foo | # Use default strategy with value ``class:foo``. | - | `Click Element` | //foo | # Find element using XPath ``//foo``. | - | `Click Element` | //foo | # Use default strategy with value ``//foo``. | + | `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 == @@ -221,7 +221,8 @@ class SeleniumLibrary(DynamicCore): 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`. + keyword or when `importing` the library. 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 From e27bfef56c635030444b8c01394aab8b408b79b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pekka=20Kl=C3=A4rck?= Date: Tue, 26 Sep 2017 10:26:48 +0300 Subject: [PATCH 5/6] Type hint for IDEs --- src/SeleniumLibrary/base/context.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/SeleniumLibrary/base/context.py b/src/SeleniumLibrary/base/context.py index 0dc3ebc81..178390571 100644 --- a/src/SeleniumLibrary/base/context.py +++ b/src/SeleniumLibrary/base/context.py @@ -18,6 +18,11 @@ 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. + """ self.ctx = ctx @property From 12bfc9335e6ec05ae31dc2d676459ebadfa6ca15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pekka=20Kl=C3=A4rck?= Date: Tue, 26 Sep 2017 11:09:18 +0300 Subject: [PATCH 6/6] Tuning general documentation. Explain general topics in the general library documentation section, not in __init__. --- src/SeleniumLibrary/__init__.py | 109 ++++++++++++++++++++------------ 1 file changed, 67 insertions(+), 42 deletions(-) diff --git a/src/SeleniumLibrary/__init__.py b/src/SeleniumLibrary/__init__.py index ffb9bfc77..8641c990f 100644 --- a/src/SeleniumLibrary/__init__.py +++ b/src/SeleniumLibrary/__init__.py @@ -54,8 +54,10 @@ class SeleniumLibrary(DynamicCore): == Table of contents == - `Locating elements` - - `Timeouts` + - `Timeouts, waits and delays` + - `Run-on-failure functionality` - `Boolean arguments` + - `Importing` - `Shortcuts` - `Keywords` @@ -216,19 +218,62 @@ class SeleniumLibrary(DynamicCore): The plan is to uniform locating tables and locating other elements in the future. - = Timeouts = + = Timeouts, waits and delays = - 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 or when `importing` the library. The same timeout also applies - to `Execute Async Javascript`. + 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. - 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 + == Timeouts == + + SeleniumLibrary contains various ``Wait ...`` keywords that can be used + to wait, for example, for a dynamically created elements to appear on + a page. All these keywords accept an optional ``timeout`` argument that + tells the maximum time to wait. + + 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. The same timeout also applies to the + `Execute Async Javascript` keyword. + + == 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. + + == 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. + + == 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 @@ -260,41 +305,21 @@ class SeleniumLibrary(DynamicCore): ROBOT_LIBRARY_SCOPE = 'GLOBAL' ROBOT_LIBRARY_VERSION = __version__ - def __init__(self, - timeout=5.0, - implicit_wait=0.0, + 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 | + """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)