RPA.Browser.Selenium library | Robocorp documentation

RPA.Browser.Selenium

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 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 and SeleniumLibrary README.rst Browser drivers chapter for more details about WebDriver binary installation.

Locating elements
Browser and Window
Timeouts, waits, and delays
Run-on-failure functionality
Boolean arguments
EventFiringWebDriver
Thread support
Plugins
Auto closing browser
Importing
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 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. If no default timeout is set globally, the default is 5 seconds. If None is specified for the timeout argument in the keywords, the default is used. 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.

Page load

Page load timeout is the amount of time to wait for page load to complete until a timeout exception is raised.

The default page load timeout can be set globally when importing the library with the page_load_timeout argument or by using the Set Selenium Page Load Timeout keyword.

See time format below for supported timeout syntax.

Support for page load is new in SeleniumLibrary 6.1

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.

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: Path to folder where possible screenshots are created or EMBED. See Set Screenshot Directory keyword for further details about EMBED. If not given, the directory where the log file is written is used.
plugins: Allows extending the SeleniumLibrary with external Python classes.
event_firing_webdriver: Class for wrapping Selenium with EventFiringWebDriver
page_load_timeout: Default value to wait for page load to complete until a timeout exception is raised.
action_chain_delay: Default value for ActionChains delay to wait in between actions.