RPA.Browser.Selenium

module RPA.Browser.Selenium

class RPA.Browser.Selenium.Selenium

Selenium(*args, **kwargs)

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.

%TOC%

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 Elementexample# Match based on id or name.
Click Linkexample# Match also based on link text and href.
Click Buttonexample# 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 Elementname:foo# Find element with name foo.
Click Elementdefault:name:foo# Use default strategy with value name:foo.
Click Element//foo# Find element using XPath //foo.
Click Elementdefault: //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.

StrategyMatch based onExample
idElement id.id:example
namename attribute.name:example
identifierEither id or name.identifier:example
classElement class.class:example
tagTag name.tag:div
xpathXPath expression.xpath://div[@id="example"]
cssCSS selector.css:div#example
domDOM expression.dom:document.images[5]
linkExact text a link has.link:The example
partial linkPartial link text.partial link:he ex
sizzleSizzle selector deprecated.sizzle:div.example
dataElement data-* attributedata:id:my_id
jqueryjQuery expression.jquery:div.example
defaultKeyword 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 Elementid:foo# Element with id ‘foo’.
Click Elementcss:div#foo h1# h1 element under div with id ‘foo’.
Click Elementxpath: //div[@id=”foo”]//h1# Same as the above using XPath, not CSS.
Click Elementxpath: //<br/>*<br/>[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 , 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 Elementcss:.bar >> xpath://a# To find a link which is present after an element with class “bar”

List examples:

${locator_list} =Create Listcss:div#div_id[xpath://*text(, ” >> “]
Page Should Contain Element${locator_list}
${element} =Get WebElement[xpath://*text(, ” >> “]
${locator_list} =Create Listcss: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 WebElementid: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]${element}=[Return]${browser}Execute Javascript${element}${locator}return window.document.getElementById(‘${locator}’);${tag}${constraints}

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 StrategycustomCustom 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 Elementcustom: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/)

Open Browserhttps://robotframework.org${BROWSER}alias=BrowserA# BrowserA with first window is opened.
Execute Javascriptwindow.open()# In BrowserA second window is opened.
Switch Windowlocator=NEW# Switched to second window in BrowserA
Go Tohttps://robocon.io# Second window navigates to robocon site.
Execute Javascriptwindow.open()# In BrowserA third window is opened.
${handle}Switch Windowlocator=NEW# Switched to third window in BrowserA
Go Tohttps://github.com/robotframework/# Third windows goes to robot framework github site.
Open Browserhttps://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 Locationsbrowser=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.

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, the browser instances created during a task execution are closed at the end of the task. This can be prevented with the auto_close parameter when importing the library.

The value of the parameter needs to be set to False or any object evaluated as false (see Boolean arguments).


variable AVAILABLE_OPTIONS

AVAILABLE_OPTIONS = {'chrome': <class 'selenium.webdriver.chrome.options.Options'>, 'chromiumedge': <class 'selenium.webdriver.edge.options.Options'>, 'edge': <class 'selenium.webdriver.edge.options.Options'>, 'firefox': <class 'RPA.Browser.Selenium.FirefoxOptions'>, 'ie': <class 'selenium.webdriver.ie.options.Options'>, 'safari': <class 'selenium.webdriver.safari.options.Options'>}

variable AVAILABLE_SERVICES

AVAILABLE_SERVICES = {'chrome': (<class 'selenium.webdriver.chrome.service.Service'>, 'chromedriver'), 'chromiumedge': (<class 'selenium.webdriver.edge.service.Service'>, 'msedgedriver'), 'edge': (<class 'selenium.webdriver.edge.service.Service'>, 'msedgedriver'), 'firefox': (<class 'selenium.webdriver.firefox.service.Service'>, 'geckodriver'), 'ie': (<class 'selenium.webdriver.ie.service.Service'>, 'IEDriverServer'), 'safari': (<class 'selenium.webdriver.safari.service.Service'>, 'safaridriver')}

variable BROWSER_NAMES

BROWSER_NAMES = {'chrome': 'chrome', 'chromiumedge': 'edge', 'edge': 'edge', 'ff': 'firefox', 'firefox': 'firefox', 'gc': 'chrome', 'googlechrome': 'chrome', 'headlesschrome': 'headless_chrome', 'headlessfirefox': 'headless_firefox', 'ie': 'ie', 'internetexplorer': 'ie', 'safari': 'safari'}

variable CHROMIUM_BROWSERS

CHROMIUM_BROWSERS = ['chrome', 'edge', 'chromiumedge', 'msedge', 'ie']

variable ROBOT_LIBRARY_DOC_FORMAT

ROBOT_LIBRARY_DOC_FORMAT = 'ROBOT'

variable ROBOT_LIBRARY_SCOPE

ROBOT_LIBRARY_SCOPE = 'GLOBAL'

variable ROBOT_LIBRARY_VERSION

ROBOT_LIBRARY_VERSION = '6.2.0'

variable SUPPORTED_BROWSERS

SUPPORTED_BROWSERS = {'chrome': 'Chrome', 'chromiumedge': 'ChromiumEdge', 'edge': 'Edge', 'firefox': 'Firefox', 'ie': 'Ie', 'safari': 'Safari'}

method add_cookie

add_cookie(name: str, value: str, path: Optional[str] = None, domain: Optional[str] = None, secure: Optional[bool] = None, expiry: Optional[str] = None)

Adds a cookie to your current session.

name and value are required, path, domain, secure and expiry are optional. Expiry supports the same formats as the DateTime library or an epoch timestamp.

Add Cookiefoobar
Add Cookiefoobardomain=example.com
Add Cookiefoobarexpiry=2027-09-28 16:21:35# Expiry as timestamp.
Add Cookiefoobarexpiry=1822137695# Expiry as epoch seconds.

Prior to SeleniumLibrary 3.0 setting expiry did not work.


method add_library_components

add_library_components(library_components: List, translation: Optional[dict] = None)

method add_location_strategy

add_location_strategy(strategy_name: str, strategy_keyword: str, persist: bool = False)

Adds a custom location strategy.

See Custom locators for information on how to create and use custom strategies. Remove Location Strategy can be used to remove a registered strategy.

Location strategies are automatically removed after leaving the current scope by default. Setting persist to a true value (see Boolean arguments) will cause the location strategy to stay registered throughout the life of the test.


method alert_should_be_present

alert_should_be_present(text: str = '', action: str = 'ACCEPT', timeout: Optional[timedelta] = None)

Verifies that an alert is present and by default, accepts it.

Fails if no alert is present. If text is a non-empty string, then it is used to verify alert’s message. The alert is accepted by default, but that behavior can be controlled by using the action argument same way as with Handle Alert.

timeout specifies how long to wait for the alert to appear. If it is not given, the global default timeout is used instead.

action and timeout arguments are new in SeleniumLibrary 3.0. In earlier versions, the alert was always accepted and a timeout was hardcoded to one second.


method alert_should_not_be_present

alert_should_not_be_present(action: str = 'ACCEPT', timeout: Optional[timedelta] = None)

Verifies that no alert is present.

If the alert actually exists, the action argument determines how it should be handled. By default, the alert is accepted, but it can be also dismissed or left open the same way as with the Handle Alert keyword.

timeout specifies how long to wait for the alert to appear. By default, is not waited for the alert at all, but a custom time can be given if alert may be delayed. See the time format section for information about the syntax.

New in SeleniumLibrary 3.0.


method assign_id_to_element

assign_id_to_element(locator: Union[WebElement, str], id: str)

Assigns a temporary id to the element specified by locator.

This is mainly useful if the locator is complicated and/or slow XPath expression and it is needed multiple times. Identifier expires when the page is reloaded.

See the Locating elements section for details about the locator syntax.

Assign ID to Element//ul[@class=’example’ and ./li[contains(., ‘Stuff’)]]my id
Page Should Contain Elementmy id

method attach_chrome_browser

attach_chrome_browser(port: int, alias: Optional[str] = None)

Attach to an existing instance of Chrome browser.

Requires that the browser was started with the command line option --remote-debugging-port=<port>, where port is any 4-digit number not being used by other applications.

Note. The first Chrome instance on the system needs to be started with this command line option or this won’t have an effect.

That port can then be used to connect using this keyword.

Attach Chrome Browserport=9222

method capture_element_screenshot

capture_element_screenshot(locator: Union[WebElement, None, str], filename: str = 'selenium-element-screenshot-{index}.png')

Captures a screenshot from the element identified by locator and embeds it into log file.

See Capture Page Screenshot for details about filename argument. See the Locating elements section for details about the locator syntax.

An absolute path to the created element screenshot is returned.

Support for capturing the screenshot from an element has limited support among browser vendors. Please check the browser vendor driver documentation does the browser support capturing a screenshot from an element.

New in SeleniumLibrary 3.3. Support for EMBED is new in SeleniumLibrary 4.2.

Capture Element Screenshotid:image_id
Capture Element Screenshotid:image_id${OUTPUTDIR}/id_image_id-1.png
Capture Element Screenshotid:image_idEMBED

method capture_page_screenshot

capture_page_screenshot(filename: str = 'selenium-screenshot-{index}.png')

Takes a screenshot of the current page and embeds it into a log file.

filename argument specifies the name of the file to write the screenshot into. The directory where screenshots are saved can be set when importing the library or by using the Set Screenshot Directory keyword. If the directory is not configured, screenshots are saved to the same directory where Robot Framework’s log file is written.

If filename equals to EMBED (case insensitive), then screenshot is embedded as Base64 image to the log.html. In this case file is not created in the filesystem.

Starting from SeleniumLibrary 1.8, if filename contains marker {index}, it will be automatically replaced with an unique running index, preventing files to be overwritten. Indices start from 1, and how they are represented can be customized using Python’s format string syntax.

An absolute path to the created screenshot file is returned or if filename equals to EMBED, word EMBED is returned.

Support for EMBED is new in SeleniumLibrary 4.2

Capture Page Screenshot
File Should Exist${OUTPUTDIR}/selenium-screenshot-1.png
${path} =Capture Page Screenshot
File Should Exist${OUTPUTDIR}/selenium-screenshot-2.png
File Should Exist${path}
Capture Page Screenshotcustom_name.png
File Should Exist${OUTPUTDIR}/custom_name.png
Capture Page Screenshotcustom_with_index_{index}.png
File Should Exist${OUTPUTDIR}/custom_with_index_1.png
Capture Page Screenshotformatted_index_{index:03}.png
File Should Exist${OUTPUTDIR}/formatted_index_001.png
Capture Page ScreenshotEMBED
File Should Not ExistEMBED

method checkbox_should_be_selected

checkbox_should_be_selected(locator: Union[WebElement, str])

Verifies checkbox locator is selected/checked.

See the Locating elements section for details about the locator syntax.


method checkbox_should_not_be_selected

checkbox_should_not_be_selected(locator: Union[WebElement, str])

Verifies checkbox locator is not selected/checked.

See the Locating elements section for details about the locator syntax.


method choose_file

choose_file(locator: Union[WebElement, str], file_path: str)

Inputs the file_path into the file input field locator.

This keyword is most often used to input files into upload forms. The keyword does not check file_path is the file or folder available on the machine where tests are executed. If the file_path points at a file and when using Selenium Grid, Selenium will magically, transfer the file from the machine where the tests are executed to the Selenium Grid node where the browser is running. Then Selenium will send the file path, from the nodes file system, to the browser.

That file_path is not checked, is new in SeleniumLibrary 4.0.

Choose Filemy_upload_field${CURDIR}/trades.csv

method clear_all_highlights

clear_all_highlights()

Remove all highlighting made by Highlight Elements.


method clear_element_text

clear_element_text(locator: Union[WebElement, str])

Clears the value of the text-input-element identified by locator.

See the Locating elements section for details about the locator syntax.


method click_button

click_button(locator: Union[WebElement, str], modifier: Union[bool, str] = False)

Clicks the button identified by locator.

See the Locating elements section for details about the locator syntax. When using the default locator strategy, buttons are searched using id, name, and value.

See the Click Element keyword for details about the modifier argument.

The modifier argument is new in SeleniumLibrary 3.3


method click_button_when_visible

click_button_when_visible(locator: Union[WebElement, ShadowRoot, str], modifier: Optional[str] = None)

Click button identified by locator, once it becomes visible.

locator element locator

modifier press given keys while clicking the element, e.g. CTRL

Click Button When Visible//button[@class=”mybutton”]

method click_element

click_element(locator: Union[WebElement, str], modifier: Union[bool, str] = False, action_chain: bool = False)

Click the element identified by locator.

See the Locating elements section for details about the locator syntax.

The modifier argument can be used to pass Selenium Keys when clicking the element. The + can be used as a separator for different Selenium Keys. The CTRL is internally translated to the CONTROL key. The modifier is space and case insensitive, example “alt” and ” aLt ” are supported formats to ALT key . If modifier does not match to Selenium Keys, keyword fails.

If action_chain argument is true, see Boolean arguments for more details on how to set boolean argument, then keyword uses ActionChain based click instead of the <web_element>.click() function. If both action_chain and modifier are defined, the click will be performed using modifier and action_chain will be ignored.

Click Elementid:button# Would click element without any modifiers.
Click Elementid:buttonCTRL# Would click element with CTLR key pressed down.
Click Elementid:buttonCTRL+ALT# Would click element with CTLR and ALT keys pressed down.
Click Elementid:buttonaction_chain=True# Clicks the button using an Selenium ActionChains

The modifier argument is new in SeleniumLibrary 3.2 The action_chain argument is new in SeleniumLibrary 4.1


method click_element_at_coordinates

click_element_at_coordinates(locator: Union[WebElement, str], xoffset: int, yoffset: int)

Click the element locator at xoffset/yoffset.

The Cursor is moved and the center of the element and x/y coordinates are calculated from that point.

See the Locating elements section for details about the locator syntax.


method click_element_if_visible

click_element_if_visible(locator: Union[WebElement, ShadowRoot, str])

Click element if it is visible

locator element locator

Click Element If Visible//button[@class=”mybutton”]

method click_element_when_clickable

click_element_when_clickable(locator: Union[WebElement, ShadowRoot, str], timeout: Optional[Union[str, int, timedelta]] = None)

Waits for and clicks an element until is fully ready to be clicked.

If a normal click doesn’t work, then JavaScript-oriented workarounds are tried as a fallback mechanism.

Parameter locator targets the element to be clicked. Parameter timeout optionally configures a custom duration to wait for the element to become clickable, until it gives up.

Click Element When Clickableexample

method click_element_when_visible

click_element_when_visible(locator: Union[WebElement, ShadowRoot, str], modifier: Optional[str] = None, action_chain: bool = False)

Click element identified by locator, once it becomes visible.

locator element locator

modifier press given keys while clicking the element, e.g. CTRL

action_chain store action in Selenium ActionChain queue

Click Element When Visibleq
Click Element When Visibleid:buttonCTRL+ALT
Click Element When Visibleaction_chain=True

method click_image

click_image(locator: Union[WebElement, str], modifier: Union[bool, str] = False)

Clicks an image identified by locator.

See the Locating elements section for details about the locator syntax. When using the default locator strategy, images are searched using id, name, src and alt.

See the Click Element keyword for details about the modifier argument.

The modifier argument is new in SeleniumLibrary 3.3


click_link(locator: Union[WebElement, str], modifier: Union[bool, str] = False)

Clicks a link identified by locator.

See the Locating elements section for details about the locator syntax. When using the default locator strategy, links are searched using id, name, href and the link text.

See the Click Element keyword for details about the modifier argument.

The modifier argument is new in SeleniumLibrary 3.3


method close_all_browsers

close_all_browsers()

Closes all open browsers and resets the browser cache.

After this keyword, new indexes returned from Open Browser keyword are reset to 1.

This keyword should be used in test or suite teardown to make sure all browsers are closed.


method close_browser

close_browser()

Closes the current browser.


method close_window

close_window()

Closes currently opened and selected browser window/tab.


method cover_element

cover_element(locator: Union[WebElement, str])

Will cover elements identified by locator with a blue div without breaking page layout.

See the Locating elements section for details about the locator syntax.

New in SeleniumLibrary 3.3.0

Examples

|

Cover Element | css:div#container |


method create_webdriver

create_webdriver(driver_name: str, alias: Optional[str] = None, kwargs: Optional[dict] = None, **init_kwargs)

Creates an instance of Selenium WebDriver.

Like Open Browser, but allows passing arguments to the created WebDriver instance directly. This keyword should only be used if the functionality provided by Open Browser is not adequate.

driver_name must be a WebDriver implementation name like Firefox, Chrome, Ie, Edge, Safari, or Remote.

The initialized WebDriver can be configured either with a Python dictionary kwargs or by using keyword arguments **init_kwargs. These arguments are passed directly to WebDriver without any processing. See Selenium API documentation for details about the supported arguments.

# Use proxy with Firefox
${proxy}=Evaluateselenium.webdriver.Proxy()modules=selenium, selenium.webdriver
${proxy.http_proxy}=Set Variablelocalhost:8888
Create WebdriverFirefoxproxy=${proxy}

Returns the index of this browser instance which can be used later to switch back to it. Index starts from 1 and is reset back to it when Close All Browsers keyword is used. See Switch Browser for an example.


method current_frame_should_contain

current_frame_should_contain(text: str, loglevel: str = 'TRACE')

Verifies that the current frame contains text.

See Page Should Contain for an explanation about the loglevel argument.

Prior to SeleniumLibrary 3.0 this keyword was named Current Frame Contains.


method current_frame_should_not_contain

current_frame_should_not_contain(text: str, loglevel: str = 'TRACE')

Verifies that the current frame does not contain text.

See Page Should Contain for an explanation about the loglevel argument.


method delete_all_cookies

delete_all_cookies()

Deletes all cookies.


method delete_cookie

delete_cookie(name)

Deletes the cookie matching name.

If the cookie is not found, nothing happens.


method does_alert_contain

does_alert_contain(text: Optional[str] = None, timeout: Optional[Union[str, int, timedelta]] = None)

Does alert contain text.

text check if alert includes text, will raise ValueError is text does not exist

${res}Does Alert Containalert message

method does_alert_not_contain

does_alert_not_contain(text: Optional[str] = None, timeout: Optional[Union[str, int, timedelta]] = None)

Does alert not contain text.

text check that alert does not include text, will raise ValueError if text does exist

${res}Does Alert Not Containunexpected message

method does_element_contain

does_element_contain(locator: Union[WebElement, ShadowRoot, str], expected: str, ignore_case: bool = False)

Does element contain expected text

locator element locator

expected expected element text

ignore_case should check be case insensitive, default False

${res}Does Element Containid:specspecification completeignore_case=True

method does_frame_contain

does_frame_contain(locator: Union[WebElement, ShadowRoot, str], text: str)

Does frame contain expected text

locator locator of the frame to check

text does frame contain this text

${res}Does Frame Containid:myframesecret

method does_location_contain

does_location_contain(expected: str)

Does current URL contain expected

expected URL should contain this

Open Available Browserhttps://robocorp.com
${res}Does Location Containrobocorp

method does_page_contain

does_page_contain(text: str)

Does page contain expected text

text page should contain this

Open Available Browserhttps://google.com
${res}Does Page ContainGmail

method does_page_contain_button

does_page_contain_button(locator: Union[WebElement, ShadowRoot, str])

Does page contain expected button

locator element locator

${res}Does Page Contain Buttonsearch-button

method does_page_contain_checkbox

does_page_contain_checkbox(locator: Union[WebElement, ShadowRoot, str])

Does page contain expected checkbox

locator element locator

${res}Does Page Contain Checkboxrandom-selection

method does_page_contain_element

does_page_contain_element(locator: Union[WebElement, ShadowRoot, str], count: Optional[int] = None)

Does page contain expected element

locator element locator

count how many times element is expected to appear on page by default one or more

${res}Does Page Contain Elementtextarea
${res}Does Page Contain Elementbuttoncount=4

method does_page_contain_image

does_page_contain_image(locator: Union[WebElement, ShadowRoot, str])

Does page contain expected image

locator element locator

Open Available Browserhttps://google.com
${res}Does Page Contain ImageGoogle

does_page_contain_link(locator: Union[WebElement, ShadowRoot, str])

Does page contain expected link

locator element locator

${res}Does Page Contain Linkid:submit

method does_page_contain_list

does_page_contain_list(locator: Union[WebElement, ShadowRoot, str])

Does page contain expected list

locator element locator

${res}Does Page Contain Listclass:selections

method does_page_contain_radio_button

does_page_contain_radio_button(locator: Union[WebElement, ShadowRoot, str])

Does page contain expected radio button

locator element locator

${res}Does Page Contain Radio Buttonmale

method does_page_contain_textfield

does_page_contain_textfield(locator: Union[WebElement, ShadowRoot, str])

Does page contain expected textfield

locator element locator

${res}Does Page Contain Textfieldid:address

method does_table_cell_contain

does_table_cell_contain(locator: Union[WebElement, ShadowRoot, str], row: int, column: int, expected: str)

Does table cell contain expected text

locator element locator for the table

row row index starting from 1 (beginning) or -1 (from the end)

column column index starting from 1 (beginning) or -1 (from the end)

expected expected text in table row

${res}Does Table Cell Contain//table11Company

method does_table_column_contain

does_table_column_contain(locator: Union[WebElement, ShadowRoot, str], column: int, expected: str)

Does table column contain expected text

locator element locator for the table

column column index starting from 1 (beginning) or -1 (from the end)

expected expected text in table column

${res}Does Table Column Contain//table1Nokia

method does_table_contain

does_table_contain(locator: Union[WebElement, ShadowRoot, str], expected: str)

Does table contain expected text

locator element locator

expected expected text in table

${res}Does Table Contain//tableFebruary

method does_table_footer_contain

does_table_footer_contain(locator: Union[WebElement, ShadowRoot, str], expected: str)

Does table footer contain expected text

locator element locator for the table

expected expected text in table footer

${res}Does Table Footer Contain//tableSum

method does_table_header_contain

does_table_header_contain(locator: Union[WebElement, ShadowRoot, str], expected: str)

Does table header contain expected text

locator element locator for the table

expected expected text in table header

${res}Does Table Header Contain//tableMonth

method does_table_row_contain

does_table_row_contain(locator: Union[WebElement, ShadowRoot, str], row: int, expected: str)

Does table row contain expected text

locator element locator for the table

row row index starting from 1 (beginning) or -1 (from the end)

expected expected text in table row

${res}Does Table Row Contain//table1Company

method does_textarea_contain

does_textarea_contain(locator: Union[WebElement, ShadowRoot, str], expected: str)

Does textarea contain expected text

locator element locator

expected expected text in textarea

${res}Does Textarea Contain//textareasincerely

method does_textfield_contain

does_textfield_contain(locator: Union[WebElement, ShadowRoot, str], expected: str)

Does textfield contain expected text

locator element locator

expected expected text in textfield

${res}Does Textfield Containid:lnameLast

method double_click_element

double_click_element(locator: Union[WebElement, str])

Double clicks the element identified by locator.

See the Locating elements section for details about the locator syntax.


method drag_and_drop

drag_and_drop(locator: Union[WebElement, str], target: Union[WebElement, str])

Drags the element identified by locator into the target element.

The locator argument is the locator of the dragged element and the target is the locator of the target. See the Locating elements section for details about the locator syntax.

Drag And Dropcss:div#elementcss:div.target

method drag_and_drop_by_offset

drag_and_drop_by_offset(locator: Union[WebElement, str], xoffset: int, yoffset: int)

Drags the element identified with locator by xoffset/yoffset.

See the Locating elements section for details about the locator syntax.

The element will be moved by xoffset and yoffset, each of which is a negative or positive number specifying the offset.

Drag And Drop By OffsetmyElem50-35# Move myElem 50px right and 35px down

property driver : WebDriver

property driver : WebDriver

Current active driver.

  • Return type: selenium.webdriver.remote.webdriver.WebDriver :raises SeleniumLibrary.errors.NoOpenBrowser: If browser is not open.

method element_attribute_value_should_be

element_attribute_value_should_be(locator: Union[WebElement, str], attribute: str, expected: Union[None, str], message: Optional[str] = None)

Verifies element identified by locator contains expected attribute value.

See the Locating elements section for details about the locator syntax.

New in SeleniumLibrary 3.2.


method element_should_be_disabled

element_should_be_disabled(locator: Union[WebElement, str])

Verifies that element identified by locator is disabled.

This keyword considers also elements that are read-only to be disabled.

See the Locating elements section for details about the locator syntax.


method element_should_be_enabled

element_should_be_enabled(locator: Union[WebElement, str])

Verifies that element identified by locator is enabled.

This keyword considers also elements that are read-only to be disabled.

See the Locating elements section for details about the locator syntax.


method element_should_be_focused

element_should_be_focused(locator: Union[WebElement, str])

Verifies that element identified by locator is focused.

See the Locating elements section for details about the locator syntax.

New in SeleniumLibrary 3.0.


method element_should_be_visible

element_should_be_visible(locator: Union[WebElement, str], message: Optional[str] = None)

Verifies that the element identified by locator is visible.

Herein, visible means that the element is logically visible, not optically visible in the current browser viewport. For example, an element that carries display:none is not logically visible, so using this keyword on that element would fail.

See the Locating elements section for details about the locator syntax.

The message argument can be used to override the default error message.


method element_should_contain

element_should_contain(locator: Union[WebElement, str], expected: Union[None, str], message: Optional[str] = None, ignore_case: bool = False)

Verifies that element locator contains text expected.

See the Locating elements section for details about the locator syntax.

The message argument can be used to override the default error message.

The ignore_case argument can be set to True to compare case insensitive, default is False. New in SeleniumLibrary 3.1.

ignore_case argument is new in SeleniumLibrary 3.1.

Use Element Text Should Be if you want to match the exact text, not a substring.


method element_should_not_be_visible

element_should_not_be_visible(locator: Union[WebElement, str], message: Optional[str] = None)

Verifies that the element identified by locator is NOT visible.

Passes if the element does not exists. See Element Should Be Visible for more information about visibility and supported arguments.


method element_should_not_contain

element_should_not_contain(locator: Union[WebElement, str], expected: Union[None, str], message: Optional[str] = None, ignore_case: bool = False)

Verifies that element locator does not contain text expected.

See the Locating elements section for details about the locator syntax.

The message argument can be used to override the default error message.

The ignore_case argument can be set to True to compare case insensitive, default is False.

ignore_case argument new in SeleniumLibrary 3.1.


method element_text_should_be

element_text_should_be(locator: Union[WebElement, str], expected: Union[None, str], message: Optional[str] = None, ignore_case: bool = False)

Verifies that element locator contains exact the text expected.

See the Locating elements section for details about the locator syntax.

The message argument can be used to override the default error message.

The ignore_case argument can be set to True to compare case insensitive, default is False.

ignore_case argument is new in SeleniumLibrary 3.1.

Use Element Should Contain if a substring match is desired.


method element_text_should_not_be

element_text_should_not_be(locator: Union[WebElement, str], not_expected: Union[None, str], message: Optional[str] = None, ignore_case: bool = False)

Verifies that element locator does not contain exact the text not_expected.

See the Locating elements section for details about the locator syntax.

The message argument can be used to override the default error message.

The ignore_case argument can be set to True to compare case insensitive, default is False.

New in SeleniumLibrary 3.1.1


method execute_async_javascript

execute_async_javascript(*code: Any)

Executes asynchronous JavaScript code with possible arguments.

Similar to Execute Javascript except that scripts executed with this keyword must explicitly signal they are finished by invoking the provided callback. This callback is always injected into the executed function as the last argument.

Scripts must complete within the script timeout or this keyword will fail. See the Timeout section for more information.

Starting from SeleniumLibrary 3.2 it is possible to provide JavaScript arguments as part of code argument. See Execute Javascript for more details.

Execute Async JavaScriptvar callback = arguments[arguments.length - 1]; window.setTimeout(callback, 2000);
Execute Async JavaScript${CURDIR}/async_js_to_execute.js
${result} =Execute Async JavaScript
var callback = arguments[arguments.length - 1];
function answer(){callback(“text”);};
window.setTimeout(answer, 2000);
Should Be Equal${result}text

method execute_cdp

execute_cdp(command, parameters)

Executes Chromium DevTools Protocol commands

Works only with Chromium-based browsers!

For more information, available commands and parameters, see: https://chromedevtools.github.io/devtools-protocol/

command command to execute as string

parameters parameters for command as a dictionary

Open Chrome Browserabout:blankheadless=${True}
&{params}Create DictionaryuserAgent=Chrome/83.0.4103.53
Execute CDPNetwork.setUserAgentOverride${params}
Go Tohttps://robocorp.com

method execute_javascript

execute_javascript(*code: Any)

Executes the given JavaScript code with possible arguments.

code may be divided into multiple cells in the test data and code may contain multiple lines of code and arguments. In that case, the JavaScript code parts are concatenated together without adding spaces and optional arguments are separated from code.

If code is a path to an existing file, the JavaScript to execute will be read from that file. Forward slashes work as a path separator on all operating systems.

The JavaScript executes in the context of the currently selected frame or window as the body of an anonymous function. Use window to refer to the window of your application and document to refer to the document object of the current frame or window, e.g. document.getElementById('example').

This keyword returns whatever the executed JavaScript code returns. Return values are converted to the appropriate Python types.

Starting from SeleniumLibrary 3.2 it is possible to provide JavaScript arguments as part of code argument. The JavaScript code and arguments must be separated with JAVASCRIPT and ARGUMENTS markers and must be used exactly with this format. If the Javascript code is first, then the JAVASCRIPT marker is optional. The order of JAVASCRIPT and ARGUMENTS markers can be swapped, but if ARGUMENTS is the first marker, then JAVASCRIPT marker is mandatory. It is only allowed to use JAVASCRIPT and ARGUMENTS markers only one time in the code argument.

Execute JavaScriptwindow.myFunc(‘arg1’, ‘arg2’)
Execute JavaScript${CURDIR}/js_to_execute.js
Execute JavaScriptalert(arguments[0]);ARGUMENTS123
Execute JavaScriptARGUMENTS123JAVASCRIPTalert(arguments[0]);

method failure_occurred

failure_occurred()

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.


method find_element

find_element(locator: str, parent: Optional[WebElement] = None)

Find element matching locator.

  • Parameters: locator – Locator to use when searching the element. See library documentation for the supported locator syntax. :type locator: str or selenium.webdriver.remote.webelement.WebElement :param parent: Optional parent WebElememt to search child elements from. By default, search starts from the root using WebDriver. :type parent: selenium.webdriver.remote.webelement.WebElement :return: Found WebElement. :rtype: selenium.webdriver.remote.webelement.WebElement :raises SeleniumLibrary.errors.ElementNotFound: If element not found.

method find_elements

find_elements(locator: str, parent: Optional[WebElement] = None)

Find all elements matching locator.

  • Parameters: locator – Locator to use when searching the element. See library documentation for the supported locator syntax. :type locator: str or selenium.webdriver.remote.webelement.WebElement :param parent: Optional parent WebElememt to search child elements from. By default, search starts from the root using WebDriver. :type parent: selenium.webdriver.remote.webelement.WebElement :return: list of found WebElement or e,mpty if elements are not found. :rtype: list[selenium.webdriver.remote.webelement.WebElement]

method frame_should_contain

frame_should_contain(locator: Union[WebElement, str], text: str, loglevel: str = 'TRACE')

Verifies that frame identified by locator contains text.

See the Locating elements section for details about the locator syntax.

See Page Should Contain for an explanation about the loglevel argument.


method get_action_chain_delay

get_action_chain_delay()

Gets the currently stored value for chain_delay_value in timestr format.


get_all_links()

Returns a list containing ids of all links found in current page.

If a link has no id, an empty string will be in the list instead.


method get_browser_aliases

get_browser_aliases()

Returns aliases of all active browser that has an alias as NormalizedDict. The dictionary contains the aliases as keys and the index as value. This can be accessed as dictionary ${aliases.key} or as list @{aliases}[0].

Open Browserhttps://example.comalias=BrowserA
Open Browserhttps://example.comalias=BrowserB
&{aliases}Get Browser Aliases# &{aliases} = { BrowserA=1
Log${aliases.BrowserA}# logs 1
FOR${alias}LogIN${alias}@{aliases}# logs BrowserA and BrowserB
END

See Switch Browser for more information and examples.

New in SeleniumLibrary 4.0


method get_browser_capabilities

get_browser_capabilities()

Get dictionary of browser properties

${caps}=Get Browser Capabilities

method get_browser_ids

get_browser_ids()

Returns index of all active browser as list.

@{browser_ids}=Get Browser Ids
FOR${id}@{window_titles}=LogINGet Window TitlesBrowser ${id} has these windows: ${window_titles}@{browser_ids}browser=${id}
END

See Switch Browser for more information and examples.

New in SeleniumLibrary 4.0


method get_cookie

get_cookie(name: str)

Returns information of cookie with name as an object.

If no cookie is found with name, keyword fails. The cookie object contains details about the cookie. Attributes available in the object are documented in the table below.

AttributeExplanation
nameThe name of a cookie.
valueValue of the cookie.
pathIndicates a URL path, for example /.
domainThe domain, the cookie is visible to.
secureWhen true, the cookie is only used with HTTPS connections.
httpOnlyWhen true, the cookie is not accessible via JavaScript.
expiryPython datetime object indicating when the cookie expires.
extraPossible attributes outside of the WebDriver specification

See the WebDriver specification for details about the cookie information. Notice that expiry is specified as a datetime object, not as seconds since Unix Epoch like WebDriver natively does.

In some cases, example when running a browser in the cloud, it is possible that the cookie contains other attributes than is defined in the WebDriver specification. These other attributes are available in an extra attribute in the cookie object and it contains a dictionary of the other attributes. The extra attribute is new in SeleniumLibrary 4.0.

Add Cookiefoobar
${cookie} =Get Cookiefoo
Should Be Equal${cookie.name}foo
Should Be Equal${cookie.value}bar
Should Be True${cookie.expiry.year} > 2017

New in SeleniumLibrary 3.0.


method get_cookies

get_cookies(as_dict: bool = False)

Returns all cookies of the current page.

If as_dict argument evaluates as false, see Boolean arguments for more details, then cookie information is returned as a single string in format name1=value1; name2=value2; name3=value3. When as_dict argument evaluates as true, cookie information is returned as Robot Framework dictionary format. The string format can be used, for example, for logging purposes or in headers when sending HTTP requests. The dictionary format is helpful when the result can be passed to requests library’s Create Session keyword’s optional cookies parameter.

The `` as_dict`` argument is new in SeleniumLibrary 3.3


method get_element_attribute

get_element_attribute(locator: Union[WebElement, str], attribute: str)

Returns the value of attribute from the element locator.

See the Locating elements section for details about the locator syntax.

${id}=Get Element Attributecss:h1id

Passing attribute name as part of the locator was removed in SeleniumLibrary 3.2. The explicit attribute argument should be used instead.


method get_element_count

get_element_count(locator: Union[WebElement, str])

Returns the number of elements matching locator.

If you wish to assert the number of matching elements, use Page Should Contain Element with limit argument. Keyword will always return an integer.

${count} =Get Element Countname:div_name
Should Be True${count} > 2

New in SeleniumLibrary 3.0.


method get_element_size

get_element_size(locator: Union[WebElement, str])

Returns width and height of the element identified by locator.

See the Locating elements section for details about the locator syntax.

Both width and height are returned as integers.

${width}${height} =Get Element Sizecss:div#container

method get_element_status

get_element_status(locator: Union[WebElement, ShadowRoot, str])

Return dictionary containing element status of:

  • visible
  • enabled
  • disabled
  • focused

locator element locator

&{res}Get Element Statusclass:special
Log${res.visible}
Log${res.enabled}
Log${res.disabled}
Log${res.focused}

method get_horizontal_position

get_horizontal_position(locator: Union[WebElement, str])

Returns the horizontal position of the element identified by locator.

See the Locating elements section for details about the locator syntax.

The position is returned in pixels off the left side of the page, as an integer.

See also Get Vertical Position.


method get_keyword_arguments

get_keyword_arguments(name)

method get_keyword_documentation

get_keyword_documentation(name: str)

method get_keyword_names

get_keyword_names()

method get_keyword_source

get_keyword_source(keyword_name)

method get_keyword_tags

get_keyword_tags(name: str)

method get_keyword_types

get_keyword_types(name)

method get_list_items

get_list_items(locator: Union[WebElement, str], values: bool = False)

Returns all labels or values of selection list locator.

See the Locating elements section for details about the locator syntax.

Returns visible labels by default, but values can be returned by setting the values argument to a true value (see Boolean arguments).

${labels} =Get List Itemsmylist
${values} =Get List Itemscss:#example selectvalues=True

Support to return values is new in SeleniumLibrary 3.0.


method get_location

get_location()

Returns the current browser window URL.


method get_locations

get_locations(browser: str = 'CURRENT')

Returns and logs URLs of all windows of the selected browser.

Browser Scope:

The browser argument specifies the browser that shall return its windows information.

  • browser can be index_or_alias like in Switch Browser.
  • If browser is CURRENT (default, case-insensitive) the currently active browser is selected.
  • If browser is ALL (case-insensitive) the window information of all windows of all opened browsers are returned.

method get_selected_list_label

get_selected_list_label(locator: Union[WebElement, str])

Returns the label of selected option from selection list locator.

If there are multiple selected options, the label of the first option is returned.

See the Locating elements section for details about the locator syntax.


method get_selected_list_labels

get_selected_list_labels(locator: Union[WebElement, str])

Returns labels of selected options from selection list locator.

Starting from SeleniumLibrary 3.0, returns an empty list if there are no selections. In earlier versions, this caused an error.

See the Locating elements section for details about the locator syntax.


method get_selected_list_value

get_selected_list_value(locator: Union[WebElement, str])

Returns the value of selected option from selection list locator.

If there are multiple selected options, the value of the first option is returned.

See the Locating elements section for details about the locator syntax.


method get_selected_list_values

get_selected_list_values(locator: Union[WebElement, str])

Returns values of selected options from selection list locator.

Starting from SeleniumLibrary 3.0, returns an empty list if there are no selections. In earlier versions, this caused an error.

See the Locating elements section for details about the locator syntax.


method get_selenium_implicit_wait

get_selenium_implicit_wait()

Gets the implicit wait value used by Selenium.

The value is returned as a human-readable string like 1 second.

See the Implicit wait section above for more information.


method get_selenium_page_load_timeout

get_selenium_page_load_timeout()

Gets the time to wait for a page load to complete before raising a timeout exception.

The value is returned as a human-readable string like 1 second.

See the Page load section above for more information.

New in SeleniumLibrary 6.1


method get_selenium_speed

get_selenium_speed()

Gets the delay that is waited after each Selenium command.

The value is returned as a human-readable string like 1 second.

See the Selenium Speed section above for more information.


method get_selenium_timeout

get_selenium_timeout()

Gets the timeout that is used by various keywords.

The value is returned as a human-readable string like 1 second.

See the Timeout section above for more information.


method get_session_id

get_session_id()

Returns the currently active browser session id.

New in SeleniumLibrary 3.2


method get_source

get_source()

Returns the entire HTML source of the current page or frame.


method get_table_cell

get_table_cell(locator: Union[WebElement, None, str], row: int, column: int, loglevel: str = 'TRACE')

Returns contents of a table cell.

The table is located using the locator argument and its cell found using row and column. See the Locating elements section for details about the locator syntax.

Both row and column indexes start from 1, and header and footer rows are included in the count. It is possible to refer to rows and columns from the end by using negative indexes so that -1 is the last row/column, -2 is the second last, and so on.

All <th> and <td> elements anywhere in the table are considered to be cells.

See Page Should Contain for an explanation about the loglevel argument.


method get_testability_status

get_testability_status()

Get SeleniumTestability plugin status


method get_text

get_text(locator: Union[WebElement, str])

Returns the text value of the element identified by locator.

See the Locating elements section for details about the locator syntax.


method get_title

get_title()

Returns the title of the current page.


method get_value

get_value(locator: Union[WebElement, str])

Returns the value attribute of the element identified by locator.

See the Locating elements section for details about the locator syntax.


method get_vertical_position

get_vertical_position(locator: Union[WebElement, str])

Returns the vertical position of the element identified by locator.

See the Locating elements section for details about the locator syntax.

The position is returned in pixels off the top of the page, as an integer.

See also Get Horizontal Position.


method get_webelement

get_webelement(locator: Union[WebElement, ShadowRoot, str], parent: Optional[Union[WebElement, ShadowRoot]] = None, shadow: bool = False)

Returns the first Element matching the given locator.

With the parent parameter you can optionally specify a parent to start the search from. Set shadow to True if you’re targeting and expecting a shadow root in return. Read more on the shadow root: https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot

See the Locating elements section for details about the locator syntax.


method get_webelements

get_webelements(locator: Union[WebElement, str])

Returns a list of WebElement objects matching the locator.

See the Locating elements section for details about the locator syntax.

Starting from SeleniumLibrary 3.0, the keyword returns an empty list if there are no matching elements. In previous releases, the keyword failed in this case.


method get_window_handles

get_window_handles(browser: str = 'CURRENT')

Returns all child window handles of the selected browser as a list.

Can be used as a list of windows to exclude with Select Window.

How to select the browser scope of this keyword, see Get Locations.

Prior to SeleniumLibrary 3.0, this keyword was named List Windows.


method get_window_identifiers

get_window_identifiers(browser: str = 'CURRENT')

Returns and logs id attributes of all windows of the selected browser.

How to select the browser scope of this keyword, see Get Locations.


method get_window_names

get_window_names(browser: str = 'CURRENT')

Returns and logs names of all windows of the selected browser.

How to select the browser scope of this keyword, see Get Locations.


method get_window_position

get_window_position()

Returns current window position.

The position is relative to the top left corner of the screen. Returned values are integers. See also Set Window Position.

${x}${y}=Get Window Position

method get_window_size

get_window_size(inner: bool = False)

Returns current window width and height as integers.

See also Set Window Size.

If inner parameter is set to True, keyword returns HTML DOM window.innerWidth and window.innerHeight properties. See Boolean arguments for more details on how to set boolean arguments. The inner is new in SeleniumLibrary 4.0.

${width}${height}=Get Window Size
${width}${height}=Get Window SizeTrue

method get_window_titles

get_window_titles(browser: str = 'CURRENT')

Returns and logs titles of all windows of the selected browser.

How to select the browser scope of this keyword, see Get Locations.


method go_back

go_back()

Simulates the user clicking the back button on their browser.


method go_to

go_to(url: str)

Navigates the current browser window to the provided url.


method handle_alert

handle_alert(action: str = 'ACCEPT', timeout: Optional[timedelta] = None)

Handles the current alert and returns its message.

By default, the alert is accepted, but this can be controlled with the action argument that supports the following case-insensitive values:

  • ACCEPT: Accept the alert i.e. press Ok. Default.
  • DISMISS: Dismiss the alert i.e. press Cancel.
  • LEAVE: Leave the alert open.

The timeout argument specifies how long to wait for the alert to appear. If it is not given, the global default timeout is used instead.

Handle Alert# Accept alert.
Handle Alertaction=DISMISS# Dismiss alert.
Handle Alerttimeout=10 s# Use custom timeout and accept alert.
Handle AlertDISMISS1 min# Use custom timeout and dismiss alert.
${message} =Handle Alert# Accept alert and get its message.
${message} =Handle AlertLEAVE# Leave alert open and get its message.

New in SeleniumLibrary 3.0.


method highlight_elements

highlight_elements(locator: Union[WebElement, ShadowRoot, str], width: str = '2px', style: str = 'dotted', color: str = 'blue')

Highlight all matching elements by locator.

Highlighting is done by adding a colored outline around the elements with CSS styling.

locator element locator width highlight outline width style highlight outline style color highlight outline color

Highlight Elementsxpath://h2

method input_password

input_password(locator: Union[WebElement, str], password: str, clear: bool = True)

Types the given password into the text field identified by locator.

See the Locating elements section for details about the locator syntax. See Input Text for clear argument details.

Difference compared to Input Text is that this keyword does not log the given password on the INFO level. Notice that if you use the keyword like

Input Passwordpassword_fieldpassword

the password is shown as a normal keyword argument. A way to avoid that is using variables like

Input Passwordpassword_field${PASSWORD}

Please notice that Robot Framework logs all arguments using the TRACE level and tests must not be executed using level below DEBUG if the password should not be logged in any format.

The clear argument is new in SeleniumLibrary 4.0. Hiding password logging from Selenium logs is new in SeleniumLibrary 4.2.


method input_text

input_text(locator: Union[WebElement, str], text: str, clear: bool = True)

Types the given text into the text field identified by locator.

When clear is true, the input element is cleared before the text is typed into the element. When false, the previous text is not cleared from the element. Use Input Password if you do not want the given text to be logged.

If Selenium Grid is used and the text argument points to a file in the file system, then this keyword prevents the Selenium to transfer the file to the Selenium Grid hub. Instead, this keyword will send the text string as is to the element. If a file should be transferred to the hub and upload should be performed, please use Choose File keyword.

See the Locating elements section for details about the locator syntax. See the Boolean arguments section how Boolean values are handled.

Disabling the file upload the Selenium Grid node and the clear argument are new in SeleniumLibrary 4.0


method input_text_into_alert

input_text_into_alert(text: str, action: str = 'ACCEPT', timeout: Optional[timedelta] = None)

Types the given text into an input field in an alert.

The alert is accepted by default, but that behavior can be controlled by using the action argument same way as with Handle Alert.

timeout specifies how long to wait for the alert to appear. If it is not given, the global default timeout is used instead.

New in SeleniumLibrary 3.0.


method input_text_when_element_is_visible

input_text_when_element_is_visible(locator: Union[WebElement, ShadowRoot, str], text: str)

Input text into locator after it has become visible.

locator element locator

text insert text to locator

Input Text When Element Is Visible//input[@id=”freetext”]my feedback

method is_alert_present

is_alert_present(text: Optional[str] = None, action: str = 'ACCEPT')

Is alert box present, which can be identified with text and action can also be done which by default is ACCEPT.

Other possible actions are DISMISS and LEAVE.

text check if alert text is matching to this, if None will check if alert is present at all

action possible action if alert is present, default ACCEPT

${res}Is Alert Presentalert message

method is_checkbox_selected

is_checkbox_selected(locator: Union[WebElement, ShadowRoot, str])

Is checkbox selected

locator element locator

${res}Is Checkbox Selectedid:taxes-paid

property is_chromium : bool

property is_chromium : bool

method is_element_attribute_equal_to

is_element_attribute_equal_to(locator: Union[WebElement, ShadowRoot, str], attribute: str, expected: str)

Is element attribute equal to expected value

locator element locator

attribute element attribute to check for

expected is attribute value equal to this

${res}Is Element Attribute Equal Toh1idmain

method is_element_disabled

is_element_disabled(locator: Union[WebElement, ShadowRoot, str], missing_ok: bool = True)

Is element disabled

locator element locator missing_ok default True, set to False if keyword should Fail if element does not exist

${res}Is Element Disabled//input[@type=”submit”]

method is_element_enabled

is_element_enabled(locator: Union[WebElement, ShadowRoot, str], missing_ok: bool = True)

Is element enabled

locator element locator missing_ok default True, set to False if keyword should Fail if element does not exist

${res}Is Element Enabledinput.field1

method is_element_focused

is_element_focused(locator: Union[WebElement, ShadowRoot, str], missing_ok: bool = True)

Is element focused

locator element locator missing_ok default True, set to False if keyword should Fail if element does not exist

${res}Is Element Focused//input[@id=”freetext”]

method is_element_text

is_element_text(locator: Union[WebElement, ShadowRoot, str], expected: str, ignore_case: bool = False)

Is element text expected

locator element locator

expected expected element text

ignore_case should check be case insensitive, default False

${res}Is Element Textid:namejohn doe
${res}Is Element Textid:namejohn doeignore_case=True

method is_element_visible

is_element_visible(locator: Union[WebElement, ShadowRoot, str], missing_ok: bool = True)

Is element visible

locator element locator missing_ok default True, set to False if keyword should Fail if element does not exist

${res}Is Element Visibleid:confirmation

method is_list_selected

is_list_selected(locator: Union[WebElement, ShadowRoot, str])

Is any option selected in the

locator element locator

${res}Is List Selectedid:cars

method is_list_selection

is_list_selection(locator: Union[WebElement, ShadowRoot, str], *expected: str)

Is list selected with expected values

locator element locator

expected expected selected options

${res}Is List Selectionid:carsFord

method is_location

is_location(url: str)

Is current URL expected url

url expected current URL

Open Available Browserhttps://www.robocorp.com
${res}Is Locationhttps://www.robocorp.com

method is_radio_button_selected

is_radio_button_selected(group_name: str)

Is any radio button selected in the button group

group_name radio button group name

${res}Is Radio Button Selectedgroup_name=gender

method is_radio_button_set_to

is_radio_button_set_to(group_name: str, value: str)

Is radio button group set to expected value

group_name radio button group name

value expected value

${res}Is Radio Button Set Togroup_name=gendervalue=female

method is_textarea_value

is_textarea_value(locator: Union[WebElement, ShadowRoot, str], expected: str)

Is textarea matching expected value

locator element locator

expected expected textarea value

${res}Is Textarea Value//textareaYours sincerely

method is_textfield_value

is_textfield_value(locator: Union[WebElement, ShadowRoot, str], expected: str)

Is textfield value expected

locator element locator

expected expected textfield value

${res}Is Textfield Valueid:lnameLastname

method is_title

is_title(title: str)

Is page title expected

title expected title value

${res}Is TitleWebpage title text

method list_selection_should_be

list_selection_should_be(locator: Union[WebElement, str], *expected: str)

Verifies selection list locator has expected options selected.

It is possible to give expected options both as visible labels and as values. Starting from SeleniumLibrary 3.0, mixing labels and values is not possible. Order of the selected options is not validated.

If no expected options are given, validates that the list has no selections. A more explicit alternative is using List Should Have No Selections.

See the Locating elements section for details about the locator syntax.

List Selection Should BegenderFemale
List Selection Should BeinterestsTest AutomationPython

method list_should_have_no_selections

list_should_have_no_selections(locator: Union[WebElement, str])

Verifies selection list locator has no options selected.

See the Locating elements section for details about the locator syntax.


property location : str

property location : str

Return browser location.


method location_should_be

location_should_be(url: str, message: Optional[str] = None)

Verifies that the current URL is exactly url.

The url argument contains the exact url that should exist in browser.

The message argument can be used to override the default error message.

message argument is new in SeleniumLibrary 3.2.0.


method location_should_contain

location_should_contain(expected: str, message: Optional[str] = None)

Verifies that the current URL contains expected.

The expected argument contains the expected value in url.

The message argument can be used to override the default error message.

message argument is new in SeleniumLibrary 3.2.0.


method log_location

log_location()

Logs and returns the current browser window URL.


method log_source

log_source(loglevel: str = 'INFO')

Logs and returns the HTML source of the current page or frame.

The loglevel argument defines the used log level. Valid log levels are WARN, INFO (default), DEBUG, TRACE and NONE (no logging).


method log_title

log_title()

Logs and returns the title of the current page.


method maximize_browser_window

maximize_browser_window(*args, force: bool = False, **kwargs)

Maximizes current browser window.

The window won’t be maximized in headless mode since there’s no way to know the screen size to set the window size to in the absence of an UI. Use the Set Window Size keyword with a specific side or set the force param to True if you still want to enforce this undefined behaviour.


method mouse_down

mouse_down(locator: Union[WebElement, str])

Simulates pressing the left mouse button on the element locator.

See the Locating elements section for details about the locator syntax.

The element is pressed without releasing the mouse button.

See also the more specific keywords Mouse Down On Image and Mouse Down On Link.


method mouse_down_on_image

mouse_down_on_image(locator: Union[WebElement, str])

Simulates a mouse down event on an image identified by locator.

See the Locating elements section for details about the locator syntax. When using the default locator strategy, images are searched using id, name, src and alt.


mouse_down_on_link(locator: Union[WebElement, str])

Simulates a mouse down event on a link identified by locator.

See the Locating elements section for details about the locator syntax. When using the default locator strategy, links are searched using id, name, href and the link text.


method mouse_out

mouse_out(locator: Union[WebElement, str])

Simulates moving the mouse away from the element locator.

See the Locating elements section for details about the locator syntax.


method mouse_over

mouse_over(locator: Union[WebElement, str])

Simulates hovering the mouse over the element locator.

See the Locating elements section for details about the locator syntax.


method mouse_up

mouse_up(locator: Union[WebElement, str])

Simulates releasing the left mouse button on the element locator.

See the Locating elements section for details about the locator syntax.


method normalize_options

normalize_options(options: Optional[Union[ArgOptions, str, Dict[str, Union[str, List, Dict]]]], *, browser: str)

Normalize provided options to a Options instance.


method open_available_browser

open_available_browser(url: Optional[str] = None, use_profile: bool = False, headless: Union[bool, str] = 'AUTO', maximized: bool = False, browser_selection: Any = 'AUTO', alias: Optional[str] = None, profile_name: Optional[str] = None, profile_path: Optional[str] = None, preferences: Optional[dict] = None, proxy: str = None, user_agent: Optional[str] = None, download: Any = 'AUTO', options: Optional[Union[ArgOptions, str, Dict[str, Union[str, List, Dict]]]] = None, port: Optional[int] = None)

Attempts to open a browser on the user’s device from a set of supported browsers. Automatically downloads a corresponding webdriver if none is already installed.

Currently supported browsers: Chrome, Firefox, Edge, ChromiumEdge, Safari, Ie

Optionally can be given a url as the first argument, to open the browser directly to the given page.

Returns either a generated index or a custom alias for the browser instance. The returned value can be used to refer to that specific browser instance in other keywords.

If the browser should start in a maximized window, this can be enabled with the argument maximized, but is disabled by default.

For certain applications it might also be required to force a certain user-agent string for Selenium, which can be overridden with the user_agent argument.

WebDriver creation can be customized with options. This accepts a class instance (e.g. ChromeOptions), a string like add_argument(“–incognito”);set_capability(“acceptInsecureCerts”, True) or even a simple dictionary like: {“arguments”: [“–incognito”], “capabilities”: {“acceptInsecureCerts”: True}}

A custom port can be provided to start the browser webdriver without a randomly picked one. Make sure you provide every time a unique system-available local port if you plan to have multiple browsers being controlled in parallel.

For incompatible web apps designed to work in Internet Explorer only, Edge can run in IE mode by simply setting ie in the browser_selection param. Robot example: https://github.com/robocorp/example-ie-mode-edge

Open Available Browserhttps://www.robocorp.com
${index}=Open Available Browser${URL}browser_selection=opera,firefox
Open Available Browser${URL}headless=${True}alias=HeadlessBrowser
Open Available Browser${URL}options=add_argument(“user-data-dir=path/to/data”);add_argument(“–incognito”)
Open Available Browser${URL}port=${8888}

Browser order

The default order of supported browsers is based on the operating system and is as follows:

PlatformDefault order
WindowsChrome, Firefox, Edge
LinuxChrome, Firefox, Edge
DarwinChrome, Firefox, Edge, Safari

The order can be overridden with a custom list by using the argument browser_selection. The argument can be either a comma-separated string or a list object.

Open Available Browser${URL}browser_selection=ie

Webdriver download

The library can (if requested) automatically download webdrivers for all the supported browsers. This can be controlled with the argument download.

If the value is False, it will only attempt to start webdrivers found from the system PATH.

If the value is True, it will download a webdriver that matches the current browser.

By default the argument has the value AUTO, which means it first attempts to use webdrivers found in PATH and if that fails forces a webdriver download.

Opening process

  • Parse list of preferred browser order. If not given, use values from above table.

  • Loop through listed browsers:

  • Set the webdriver options for the browser.

  • Download webdriver (if requested).

  • Attempt to launch the webdriver and stop the loop if successful.

  • Return index/alias if webdriver was created, or raise an exception if no browsers were successfully opened.

Headless mode

If required, the browser can also run headless, which means that it does not create a visible window. Generally a headless browser is slightly faster, but might not support all features a normal browser does.

One typical use-case for headless mode is in cloud containers, where there is no display available. It also prevents manual interaction with the browser, which can be either a benefit or a drawback depending on the context.

It can be explicitly enabled or disabled with the argument headless. By default, it will be disabled, unless it detects that it is running in a Linux environment without a display, e.g. a container or if the RPA_HEADLESS_MODE env var is set to a number different than 0.

Chromium options

Some features are currently available only for Chromium-based browsers. This includes using an existing user profile. By default Selenium uses a new profile for each session, but it can use an existing one by enabling the use_profile argument.

If a custom profile is stored somewhere outside of the default location, the path to the profiles directory and the name of the profile can be controlled with profile_path and profile_name respectively. Keep in mind that the profile_path for the Chrome browser for e.g. ends usually with “Chrome”, “User Data” or “google-chrome” (based on platform) and the profile_name is a directory relative to profile_path, usually named “Profile 1”, “Profile 2” etc. (and not as your visible name in the Chrome browser). Similar behavior is observed with Edge as well.

Open Available Browserhttps://www.robocorp.comuse_profile=${True}
Open Available Browserhttps://www.robocorp.comuse_profile=${True}profile_name=Default
Open Available Browserhttps://www.robocorp.comuse_profile=${True}profile_name=Profile 2
Open Available Browserhttps://www.robocorp.comuse_profile=${True}profile_name=Profile 1profile_path=path/to/custom/user_data_dir

Profile preferences can be further overridden with the preferences argument by giving a dictionary of key/value pairs.

Chromium-based browsers can additionally connect through a proxy, which should be given as either a local or remote address.


method open_browser

open_browser(url: Optional[str] = None, browser: str = 'firefox', alias: Optional[str] = None, remote_url: Union[bool, str] = False, desired_capabilities: Union[dict, None, str] = None, ff_profile_dir: Optional[Union[FirefoxProfile, str]] = None, options: Optional[Union[ArgOptions, str, Dict[str, Union[str, List, Dict]]]] = None, service_log_path: Optional[str] = None, executable_path: Optional[str] = None)

Opens a new browser instance to the optional url.

The browser argument specifies which browser to use. The supported browsers are listed in the table below. The browser names are case-insensitive and some browsers have multiple supported names.

BrowserName(s)
Firefoxfirefox, ff
Google Chromegooglechrome, chrome, gc
Headless Firefoxheadlessfirefox
Headless Chromeheadlesschrome
Internet Explorerinternetexplorer, ie
Edgeedge
Safarisafari

To be able to actually use one of these browsers, you need to have a matching Selenium browser driver available. See the project documentation for more details. Headless Firefox and Headless Chrome are new additions in SeleniumLibrary 3.1.0 and require Selenium 3.8.0 or newer.

After opening the browser, it is possible to use optional url to navigate the browser to the desired address.

Optional alias is an alias given for this browser instance and it can be used for switching between browsers. When same alias is given with two Open Browser keywords, the first keyword will open a new browser, but the second one will switch to the already opened browser and will not open a new browser. The alias definition overrules browser definition. When same alias is used but a different browser is defined, then switch to a browser with same alias is done and new browser is not opened. An alternative approach for switching is using an index returned by this keyword. These indices start from 1, are incremented when new browsers are opened, and reset back to 1 when Close All Browsers is called. See Switch Browser for more information and examples.

Optional remote_url is the URL for a Selenium Grid.

Optional desired_capabilities is deprecated and will be ignored. Capabilities of each individual browser is now done through options or services. Please refer to those arguments for configuring specific browsers.

Examples

Optional ff_profile_dir is the path to the Firefox profile directory if you wish to overwrite the default profile Selenium uses. Notice that prior to SeleniumLibrary 3.0, the library contained its own profile that was used by default. The ff_profile_dir can also be an instance of the selenium.webdriver.FirefoxProfile . As a third option, it is possible to use FirefoxProfile methods and attributes to define the profile using methods and attributes in the same way as with optionsoptions argument documentation in below how to handle backslash escaping.

Optional options argument allows defining browser specific Selenium options. Example for Chrome, the options argument allows defining the following methods and attributes and for Firefox these methods and attributes are available. Please note that not all browsers, supported by the SeleniumLibrary, have Selenium options available. Therefore please consult the Selenium documentation which browsers do support the Selenium options. Selenium options are also supported, when remote_url argument is used.

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

Examples

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:pathtoprofile” 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”.

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

Optional service_log_path argument defines the name of the file where to write the browser driver logs. If the service_log_path argument contain a marker {index}, it will be automatically replaced with unique running index preventing files to be overwritten. Indices start’s from 1, and how they are represented can be customized using Python’s format string syntax.

Optional executable_path argument defines the path to the driver executable, example to a chromedriver or a geckodriver. If not defined it is assumed the executable is in the $PATH.

Open Browserhttp://example.comChrome
Open Browserhttp://example.comFirefoxalias=Firefox
Open Browserhttp://example.comEdgeremote_url=http://127.0.0.1:4444/wd/hub
Open Browserabout:blank
Open Browserbrowser=Chrome

Alias examples:

${1_index} =Open Browserhttp://example.comChromealias=Chrome# Opens new browser because alias is new.
${2_index} =Open Browserhttp://example.comFirefox# Opens new browser because alias is not defined.
${3_index} =Open Browserhttp://example.comChromealias=Chrome# Switches to the browser with Chrome alias.
${4_index} =Open Browserhttp://example.comChromealias=${1_index}# Switches to the browser with Chrome alias.
Should Be Equal${1_index}${3_index}
Should Be Equal${1_index}${4_index}
Should Be Equal${2_index}${2}

Example when using Chrome options method:

Open Browserhttp://example.comChromeoptions=add_argument(“–disable-popup-blocking”); add_argument(“–ignore-certificate-errors”)# Sting format.
${options} =Get Options# Selenium options instance.
Open Browserhttp://example.comChromeoptions=${options}
Open BrowserNoneChromeoptions=binary_location=”/path/to/binary”;add_argument(“remote-debugging-port=port”)# Start Chomium-based application.
Open BrowserNoneChromeoptions=binary_location=r”C:\path\to\binary”# Windows OS path escaping.

Example for FirefoxProfile

Open Browserhttp://example.comFirefoxff_profile_dir=/path/to/profile# Using profile from disk.
Open Browserhttp://example.comFirefoxff_profile_dir=${FirefoxProfile_instance}# Using instance of FirefoxProfile.
Open Browserhttp://example.comFirefoxff_profile_dir=set_preference(“key”, “value”);set_preference(“other”, “setting”)# Defining profile using FirefoxProfile mehtods.

If the provided configuration options are not enough, it is possible to use Create Webdriver to customize browser initialization even more.

Applying desired_capabilities argument also for local browser is new in SeleniumLibrary 3.1.

Using alias to decide, is the new browser opened is new in SeleniumLibrary 4.0. The options and service_log_path are new in SeleniumLibrary 4.0. Support for ff_profile_dir accepting an instance of the selenium.webdriver.FirefoxProfile and support defining FirefoxProfile with methods and attributes are new in SeleniumLibrary 4.0.

Making url optional is new in SeleniumLibrary 4.1.

The executable_path argument is new in SeleniumLibrary 4.2.


method open_chrome_browser

open_chrome_browser(url: str, use_profile: bool = False, headless: Union[bool, str] = 'AUTO', maximized: bool = False, alias: Optional[str] = None, profile_name: Optional[str] = None, profile_path: Optional[str] = None, preferences: Optional[dict] = None, proxy: Optional[str] = None, user_agent: Optional[str] = None)

Opens a Chrome browser.

See Open Available Browser for a full descriptions of the arguments.


method open_context_menu

open_context_menu(locator: Union[WebElement, str])

Opens the context menu on the element identified by locator.


method open_headless_chrome_browser

open_headless_chrome_browser(url: str)

Opens the Chrome browser in headless mode.

url URL to open

${idx} =Open Headless Chrome Browserhttps://www.google.com

method open_user_browser

open_user_browser(url: str, tab=True)

Opens an URL with te user’s default browser.

The browser opened with this keyword is not accessible with Selenium. To interact with the opened browser it is possible to use RPA.Desktop or RPA.Windows library keywords.

The keyword Attach Chrome Browser can be used to access an already open browser with Selenium keywords.

Read more: https://robocorp.com/docs/development-guide/browser/how-to-attach-to-running-chrome-browser

url URL to open tab defines is url is opened in a tab (defaults to True) or in new window (if set to False)

Open User Browserhttps://www.google.com?q=rpa
Open User Browserhttps://www.google.com?q=rpatab=${False}

method page_should_contain

page_should_contain(text: str, loglevel: str = 'TRACE')

Verifies that current page contains text.

If this keyword fails, it automatically logs the page source using the log level specified with the optional loglevel argument. Valid log levels are TRACE (default), DEBUG, INFO, WARN, and NONE. If the log level is NONE or below the current active log level the source will not be logged.


method page_should_contain_button

page_should_contain_button(locator: Union[WebElement, str], message: Optional[str] = None, loglevel: str = 'TRACE')

Verifies button locator is found from current page.

See Page Should Contain Element for an explanation about message and loglevel arguments.

See the Locating elements section for details about the locator syntax. When using the default locator strategy, buttons are searched using id, name, and value.


method page_should_contain_checkbox

page_should_contain_checkbox(locator: Union[WebElement, str], message: Optional[str] = None, loglevel: str = 'TRACE')

Verifies checkbox locator is found from the current page.

See Page Should Contain Element for an explanation about message and loglevel arguments.

See the Locating elements section for details about the locator syntax.


method page_should_contain_element

page_should_contain_element(locator: Union[WebElement, str], message: Optional[str] = None, loglevel: str = 'TRACE', limit: Optional[int] = None)

Verifies that element locator is found on the current page.

See the Locating elements section for details about the locator syntax.

The message argument can be used to override the default error message.

The limit argument can used to define how many elements the page should contain. When limit is None (default) page can contain one or more elements. When limit is a number, page must contain same number of elements.

See Page Should Contain for an explanation about the loglevel argument.

Examples assumes that locator matches to two elements.

Page Should Contain Elementdiv_namelimit=1# Keyword fails.
Page Should Contain Elementdiv_namelimit=2# Keyword passes.
Page Should Contain Elementdiv_namelimit=none# None is considered one or more.
Page Should Contain Elementdiv_name# Same as above.

The limit argument is new in SeleniumLibrary 3.0.


method page_should_contain_image

page_should_contain_image(locator: Union[WebElement, str], message: Optional[str] = None, loglevel: str = 'TRACE')

Verifies image identified by locator is found from current page.

See the Locating elements section for details about the locator syntax. When using the default locator strategy, images are searched using id, name, src and alt.

See Page Should Contain Element for an explanation about message and loglevel arguments.


page_should_contain_link(locator: Union[WebElement, str], message: Optional[str] = None, loglevel: str = 'TRACE')

Verifies link identified by locator is found from current page.

See the Locating elements section for details about the locator syntax. When using the default locator strategy, links are searched using id, name, href and the link text.

See Page Should Contain Element for an explanation about message and loglevel arguments.


method page_should_contain_list

page_should_contain_list(locator: Union[WebElement, str], message: Optional[str] = None, loglevel: str = 'TRACE')

Verifies selection list locator is found from current page.

See Page Should Contain Element for an explanation about message and loglevel arguments.

See the Locating elements section for details about the locator syntax.


method page_should_contain_radio_button

page_should_contain_radio_button(locator: Union[WebElement, str], message: Optional[str] = None, loglevel: str = 'TRACE')

Verifies radio button locator is found from current page.

See Page Should Contain Element for an explanation about message and loglevel arguments.

See the Locating elements section for details about the locator syntax. When using the default locator strategy, radio buttons are searched using id, name and value.


method page_should_contain_textfield

page_should_contain_textfield(locator: Union[WebElement, str], message: Optional[str] = None, loglevel: str = 'TRACE')

Verifies text field locator is found from current page.

See Page Should Contain Element for an explanation about message and loglevel arguments.

See the Locating elements section for details about the locator syntax.


method page_should_not_contain

page_should_not_contain(text: str, loglevel: str = 'TRACE')

Verifies the current page does not contain text.

See Page Should Contain for an explanation about the loglevel argument.


method page_should_not_contain_button

page_should_not_contain_button(locator: Union[WebElement, str], message: Optional[str] = None, loglevel: str = 'TRACE')

Verifies button locator is not found from current page.

See Page Should Contain Element for an explanation about message and loglevel arguments.

See the Locating elements section for details about the locator syntax. When using the default locator strategy, buttons are searched using id, name, and value.


method page_should_not_contain_checkbox

page_should_not_contain_checkbox(locator: Union[WebElement, str], message: Optional[str] = None, loglevel: str = 'TRACE')

Verifies checkbox locator is not found from the current page.

See Page Should Contain Element for an explanation about message and loglevel arguments.

See the Locating elements section for details about the locator syntax.


method page_should_not_contain_element

page_should_not_contain_element(locator: Union[WebElement, str], message: Optional[str] = None, loglevel: str = 'TRACE')

Verifies that element locator is not found on the current page.

See the Locating elements section for details about the locator syntax.

See Page Should Contain for an explanation about message and loglevel arguments.


method page_should_not_contain_image

page_should_not_contain_image(locator: Union[WebElement, str], message: Optional[str] = None, loglevel: str = 'TRACE')

Verifies image identified by locator is not found from current page.

See the Locating elements section for details about the locator syntax. When using the default locator strategy, images are searched using id, name, src and alt.

See Page Should Contain Element for an explanation about message and loglevel arguments.


page_should_not_contain_link(locator: Union[WebElement, str], message: Optional[str] = None, loglevel: str = 'TRACE')

Verifies link identified by locator is not found from current page.

See the Locating elements section for details about the locator syntax. When using the default locator strategy, links are searched using id, name, href and the link text.

See Page Should Contain Element for an explanation about message and loglevel arguments.


method page_should_not_contain_list

page_should_not_contain_list(locator: Union[WebElement, str], message: Optional[str] = None, loglevel: str = 'TRACE')

Verifies selection list locator is not found from current page.

See Page Should Contain Element for an explanation about message and loglevel arguments.

See the Locating elements section for details about the locator syntax.


method page_should_not_contain_radio_button

page_should_not_contain_radio_button(locator: Union[WebElement, str], message: Optional[str] = None, loglevel: str = 'TRACE')

Verifies radio button locator is not found from current page.

See Page Should Contain Element for an explanation about message and loglevel arguments.

See the Locating elements section for details about the locator syntax. When using the default locator strategy, radio buttons are searched using id, name and value.


method page_should_not_contain_textfield

page_should_not_contain_textfield(locator: Union[WebElement, str], message: Optional[str] = None, loglevel: str = 'TRACE')

Verifies text field locator is not found from current page.

See Page Should Contain Element for an explanation about message and loglevel arguments.

See the Locating elements section for details about the locator syntax.


method press_key

press_key(locator: Union[WebElement, str], key: str)

DEPRECATED in SeleniumLibrary 4.0. use Press Keys instead.


method press_keys

press_keys(locator: Union[WebElement, None, str] = None, *keys: str)

Simulates the user pressing key(s) to an element or on the active browser.

If locator evaluates as false, see Boolean arguments for more details, then the keys are sent to the currently active browser. Otherwise element is searched and keys are send to the element identified by the locator. In later case, keyword fails if element is not found. See the Locating elements section for details about the locator syntax.

keys arguments can contain one or many strings, but it can not be empty. keys can also be a combination of Selenium Keys and strings or a single Selenium Key. If Selenium Key is combined with strings, Selenium key and strings must be separated by the + character, like in CONTROL+c. Selenium Keys are space and case sensitive and Selenium Keys are not parsed inside of the string. Example AALTO, would send string AALTO and ALT not parsed inside of the string. But A+ALT+O would found Selenium ALT key from the keys argument. It also possible to press many Selenium Keys down at the same time, example ‘ALT+ARROW_DOWN`.

If Selenium Keys are detected in the keys argument, keyword will press the Selenium Key down, send the strings and then release the Selenium Key. If keyword needs to send a Selenium Key as a string, then each character must be separated with + character, example E+N+D.

CTRL is alias for Selenium CONTROL and ESC is alias for Selenium ESCAPE

New in SeleniumLibrary 3.3

Press Keystext_fieldAAAAA# Sends string “AAAAA” to element.
Press KeysNoneBBBBB# Sends string “BBBBB” to currently active browser.
Press Keystext_fieldE+N+D# Sends string “END” to element.
Press Keystext_fieldXXXYY# Sends strings “XXX” and “YY” to element.
Press Keystext_fieldXXX+YY# Same as above.
Press Keystext_fieldALT+ARROW_DOWN# Pressing “ALT” key down, then pressing ARROW_DOWN and then releasing both keys.
Press Keystext_fieldALTARROW_DOWN# Pressing “ALT” key and then pressing ARROW_DOWN.
Press Keystext_fieldCTRL+c# Pressing CTRL key down, sends string “c” and then releases CTRL key.
Press KeysbuttonRETURN# Pressing “ENTER” key to element.

method print_to_pdf

print_to_pdf(output_path: Optional[str] = None, params: Optional[dict] = None)

Print the current page to a PDF document using Chrome’s DevTools.

Attention: With some older browsers, this may work in headless mode only! For a list of supported parameters see: https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF Returns the output PDF file path.

Parameter output_path specifies the file path for the generated PDF document. By default, it is saved to the output folder with the default name of out.pdf. Parameter params specify parameters for the browser printing method. By default, it uses the following values: { "landscape": False, "displayHeaderFooter": False, "printBackground": True, "preferCSSPageSize": True, }


method radio_button_should_be_set_to

radio_button_should_be_set_to(group_name: str, value: str)

Verifies radio button group group_name is set to value.

group_name is the name of the radio button group.


method radio_button_should_not_be_selected

radio_button_should_not_be_selected(group_name: str)

Verifies radio button group group_name has no selection.

group_name is the name of the radio button group.


method register_driver

register_driver(driver: WebDriver, alias: str)

Add’s a driver to the library WebDriverCache.

  • Parameters: driver – Instance of the Selenium WebDriver. :type driver: selenium.webdriver.remote.webdriver.WebDriver :param alias: Alias given for this WebDriver instance. :type alias: str :return: The index of the WebDriver instance. :rtype: int

method register_keyword_to_run_on_failure

register_keyword_to_run_on_failure(keyword: Optional[str])

Sets the keyword to execute, when a SeleniumLibrary keyword fails.

keyword is the name of a keyword that will be executed if a SeleniumLibrary keyword fails. It is possible to use any available keyword, including user keywords or keywords from other libraries, but the keyword must not take any arguments.

The initial keyword to use is set when importing the library, and the keyword that is used by default is Capture Page Screenshot. Taking a screenshot when something failed is a very useful feature, but notice that it can slow down the execution.

It is possible to use string NOTHING or NONE, case-insensitively, as well as Python None to disable this feature altogether.

This keyword returns the name of the previously registered failure keyword or Python None if this functionality was previously disabled. The return value can be always used to restore the original value later.

Register Keyword To Run On FailureLog Source
${previous kw}=Register Keyword To Run On FailureNONE
Register Keyword To Run On Failure${previous kw}

Changes in SeleniumLibrary 3.0:

  • Possible to use string NONE or Python None to disable the functionality.
  • Return Python None when the functionality was disabled earlier. In previous versions special value No Keyword was returned and it could not be used to restore the original state.

method reload_page

reload_page()

Simulates user reloading page.


method remove_location_strategy

remove_location_strategy(strategy_name: str)

Removes a previously added custom location strategy.

See Custom locators for information on how to create and use custom strategies.


method run_keyword

run_keyword(name: str, args: tuple, kwargs: dict)

method screenshot

screenshot(locator: Optional[Union[WebElement, ShadowRoot, str]] = None, filename: Optional[str] = '')

Capture page and/or element screenshot.

locator if defined, take element screenshot, if not takes page screenshot

filename filename for the screenshot, by default creates file screenshot--(element|page).png if set to None then file is not saved at all

Screenshotlocator=//img[@alt=”Google”]filename=locator.png# element screenshot, defined filename
Screenshotfilename=page.png# page screenshot, defined filename
Screenshotfilename=${NONE}# page screenshot, NO file will be created
Screenshot# page screenshot, default filename
Screenshotlocator=//img[@alt=”Google”]# element screenshot, default filename
Screenshotlocator=//img[@alt=”Google”]filename=${CURDIR}/subdir/loc.png# element screenshot, create dirs if not existing

method scroll_element_into_view

scroll_element_into_view(locator: Union[WebElement, str])

Scrolls the element identified by locator into view.

See the Locating elements section for details about the locator syntax.

New in SeleniumLibrary 3.2.0


method select_all_from_list

select_all_from_list(locator: Union[WebElement, str])

Selects all options from multi-selection list locator.

See the Locating elements section for details about the locator syntax.


method select_checkbox

select_checkbox(locator: Union[WebElement, str])

Selects the checkbox identified by locator.

Does nothing if checkbox is already selected.

See the Locating elements section for details about the locator syntax.


method select_frame

select_frame(locator: Union[WebElement, str])

Sets frame identified by locator as the current frame.

See the Locating elements section for details about the locator syntax.

Works both with frames and iframes. Use Unselect Frame to cancel the frame selection and return to the main frame.

Select Frametop-frame# Select frame with id or name ‘top-frame’
Click Linkexample# Click link ‘example’ in the selected frame
Unselect Frame# Back to main frame.
Select Frame//iframe[@name=’xxx’]# Select frame using xpath

method select_from_list_by_index

select_from_list_by_index(locator: Union[WebElement, str], *indexes: str)

Selects options from selection list locator by indexes.

Indexes of list options start from 0.

If more than one option is given for a single-selection list, the last value will be selected. With multi-selection lists all specified options are selected, but possible old selections are not cleared.

See the Locating elements section for details about the locator syntax.


method select_from_list_by_label

select_from_list_by_label(locator: Union[WebElement, str], *labels: str)

Selects options from selection list locator by labels.

If more than one option is given for a single-selection list, the last value will be selected. With multi-selection lists all specified options are selected, but possible old selections are not cleared.

See the Locating elements section for details about the locator syntax.


method select_from_list_by_value

select_from_list_by_value(locator: Union[WebElement, str], *values: str)

Selects options from selection list locator by values.

If more than one option is given for a single-selection list, the last value will be selected. With multi-selection lists all specified options are selected, but possible old selections are not cleared.

See the Locating elements section for details about the locator syntax.


method select_radio_button

select_radio_button(group_name: str, value: str)

Sets the radio button group group_name to value.

The radio button to be selected is located by two arguments:

  • group_name is the name of the radio button group.
  • value is the id or value attribute of the actual radio button.

Select Radio ButtonsizeXL
Select Radio Buttoncontactemail

method set_action_chain_delay

set_action_chain_delay(value: timedelta)

Sets the duration of delay in ActionChains() used by SeleniumLibrary.

The value can be given as a number that is considered to be seconds or as a human-readable string like 1 second.

Value is always stored as milliseconds internally.

The previous value is returned and can be used to restore the original value later if needed.


method set_browser_implicit_wait

set_browser_implicit_wait(value: timedelta)

Sets the implicit wait value used by Selenium.

Same as Set Selenium Implicit Wait but only affects the current browser.


method set_default_url_scheme

set_default_url_scheme(scheme: Optional[str])

Sets the default scheme used for URLs without a defined value, such as http or https.

The feature is disabled if the value is set to None.


method set_download_directory

set_download_directory(directory: Optional[str] = None, download_pdf: bool = True)

Set a custom browser download directory.

This has to be called before opening the browser and it works with the following keywords:

  • Open Available Browser
  • Open Chrome Browser
  • Open Headless Chrome Browser

Supported browsers: Chrome, Edge, Firefox.

If the downloading doesn’t work (file is not found on disk), try using the browser in non-headless (headful) mode when opening it. (headless=${False})

Parameter directory sets a path for downloads, defaults to None, which means that this setting is removed and the default location will be used. Parameter download_pdf will download a PDF file instead of previewing it within browser’s internal viewer when this is set to True. (enabled by default)

Set Download Directory${OUTPUT_DIR}
Open Available Browserhttps://cdn.robocorp.com/legal/Robocorp-EULA-v1.0.pdf
@{files} =List Files In Directory${OUTPUT_DIR}
Log List${files}

method set_element_attribute

set_element_attribute(locator: Union[WebElement, ShadowRoot, str], attribute: str, value: str)

Sets a value for the attribute in the element locator.

See the Locating elements section for details about the locator syntax.

Set Element Attributecss:h1classactive

method set_focus_to_element

set_focus_to_element(locator: Union[WebElement, str])

Sets the focus to the element identified by locator.

See the Locating elements section for details about the locator syntax.

Prior to SeleniumLibrary 3.0 this keyword was named Focus.


method set_screenshot_directory

set_screenshot_directory(path: Union[None, str])

Sets the directory for captured screenshots.

path argument specifies the absolute path to a directory where the screenshots should be written to. If the directory does not exist, it will be created. The directory can also be set when importing the library. If it is not configured anywhere, screenshots are saved to the same directory where Robot Framework’s log file is written.

If path equals to EMBED (case insensitive) and Capture Page Screenshot or capture Element Screenshot keywords filename argument is not changed from the default value, then the page or element screenshot is embedded as Base64 image to the log.html.

The previous value is returned and can be used to restore the original value later if needed.

Returning the previous value is new in SeleniumLibrary 3.0. The persist argument was removed in SeleniumLibrary 3.2 and EMBED is new in SeleniumLibrary 4.2.


method set_selenium_implicit_wait

set_selenium_implicit_wait(value: timedelta)

Sets the implicit wait value used by Selenium.

The value can be given as a number that is considered to be seconds or as a human-readable string like 1 second. The previous value is returned and can be used to restore the original value later if needed.

This keyword sets the implicit wait for all opened browsers. Use Set Browser Implicit Wait to set it only to the current browser.

See the Implicit wait section above for more information.

${orig wait} =Set Selenium Implicit Wait10 seconds
Perform AJAX call that is slow
Set Selenium Implicit Wait${orig wait}

method set_selenium_page_load_timeout

set_selenium_page_load_timeout(value: timedelta)

Sets the page load timeout value used by Selenium.

The value can be given as a number that is considered to be seconds or as a human-readable string like 1 second. The previous value is returned and can be used to restore the original value later if needed.

In contrast to Set Selenium Timeout and Set Selenium Implicit Wait, this keywords sets the time for the Webdriver to wait until the page is loaded before raising a timeout exception.

See the Page load section above for more information.

${orig page load timeout} =Set Selenium Page Load Timeout30 seconds
Open page that loads slowly
Set Selenium Page Load Timeout${orig page load timeout}

New in SeleniumLibrary 6.1


method set_selenium_speed

set_selenium_speed(value: timedelta)

Sets the delay that is waited after each Selenium command.

The value can be given as a number that is considered to be seconds or as a human-readable string like 1 second. The previous value is returned and can be used to restore the original value later if needed.

See the Selenium Speed section above for more information.

Set Selenium Speed0.5 seconds

method set_selenium_timeout

set_selenium_timeout(value: timedelta)

Sets the timeout that is used by various keywords.

The value can be given as a number that is considered to be seconds or as a human-readable string like 1 second. The previous value is returned and can be used to restore the original value later if needed.

See the Timeout section above for more information.

${orig timeout} =Set Selenium Timeout15 seconds
Open page that loads slowly
Set Selenium Timeout${orig timeout}

method set_window_position

set_window_position(x: int, y: int)

Sets window position using x and y coordinates.

The position is relative to the top left corner of the screen, but some browsers exclude possible task bar set by the operating system from the calculation. The actual position may thus be different with different browsers.

Values can be given using strings containing numbers or by using actual numbers. See also Get Window Position.

Set Window Position100200

method set_window_size

set_window_size(width: int, height: int, inner: bool = False)

Sets current windows size to given width and height.

Values can be given using strings containing numbers or by using actual numbers. See also Get Window Size.

Browsers have a limit on their minimum size. Trying to set them smaller will cause the actual size to be bigger than the requested size.

If inner parameter is set to True, keyword sets the necessary window width and height to have the desired HTML DOM window.innerWidth and window.innerHeight. See Boolean arguments for more details on how to set boolean arguments.

The inner argument is new since SeleniumLibrary 4.0.

This inner argument does not support Frames. If a frame is selected, switch to default before running this.

Set Window Size800600
Set Window Size800600True

method simulate_event

simulate_event(locator: Union[WebElement, str], event: str)

Simulates event on the element identified by locator.

This keyword is useful if element has OnEvent handler that needs to be explicitly invoked.

See the Locating elements section for details about the locator syntax.

Prior to SeleniumLibrary 3.0 this keyword was named Simulate.


method submit_form

submit_form(locator: Union[WebElement, None, str] = None)

Submits a form identified by locator.

If locator is not given, first form on the page is submitted.

See the Locating elements section for details about the locator syntax.


method switch_browser

switch_browser(index_or_alias: str)

Switches between active browsers using index_or_alias.

Indices are returned by the Open Browser keyword and aliases can be given to it explicitly. Indices start from 1.

Open Browserhttp://google.comff
Location Should Behttp://google.com
Open Browserhttp://yahoo.comiealias=second
Location Should Behttp://yahoo.com
Switch Browser1# index
Page Should ContainI’m feeling lucky
Switch Browsersecond# alias
Page Should ContainMore Yahoo!
Close All Browsers

Above example expects that there was no other open browsers when opening the first one because it used index 1 when switching to it later. If you are not sure about that, you can store the index into a variable as below.

${index} =Open Browserhttp://google.com
# Do something …
Switch Browser${index}

method switch_window

switch_window(locator: Union[list, str] = 'MAIN', timeout: Optional[str] = None, browser: str = 'CURRENT')

Switches to browser window matching locator.

If the window is found, all subsequent commands use the selected window, until this keyword is used again. If the window is not found, this keyword fails. The previous windows handle is returned and can be used to switch back to it later.

Notice that alerts should be handled with Handle Alert or other alert related keywords.

The locator can be specified using different strategies somewhat similarly as when locating elements on pages.

  • By default, the locator is matched against window handle, name, title, and URL. Matching is done in that order and the first matching window is selected.
  • The locator can specify an explicit strategy by using the format strategy:value (recommended) or strategy=value. Supported strategies are name, title, and url. These matches windows using their name, title, or URL, respectively. Additionally, default can be used to explicitly use the default strategy explained above.
  • If the locator is NEW (case-insensitive), the latest opened window is selected. It is an error if this is the same as the current window.
  • If the locator is MAIN (default, case-insensitive), the main window is selected.
  • If the locator is CURRENT (case-insensitive), nothing is done. This effectively just returns the current window handle.
  • If the locator is not a string, it is expected to be a list of window handles to exclude. Such a list of excluded windows can be got from Get Window Handles before doing an action that opens a new window.

The timeout is used to specify how long keyword will poll to select the new window. The timeout is new in SeleniumLibrary 3.2.

Click Linkpopup1# Open new window
Switch Windowexample# Select window using default strategy
Title Should BePop-up 1
Click Buttonpopup2# Open another window
${handle} =Switch WindowNEW# Select latest opened window
Title Should BePop-up 2
Switch Window${handle}# Select window using handle
Title Should BePop-up 1
Switch WindowMAIN# Select the main window
Title Should BeMain
${excludes} =Get Window Handles# Get list of current windows
Click Linkpopup3# Open one more window
Switch Window${excludes}# Select window using excludes
Title Should BePop-up 3

The browser argument allows with index_or_alias to implicitly switch to a specific browser when switching to a window. See Switch Browser

  • If the browser is CURRENT (case-insensitive), no other browser is selected.

NOTE:

  • The strategy:value syntax is only supported by SeleniumLibrary 3.0 and newer.
  • Prior to SeleniumLibrary 3.0 matching windows by name, title and URL was case-insensitive.
  • Earlier versions supported aliases None, null and the empty string for selecting the main window, and alias self for selecting the current window. Support for these aliases was removed in SeleniumLibrary 3.2.

method table_cell_should_contain

table_cell_should_contain(locator: Union[WebElement, None, str], row: int, column: int, expected: str, loglevel: str = 'TRACE')

Verifies table cell contains text expected.

See Get Table Cell that this keyword uses internally for an explanation about accepted arguments.


method table_column_should_contain

table_column_should_contain(locator: Union[WebElement, None, str], column: int, expected: str, loglevel: str = 'TRACE')

Verifies table column contains text expected.

The table is located using the locator argument and its column found using column. See the Locating elements section for details about the locator syntax.

Column indexes start from 1. It is possible to refer to columns from the end by using negative indexes so that -1 is the last column, -2 is the second last, and so on.

If a table contains cells that span multiple columns, those merged cells count as a single column.

See Page Should Contain Element for an explanation about the loglevel argument.


method table_footer_should_contain

table_footer_should_contain(locator: Union[WebElement, None, str], expected: str, loglevel: str = 'TRACE')

Verifies table footer contains text expected.

Any <td> element inside <tfoot> element is considered to be part of the footer.

The table is located using the locator argument. See the Locating elements section for details about the locator syntax.

See Page Should Contain Element for an explanation about the loglevel argument.


method table_header_should_contain

table_header_should_contain(locator: Union[WebElement, None, str], expected: str, loglevel: str = 'TRACE')

Verifies table header contains text expected.

Any <th> element anywhere in the table is considered to be part of the header.

The table is located using the locator argument. See the Locating elements section for details about the locator syntax.

See Page Should Contain Element for an explanation about the loglevel argument.


method table_row_should_contain

table_row_should_contain(locator: Union[WebElement, None, str], row: int, expected: str, loglevel: str = 'TRACE')

Verifies that table row contains text expected.

The table is located using the locator argument and its column found using column. See the Locating elements section for details about the locator syntax.

Row indexes start from 1. It is possible to refer to rows from the end by using negative indexes so that -1 is the last row, -2 is the second last, and so on.

If a table contains cells that span multiple rows, a match only occurs for the uppermost row of those merged cells.

See Page Should Contain Element for an explanation about the loglevel argument.


method table_should_contain

table_should_contain(locator: Union[WebElement, None, str], expected: str, loglevel: str = 'TRACE')

Verifies table contains text expected.

The table is located using the locator argument. See the Locating elements section for details about the locator syntax.

See Page Should Contain Element for an explanation about the loglevel argument.


method textarea_should_contain

textarea_should_contain(locator: Union[WebElement, str], expected: str, message: Optional[str] = None)

Verifies text area locator contains text expected.

message can be used to override default error message.

See the Locating elements section for details about the locator syntax.


method textarea_value_should_be

textarea_value_should_be(locator: Union[WebElement, str], expected: str, message: Optional[str] = None)

Verifies text area locator has exactly text expected.

message can be used to override default error message.

See the Locating elements section for details about the locator syntax.


method textfield_should_contain

textfield_should_contain(locator: Union[WebElement, str], expected: str, message: Optional[str] = None)

Verifies text field locator contains text expected.

message can be used to override the default error message.

See the Locating elements section for details about the locator syntax.


method textfield_value_should_be

textfield_value_should_be(locator: Union[WebElement, str], expected: str, message: Optional[str] = None)

Verifies text field locator has exactly text expected.

message can be used to override default error message.

See the Locating elements section for details about the locator syntax.


method title_should_be

title_should_be(title: str, message: Optional[str] = None)

Verifies that the current page title equals title.

The message argument can be used to override the default error message.

message argument is new in SeleniumLibrary 3.1.


method unselect_all_from_list

unselect_all_from_list(locator: Union[WebElement, str])

Unselects all options from multi-selection list locator.

See the Locating elements section for details about the locator syntax.

New in SeleniumLibrary 3.0.


method unselect_checkbox

unselect_checkbox(locator: Union[WebElement, str])

Removes the selection of checkbox identified by locator.

Does nothing if the checkbox is not selected.

See the Locating elements section for details about the locator syntax.


method unselect_frame

unselect_frame()

Sets the main frame as the current frame.

In practice cancels the previous Select Frame call.


method unselect_from_list_by_index

unselect_from_list_by_index(locator: Union[WebElement, str], *indexes: str)

Unselects options from selection list locator by indexes.

Indexes of list options start from 0. This keyword works only with multi-selection lists.

See the Locating elements section for details about the locator syntax.


method unselect_from_list_by_label

unselect_from_list_by_label(locator: Union[WebElement, str], *labels: str)

Unselects options from selection list locator by labels.

This keyword works only with multi-selection lists.

See the Locating elements section for details about the locator syntax.


method unselect_from_list_by_value

unselect_from_list_by_value(locator: Union[WebElement, str], *values: str)

Unselects options from selection list locator by values.

This keyword works only with multi-selection lists.

See the Locating elements section for details about the locator syntax.


method wait_and_click_button

wait_and_click_button(locator: Union[WebElement, ShadowRoot, str], modifier: Optional[str] = None)

Click button identified by locator, once it becomes visible.

locator element locator

modifier press given keys while clicking the element, e.g. CTRL

Click Button When Visible//button[@class=”mybutton”]

method wait_for_condition

wait_for_condition(condition: str, timeout: Optional[timedelta] = None, error: Optional[str] = None)

Waits until condition is true or timeout expires.

The condition can be arbitrary JavaScript expression but it must return a value to be evaluated. See Execute JavaScript for information about accessing content on pages.

Fails if the timeout expires before the condition becomes true. See the Timeouts section for more information about using timeouts and their default value.

error can be used to override the default error message.

Wait For Conditionreturn document.title == “New Title”
Wait For Conditionreturn jQuery.active == 0
Wait For Conditionstyle = document.querySelector(‘h1’).style; return style.background == “red” && style.color == “white”

method wait_until_element_contains

wait_until_element_contains(locator: Union[WebElement, None, str], text: str, timeout: Optional[timedelta] = None, error: Optional[str] = None)

Waits until the element locator contains text.

Fails if timeout expires before the text appears. See the Timeouts section for more information about using timeouts and their default value and the Locating elements section for details about the locator syntax.

error can be used to override the default error message.


method wait_until_element_does_not_contain

wait_until_element_does_not_contain(locator: Union[WebElement, None, str], text: str, timeout: Optional[timedelta] = None, error: Optional[str] = None)

Waits until the element locator does not contain text.

Fails if timeout expires before the text disappears. See the Timeouts section for more information about using timeouts and their default value and the Locating elements section for details about the locator syntax.

error can be used to override the default error message.


method wait_until_element_is_enabled

wait_until_element_is_enabled(locator: Union[WebElement, None, str], timeout: Optional[timedelta] = None, error: Optional[str] = None)

Waits until the element locator is enabled.

Element is considered enabled if it is not disabled nor read-only.

Fails if timeout expires before the element is enabled. See the Timeouts section for more information about using timeouts and their default value and the Locating elements section for details about the locator syntax.

error can be used to override the default error message.

Considering read-only elements to be disabled is a new feature in SeleniumLibrary 3.0.


method wait_until_element_is_not_visible

wait_until_element_is_not_visible(locator: Union[WebElement, None, str], timeout: Optional[timedelta] = None, error: Optional[str] = None)

Waits until the element locator is not visible.

Fails if timeout expires before the element is not visible. See the Timeouts section for more information about using timeouts and their default value and the Locating elements section for details about the locator syntax.

error can be used to override the default error message.


method wait_until_element_is_visible

wait_until_element_is_visible(locator: Union[WebElement, None, str], timeout: Optional[timedelta] = None, error: Optional[str] = None)

Waits until the element locator is visible.

Fails if timeout expires before the element is visible. See the Timeouts section for more information about using timeouts and their default value and the Locating elements section for details about the locator syntax.

error can be used to override the default error message.


method wait_until_location_contains

wait_until_location_contains(expected: str, timeout: Optional[timedelta] = None, message: Optional[str] = None)

Waits until the current URL contains expected.

The expected argument contains the expected value in url.

Fails if timeout expires before the location contains. See the Timeouts section for more information about using timeouts and their default value.

The message argument can be used to override the default error message.

New in SeleniumLibrary 4.0


method wait_until_location_does_not_contain

wait_until_location_does_not_contain(location: str, timeout: Optional[timedelta] = None, message: Optional[str] = None)

Waits until the current URL does not contains location.

The location argument contains value not expected in url.

Fails if timeout expires before the location not contains. See the Timeouts section for more information about using timeouts and their default value.

The message argument can be used to override the default error message.

New in SeleniumLibrary 4.3


method wait_until_location_is

wait_until_location_is(expected: str, timeout: Optional[timedelta] = None, message: Optional[str] = None)

Waits until the current URL is expected.

The expected argument is the expected value in url.

Fails if timeout expires before the location is. See the Timeouts section for more information about using timeouts and their default value.

The message argument can be used to override the default error message.

New in SeleniumLibrary 4.0


method wait_until_location_is_not

wait_until_location_is_not(location: str, timeout: Optional[timedelta] = None, message: Optional[str] = None)

Waits until the current URL is not location.

The location argument is the unexpected value in url.

Fails if timeout expires before the location is not. See the Timeouts section for more information about using timeouts and their default value.

The message argument can be used to override the default error message.

New in SeleniumLibrary 4.3


method wait_until_page_contains

wait_until_page_contains(text: str, timeout: Optional[timedelta] = None, error: Optional[str] = None)

Waits until text appears on the current page.

Fails if timeout expires before the text appears. See the Timeouts section for more information about using timeouts and their default value.

error can be used to override the default error message.


method wait_until_page_contains_element

wait_until_page_contains_element(locator: Union[WebElement, None, str], timeout: Optional[timedelta] = None, error: Optional[str] = None, limit: Optional[int] = None)

Waits until the element locator appears on the current page.

Fails if timeout expires before the element appears. See the Timeouts section for more information about using timeouts and their default value and the Locating elements section for details about the locator syntax.

error can be used to override the default error message.

The limit argument can used to define how many elements the page should contain. When limit is None (default) page can contain one or more elements. When limit is a number, page must contain same number of elements.

limit is new in SeleniumLibrary 4.4


method wait_until_page_does_not_contain

wait_until_page_does_not_contain(text: str, timeout: Optional[timedelta] = None, error: Optional[str] = None)

Waits until text disappears from the current page.

Fails if timeout expires before the text disappears. See the Timeouts section for more information about using timeouts and their default value.

error can be used to override the default error message.


method wait_until_page_does_not_contain_element

wait_until_page_does_not_contain_element(locator: Union[WebElement, None, str], timeout: Optional[timedelta] = None, error: Optional[str] = None, limit: Optional[int] = None)

Waits until the element locator disappears from the current page.

Fails if timeout expires before the element disappears. See the Timeouts section for more information about using timeouts and their default value and the Locating elements section for details about the locator syntax.

error can be used to override the default error message.

The limit argument can used to define how many elements the page should not contain. When limit is None (default) page can`t contain any elements. When limit is a number, page must not contain same number of elements.

limit is new in SeleniumLibrary 4.4