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 project pages. For more information about Robot Framework, see https://robotframework.org.

SeleniumLibrary uses the Selenium WebDriver modules internally to control a web browser. See https://www.selenium.dev/ for more information about Selenium in general and SeleniumLibrary README.rst Browser drivers chapter for more details about WebDriver binary installation.

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 attributes or other values that make sense in their context. For example, Click Link supports the href attribute and the link text and 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 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 deprecated. sizzle:div.example
data Element data-* attribute data:id:my_id
jquery jQuery expression. 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 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.
  • data strategy is conveniance locator that will construct xpath from the parameters. If you have element like <div data-automation="automation-id-2">, you locate the element via data:automation:automation-id-2. This feature was added in SeleniumLibrary 5.2.0

Implicit XPath strategy

If the locator starts with // or multiple opening parenthesis in front of the //, the locator is considered to be an XPath expression. In other words, using //div is equivalent to using explicit xpath://div and ((//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. Supporting multiple opening parenthesis is new in SeleniumLibrary 5.0.

Chaining locators

It is possible chain multiple locators together as single locator. Each chained locator must start with locator strategy. Chained locators must be separated with single space, two greater than characters and followed with space. It is also possible mix different locator strategies, example css or xpath. Also a list can also be used to specify multiple locators. This is useful, is some part of locator would match as the locator separator but it should not. Or if there is need to existing WebElement as locator.

Although all locators support chaining, some locator strategies do not abey the chaining. This is because some locator strategies use JavaScript to find elements and JavaScript is executed for the whole browser context and not for the element found be the previous locator. Chaining is supported by locator strategies which are based on Selenium API, like xpath or css, but example chaining is not supported by sizzle or `jquery

Examples:

Click Element css:.bar >> xpath://a # To find a link which is present after an element with class "bar"

List examples:

${locator_list} = Create List css:div#div_id xpath://*[text(), " >> "]
Page Should Contain Element ${locator_list}
${element} = Get WebElement xpath://*[text(), " >> "]
${locator_list} = Create List css:div#div_id ${element}
Page Should Contain Element ${locator_list}

Chaining locators in new in SeleniumLibrary 5.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} ${locator} ${tag} ${constraints}
${element}= Execute Javascript return window.document.getElementById('${locator}');
[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 ${locator} is the 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.

Browser and Window

There is different conceptual meaning when SeleniumLibrary talks about windows or browsers. This chapter explains those differences.

Browser

When Open Browser or Create WebDriver keyword is called, it will create a new Selenium WebDriver instance by using the Selenium WebDriver API. In SeleniumLibrary terms, a new browser is created. It is possible to start multiple independent browsers (Selenium Webdriver instances) at the same time, by calling Open Browser or Create WebDriver multiple times. These browsers are usually independent of each other and do not share data like cookies, sessions or profiles. Typically when the browser starts, it creates a single window which is shown to the user.

Window

Windows are the part of a browser that loads the web site and presents it to the user. All content of the site is the content of the window. Windows are children of a browser. In SeleniumLibrary browser is a synonym for WebDriver instance. One browser may have multiple windows. Windows can appear as tabs, as separate windows or pop-ups with different position and size. Windows belonging to the same browser typically share the sessions detail, like cookies. If there is a need to separate sessions detail, example login with two different users, two browsers (Selenium WebDriver instances) must be created. New windows can be opened example by the application under test or by example Execute Javascript keyword:

Execute Javascript    window.open()    # Opens a new window with location about:blank

The example below opens multiple browsers and windows, to demonstrate how the different keywords can be used to interact with browsers, and windows attached to these browsers.

Structure:

BrowserA
           Window 1  (location=https://robotframework.org/)
           Window 2  (location=https://robocon.io/)
           Window 3  (location=https://github.com/robotframework/)

BrowserB
           Window 1  (location=https://github.com/)

Example:

Open Browser https://robotframework.org ${BROWSER} alias=BrowserA # BrowserA with first window is opened.
Execute Javascript window.open() # In BrowserA second window is opened.
Switch Window locator=NEW # Switched to second window in BrowserA
Go To https://robocon.io # Second window navigates to robocon site.
Execute Javascript window.open() # In BrowserA third window is opened.
${handle} Switch Window locator=NEW # Switched to third window in BrowserA
Go To https://github.com/robotframework/ # Third windows goes to robot framework github site.
Open Browser https://github.com ${BROWSER} alias=BrowserB # BrowserB with first windows is opened.
${location} Get Location # ${location} is: https://www.github.com
Switch Window ${handle} browser=BrowserA # BrowserA second windows is selected.
${location} Get Location # ${location} = https://robocon.io/
@{locations 1} Get Locations # By default, lists locations under the currectly active browser (BrowserA).
@{locations 2} Get Locations browser=ALL # By using browser=ALL argument keyword list all locations from all browsers.

The above example, @{locations 1} contains the following items: https://robotframework.org/, https://robocon.io/ and https://github.com/robotframework/'. The @{locations 2} contains the following items: https://robotframework.org/, https://robocon.io/, https://github.com/robotframework/' and 'https://github.com/.

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. Additionally Execute Async Javascript. Although it does not have timeout, argument, uses a timeout to define how long asynchronous JavaScript can run.

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 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. 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 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

Starting from 5.0 SeleniumLibrary relies on Robot Framework to perform the boolean conversion based on keyword arguments type hint. More details in Robot Framework user guide

Please note SeleniumLibrary 3 and 4 did have own custom methods to covert arguments to boolean values.

EventFiringWebDriver

The SeleniumLibrary offers support for EventFiringWebDriver. See the Selenium and SeleniumLibrary EventFiringWebDriver support documentation for further details.

EventFiringWebDriver is new in SeleniumLibrary 4.0

Thread support

SeleniumLibrary is not thread-safe. This is mainly due because the underlying Selenium tool is not thread-safe within one browser/driver instance. Because of the limitation in the Selenium side, the keywords or the API provided by the SeleniumLibrary is not thread-safe.

Plugins

SeleniumLibrary offers plugins as a way to modify and add library keywords and modify some of the internal functionality without creating a new library or hacking the source code. See plugin API documentation for further details.

Plugin API is new SeleniumLibrary 4.0

Auto closing browser

By default browser instances created during task execution are closed at the end of the task. This can be prevented with the auto_close argument when importing the library.

Value needs to be set to False or anything considered false (see Boolean arguments).