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
Browser and Driver options and service class
Timeouts, waits, and delays
Run-on-failure functionality
Boolean arguments
EventFiringWebDriver
Thread support
Plugins
Language
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 obey 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/.

Browser and Driver options and service class

This section talks about how to configure either the browser or the driver using the options and service arguments of the Open Browser keyword.

Configuring the browser using the Selenium Options

As noted within the keyword documentation for Open Browser, its options argument accepts Selenium options in two different formats: as a string and as Python object which is an instance of the Selenium options class.

Options string format

The string format allows defining Selenium options methods or attributes and their arguments in Robot Framework test data. The method and attributes names are case and space sensitive and must match to the Selenium options methods and attributes names. When defining a method, it must be defined in a similar way as in python: method name, opening parenthesis, zero to many arguments and closing parenthesis. If there is a need to define multiple arguments for a single method, arguments must be separated with comma, just like in Python. Example: add_argument("--headless") or add_experimental_option("key", "value"). Attributes are defined in a similar way as in Python: attribute name, equal sign, and attribute value. Example, headless=True. Multiple methods and attributes must be separated by a semicolon. Example: add_argument("--headless");add_argument("--start-maximized").

Arguments allow defining Python data types and arguments are evaluated by using Python ast.literal_eval. Strings must be quoted with single or double quotes, example "value" or 'value'. It is also possible to define other Python builtin data types, example True or None, by not using quotes around the arguments.

The string format is space friendly. Usually, spaces do not alter the defining methods or attributes. There are two exceptions. In some Robot Framework test data formats, two or more spaces are considered as cell separator and instead of defining a single argument, two or more arguments may be defined. Spaces in string arguments are not removed and are left as is. Example add_argument ( "--headless" ) is same as add_argument("--headless"). But add_argument(" --headless ") is not same same as add_argument ( "--headless" ), because spaces inside of quotes are not removed. Please note that if options string contains backslash, example a Windows OS path, the backslash needs escaping both in Robot Framework data and in Python side. This means single backslash must be writen using four backslash characters. Example, Windows path: "C:\path\to\profile" must be written as "C:\\\\path\\\to\\\\profile". Another way to write backslash is use Python raw strings and example write: r"C:\\path\\to\\profile".

Selenium Options as Python class

As last format, options argument also supports receiving the Selenium options as Python class instance. In this case, the instance is used as-is and the SeleniumLibrary will not convert the instance to other formats. For example, if the following code return value is saved to ${options} variable in the Robot Framework data:

options = webdriver.ChromeOptions()
options.add_argument('--disable-dev-shm-usage')
return options

Then the ${options} variable can be used as an argument to options.

Example the options argument can be used to launch Chomium-based applications which utilize the Chromium Embedded Framework . To launch Chromium-based application, use options to define binary_location attribute and use add_argument method to define remote-debugging-port port for the application. Once the browser is opened, the test can interact with the embedded web-content of the system under test.

Configuring the driver using the Service class

With the service argument, one can setup and configure the driver. For example one can set the driver location and/port or specify the command line arguments. There are several browser specific attributes related to logging as well. For the various Service Class attributes refer to the Selenium documentation . Currently the service argument only accepts Selenium service in the string format.

Service string format

The string format allows for defining Selenium service attributes and their values in the Open Browser keyword. The attributes names are case and space sensitive and must match to the Selenium attributes names. Attributes are defined in a similar way as in Python: attribute name, equal sign, and attribute value. Example, port=1234. Multiple attributes must be separated by a semicolon. Example: executable_path='/path/to/driver';port=1234. Don't have duplicate attributes, like service_args=['--append-log', '--readable-timestamp']; service_args=['--log-level=DEBUG'] as the second will override the first. Instead combine them as in service_args=['--append-log', '--readable-timestamp', '--log-level=DEBUG']

Arguments allow defining Python data types and arguments are evaluated by using Python. Strings must be quoted with single or double quotes, example "value" or 'value'

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.

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

Language

SeleniumLibrary offers the possibility to translate keyword names and documentation to new language. If language is defined, SeleniumLibrary will search from module search path for Python packages starting with robotframework-seleniumlibrary-translation by using the Python pluging API. The Library is using naming convention to find Python plugins.

The package must implement a single API call, get_language without any arguments. The method must return a dictionary containing two keys: language and path. The language key value defines which language the package contains. Also the value should match (case insensitive) the library language import parameter. The path parameter value should be full path to the translation file.

Translation file

The file name or extension is not important, but data must be in json format. The keys of json are the methods names, not the keyword names, which implements keywords. Value of key is json object which contains two keys: name and doc. The name key contains the keyword translated name and doc contains translated documentation. Providing doc and name are optional, example translation json file can only provide translations to keyword names or only to documentation. But it is always recommended to provide translation to both name and doc. Special key __intro__ is for class level documentation and __init__ is for init level documentation. These special values name can not be translated, instead name should be kept the same.

Generating template translation file

Template translation file, with English language can be created by running: rfselib translation /path/to/translation.json command. Command does not provide translations to other languages, it only provides easy way to create full list keywords and their documentation in correct format. It is also possible to add keywords from library plugins by providing --plugins arguments to command. Example: rfselib translation --plugins myplugin.SomePlugin /path/to/translation.json The generated json file contains sha256 key, which contains the sha256 sum of the library documentation. The sha256 sum is used by rfselib translation --compare /path/to/translation.json command, which compares the translation to the library and prints outs a table which tells if there are changes needed for the translation file.

Example project for translation can be found from robotframework-seleniumlibrary-translation-fi repository.

Opening library documentation failed