Add Location Strategy

Adds a custom location strategy.

Arguments

Argument Type Default value Description
strategy_namestrnull
strategy_keywordstrnull
persistboolFalse

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.

Alert Should Be Present

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

Arguments

Argument Type Default value Description
textstr
actionstrACCEPT
timeouttimedeltaNone

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.

Alert Should Not Be Present

Verifies that no alert is present.

Arguments

Argument Type Default value Description
actionstrACCEPT
timeouttimedeltaNone

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.

Assign Id To Element

Assigns a temporary ``id`` to the element specified by ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
idstrnull

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.

Examples

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

Attach Chrome Browser

Attach to an existing instance of Chrome or Chromium.

Arguments

Argument Type Default value Description
portintnull
aliasstrNone

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.

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

Examples

Attach Chrome Browser port=9222

Capture Element Screenshot

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

Arguments

Argument Type Default value Description
locatorWebElement, None, strnull
filenamestrselenium-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.

Examples:

Capture Element Screenshot id:image_id
Capture Element Screenshot id:image_id ${OUTPUTDIR}/id_image_id-1.png
Capture Element Screenshot id:image_id EMBED

Capture Page Screenshot

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

Arguments

Argument Type Default value Description
filenamestrselenium-screenshot-{index}.png

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

Examples:

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 Screenshot custom_name.png
File Should Exist ${OUTPUTDIR}/custom_name.png
Capture Page Screenshot custom_with_index_{index}.png
File Should Exist ${OUTPUTDIR}/custom_with_index_1.png
Capture Page Screenshot formatted_index_{index:03}.png
File Should Exist ${OUTPUTDIR}/formatted_index_001.png
Capture Page Screenshot EMBED
File Should Not Exist EMBED

Checkbox Should Be Selected

Verifies checkbox ``locator`` is selected/checked.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

Verifies checkbox locator is selected/checked.

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

Checkbox Should Not Be Selected

Verifies checkbox ``locator`` is not selected/checked.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

Verifies checkbox locator is not selected/checked.

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

Choose File

Inputs the ``file_path`` into the file input field ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
file_pathstrnull

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.

Examples

Choose File my_upload_field ${CURDIR}/trades.csv

Clear All Highlights

Remove all highlighting made by ``Highlight Elements``.

Remove all highlighting made by Highlight Elements.

Clear Element Text

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

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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

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

Click Button

Clicks the button identified by ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
modifierbool, strFalse

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

Click Button When Visible

Click button identified by ``locator``, once it becomes visible.

Arguments

Argument Type Default value Description
locatorstrnull
modifierstrNone

Click button identified by locator, once it becomes visible.

locator element locator

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

Examples

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

Click Element

Click the element identified by ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
modifierbool, strFalse
action_chainboolFalse

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.

Examples

Click Element id:button # Would click element without any modifiers.
Click Element id:button CTRL # Would click element with CTLR key pressed down.
Click Element id:button CTRL+ALT # Would click element with CTLR and ALT keys pressed down.
Click Element id:button action_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

Click Element At Coordinates

Click the element ``locator`` at ``xoffset/yoffset``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
xoffsetintnull
yoffsetintnull

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.

Click Element If Visible

Click element if it is visible

Arguments

Argument Type Default value Description
locatorstrnull

locator element locator

Examples

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

Click Element When Visible

Click element identified by ``locator``, once it becomes visible.

Arguments

Argument Type Default value Description
locatorstrnull
modifierstrNone
action_chainboolFalse

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

Examples

Click Element When Visible q
Click Element When Visible id:button CTRL+ALT
Click Element When Visible action_chain=True

Click Image

Clicks an image identified by ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
modifierbool, strFalse

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

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.

Close Browser

Closes the current browser.

Close Window

Closes currently opened and selected browser window/tab.

Cover Element

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

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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

Example: |Cover Element | css:div#container |

Create Webdriver

Creates an instance of Selenium WebDriver.

Arguments

Argument Type Default value Description
driver_namestrnull
aliasstrNone
kwargs{}
init_kwargsnull

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, Opera, Safari, PhantomJS, 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.

Examples:

# Use proxy with Firefox
${proxy}= Evaluate selenium.webdriver.Proxy() modules=selenium, selenium.webdriver
${proxy.http_proxy}= Set Variable localhost:8888
Create Webdriver Firefox proxy=${proxy}
# Use proxy with PhantomJS
${service args}= Create List --proxy=192.168.132.104:8888
Create Webdriver PhantomJS service_args=${service args}

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.

Current Frame Should Contain

Verifies that the current frame contains ``text``.

Arguments

Argument Type Default value Description
textstrnull
loglevelstrTRACE

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.

Current Frame Should Not Contain

Verifies that the current frame does not contain ``text``.

Arguments

Argument Type Default value Description
textstrnull
loglevelstrTRACE

Verifies that the current frame does not contain text.

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

Delete All Cookies

Deletes all cookies.

Does Alert Contain

Does alert contain text.

Arguments

Argument Type Default value Description
textstrNone
timeoutfloatNone

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

Examples

${res} Does Alert Contain alert message

Does Alert Not Contain

Does alert not contain text.

Arguments

Argument Type Default value Description
textstrNone
timeoutfloatNone

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

Examples

${res} Does Alert Not Contain unexpected message

Does Element Contain

Does element contain expected text

Arguments

Argument Type Default value Description
locatorstrnull
expectedstrnull
ignore_caseboolFalse

locator element locator

expected expected element text

ignore_case should check be case insensitive, default False

Examples

${res} Does Element Contain id:spec specification complete ignore_case=True

Does Frame Contain

Does frame contain expected text

Arguments

Argument Type Default value Description
locatorstrnull
textstrnull

locator locator of the frame to check

text does frame contain this text

Examples

${res} Does Frame Contain id:myframe secret

Does Location Contain

Does current URL contain expected

Arguments

Argument Type Default value Description
expectedstrnull

expected URL should contain this

Examples

Open Available Browser https://robocorp.com
${res} Does Location Contain robocorp

Does Page Contain

Does page contain expected text

Arguments

Argument Type Default value Description
textstrnull

text page should contain this

Examples

Open Available Browser https://google.com
${res} Does Page Contain Gmail

Does Page Contain Button

Does page contain expected button

Arguments

Argument Type Default value Description
locatorstrnull

locator element locator

Examples

${res} Does Page Contain Button search-button

Does Page Contain Checkbox

Does page contain expected checkbox

Arguments

Argument Type Default value Description
locatorstrnull

locator element locator

Examples

${res} Does Page Contain Checkbox random-selection

Does Page Contain Element

Does page contain expected element

Arguments

Argument Type Default value Description
locatorstrnull
countintNone

locator element locator

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

Examples

${res} Does Page Contain Element textarea
${res} Does Page Contain Element button count=4

Does Page Contain Image

Does page contain expected image

Arguments

Argument Type Default value Description
locatorstrnull

locator element locator

Examples

Open Available Browser https://google.com
${res} Does Page Contain Image Google

Does Page Contain List

Does page contain expected list

Arguments

Argument Type Default value Description
locatorstrnull

locator element locator

Examples

${res} Does Page Contain List class:selections

Does Page Contain Radio Button

Does page contain expected radio button

Arguments

Argument Type Default value Description
locatorstrnull

locator element locator

Examples

${res} Does Page Contain Radio Button male

Does Page Contain Textfield

Does page contain expected textfield

Arguments

Argument Type Default value Description
locatorstrnull

locator element locator

Examples

${res} Does Page Contain Textfield id:address

Does Table Cell Contain

Does table cell contain expected text

Arguments

Argument Type Default value Description
locatorstrnull
rowintnull
columnintnull
expectedstrnull

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

Examples

${res} Does Table Cell Contain //table 1 1 Company

Does Table Column Contain

Does table column contain expected text

Arguments

Argument Type Default value Description
locatorstrnull
columnintnull
expectedstrnull

locator element locator for the table

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

expected expected text in table column

Examples

${res} Does Table Column Contain //table 1 Nokia

Does Table Contain

Does table contain expected text

Arguments

Argument Type Default value Description
locatorstrnull
expectedstrnull

locator element locator

expected expected text in table

Examples

${res} Does Table Contain //table February

Does Table Header Contain

Does table header contain expected text

Arguments

Argument Type Default value Description
locatorstrnull
expectedstrnull

locator element locator for the table

expected expected text in table header

Examples

${res} Does Table Header Contain //table Month

Does Table Row Contain

Does table row contain expected text

Arguments

Argument Type Default value Description
locatorstrnull
rowintnull
expectedstrnull

locator element locator for the table

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

expected expected text in table row

Examples

${res} Does Table Row Contain //table 1 Company

Does Textarea Contain

Does textarea contain expected text

Arguments

Argument Type Default value Description
locatorstrnull
expectedstrnull

locator element locator

expected expected text in textarea

Examples

${res} Does Textarea Contain //textarea sincerely

Does Textfield Contain

Does textfield contain expected text

Arguments

Argument Type Default value Description
locatorstrnull
expectedstrnull

locator element locator

expected expected text in textfield

Examples

${res} Does Textfield Contain id:lname Last

Double Click Element

Double clicks the element identified by ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

Double clicks the element identified by locator.

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

Drag And Drop

Drags the element identified by ``locator`` into the ``target`` element.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
targetWebElement, strnull

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.

Examples

Drag And Drop css:div#element css:div.target

Drag And Drop By Offset

Drags the element identified with ``locator`` by ``xoffset/yoffset``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
xoffsetintnull
yoffsetintnull

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.

Examples

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

Element Attribute Value Should Be

Verifies element identified by ``locator`` contains expected attribute value.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
attributestrnull
expectedNone, strnull
messagestrNone

Verifies element identified by locator contains expected attribute value.

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

Example: Element Attribute Value Should Be | css:img | href | value

New in SeleniumLibrary 3.2.

Element Should Be Disabled

Verifies that element identified by ``locator`` is disabled.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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.

Element Should Be Enabled

Verifies that element identified by ``locator`` is enabled.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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.

Element Should Be Focused

Verifies that element identified by ``locator`` is focused.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

Verifies that element identified by locator is focused.

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

New in SeleniumLibrary 3.0.

Element Should Be Visible

Verifies that the element identified by ``locator`` is visible.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
messagestrNone

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.

Element Should Contain

Verifies that element ``locator`` contains text ``expected``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
expectedNone, strnull
messagestrNone
ignore_caseboolFalse

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.

Element Should Not Be Visible

Verifies that the element identified by ``locator`` is NOT visible.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
messagestrNone

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.

Element Should Not Contain

Verifies that element ``locator`` does not contain text ``expected``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
expectedNone, strnull
messagestrNone
ignore_caseboolFalse

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.

Element Text Should Be

Verifies that element ``locator`` contains exact the text ``expected``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
expectedNone, strnull
messagestrNone
ignore_caseboolFalse

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.

Element Text Should Not Be

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

Arguments

Argument Type Default value Description
locatorWebElement, strnull
not_expectedNone, strnull
messagestrNone
ignore_caseboolFalse

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

Execute Async Javascript

Executes asynchronous JavaScript code with possible arguments.

Arguments

Argument Type Default value Description
codeWebElement, strnull

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.

Examples:

Execute Async JavaScript var 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

Execute Cdp

Executes Chrome DevTools Protocol commands

Arguments

Argument Type Default value Description
commandnull
parametersnull

Works only with Chrome/Chromium

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

Examples

Open Chrome Browser about:blank headless=True
&{params} Create Dictionary useragent=Chrome/83.0.4103.53
Execute CDP Network.setUserAgentOverride ${params}
Go To https://robocorp.com

Execute Javascript

Executes the given JavaScript code with possible arguments.

Arguments

Argument Type Default value Description
codeWebElement, strnull

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.

Examples:

Execute JavaScript window.myFunc('arg1', 'arg2')
Execute JavaScript ${CURDIR}/js_to_execute.js
Execute JavaScript alert(arguments[0]); ARGUMENTS 123
Execute JavaScript ARGUMENTS 123 JAVASCRIPT alert(arguments[0]);

Frame Should Contain

Verifies that frame identified by ``locator`` contains ``text``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
textstrnull
loglevelstrTRACE

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.

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

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

Examples

Open Browser https://example.com alias=BrowserA
Open Browser https://example.com alias=BrowserB
&{aliases} Get Browser Aliases # &{aliases} = { BrowserA=1|BrowserB=2 }
Log ${aliases.BrowserA} # logs 1
FOR ${alias} IN @{aliases}
Log ${alias} # logs BrowserA and BrowserB
END

See Switch Browser for more information and examples.

New in SeleniumLibrary 4.0

Get Browser Capabilities

Get dictionary of browser properties

Examples

${caps}= Get Browser Capabilities

Get Browser Ids

Returns index of all active browser as list.

Examples

@{browser_ids}= Get Browser Ids
FOR ${id} IN @{browser_ids}
@{window_titles}= Get Window Titles browser=${id}
Log Browser ${id} has these windows: ${window_titles}
END

See Switch Browser for more information and examples.

New in SeleniumLibrary 4.0

Get Cookies

Returns all cookies of the current page.

Arguments

Argument Type Default value Description
as_dictboolFalse

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

Get Element Attribute

Returns the value of ``attribute`` from the element ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
attributestrnull

Returns the value of attribute from the element locator.

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

Examples

${id}= Get Element Attribute css:h1 id

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

Get Element Count

Returns the number of elements matching ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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.

Examples

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

New in SeleniumLibrary 3.0.

Get Element Size

Returns width and height of the element identified by ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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.

Examples

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

Get Element Status

Return dictionary containing element status of:

Arguments

Argument Type Default value Description
locatorstrnull
  • visible
  • enabled
  • disabled
  • focused

locator element locator

Examples

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

Get Horizontal Position

Returns the horizontal position of the element identified by ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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.

Get List Items

Returns all labels or values of selection list ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
valuesboolFalse

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

Examples

${labels} = Get List Items mylist
${values} = Get List Items css:#example select values=True

Support to return values is new in SeleniumLibrary 3.0.

Get Location

Returns the current browser window URL.

Get Locations

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

Arguments

Argument Type Default value Description
browserstrCURRENT

Browser Scope:

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

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

Get Selected List Label

Returns the label of selected option from selection list ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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.

Get Selected List Labels

Returns labels of selected options from selection list ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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.

Get Selected List Value

Returns the value of selected option from selection list ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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.

Get Selected List Values

Returns values of selected options from selection list ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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.

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.

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.

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.

Get Session Id

Returns the currently active browser session id.

New in SeleniumLibrary 3.2

Get Source

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

Get Table Cell

Returns contents of a table cell.

Arguments

Argument Type Default value Description
locatorWebElement, None, strnull
rowintnull
columnintnull
loglevelstrTRACE

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.

Get Testability Status

Get SeleniumTestability plugin status

Get Text

Returns the text value of the element identified by ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

Returns the text value of the element identified by locator.

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

Get Title

Returns the title of the current page.

Get Value

Returns the value attribute of the element identified by ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

Returns the value attribute of the element identified by locator.

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

Get Vertical Position

Returns the vertical position of the element identified by ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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.

Get WebElement

Returns the first WebElement matching the given ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

Returns the first WebElement matching the given locator.

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

Get WebElements

Returns a list of WebElement objects matching the ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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.

Get Window Handles

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

Arguments

Argument Type Default value Description
browserstrCURRENT

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.

Get Window Identifiers

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

Arguments

Argument Type Default value Description
browserstrCURRENT

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

Get Window Names

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

Arguments

Argument Type Default value Description
browserstrCURRENT

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

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.

Examples

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

Get Window Size

Returns current window width and height as integers.

Arguments

Argument Type Default value Description
innerboolFalse

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.

Examples

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

Get Window Titles

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

Arguments

Argument Type Default value Description
browserstrCURRENT

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

Go Back

Simulates the user clicking the back button on their browser.

Go To

Navigates the current browser window to the provided ``url``.

Arguments

Argument Type Default value Description
urlnull

Navigates the current browser window to the provided url.

Handle Alert

Handles the current alert and returns its message.

Arguments

Argument Type Default value Description
actionstrACCEPT
timeouttimedeltaNone

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.

Examples:

Handle Alert # Accept alert.
Handle Alert action=DISMISS # Dismiss alert.
Handle Alert timeout=10 s # Use custom timeout and accept alert.
Handle Alert DISMISS 1 min # Use custom timeout and dismiss alert.
${message} = Handle Alert # Accept alert and get its message.
${message} = Handle Alert LEAVE # Leave alert open and get its message.

New in SeleniumLibrary 3.0.

Highlight Elements

Highlight all matching elements by locator.

Arguments

Argument Type Default value Description
locatorstrnull
widthstr2px
stylestrdotted
colorstrblue

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

Examples

Highlight Elements xpath://h2

Input Password

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

Arguments

Argument Type Default value Description
locatorWebElement, strnull
passwordstrnull
clearboolTrue

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 Password password_field password

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

Input Password password_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.

Input Text

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

Arguments

Argument Type Default value Description
locatorWebElement, strnull
textstrnull
clearboolTrue

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

Input Text Into Alert

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

Arguments

Argument Type Default value Description
textstrnull
actionstrACCEPT
timeouttimedeltaNone

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.

Input Text When Element Is Visible

Input text into locator after it has become visible.

Arguments

Argument Type Default value Description
locatorstrnull
textstrnull

locator element locator

text insert text to locator

Examples

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

Is Alert Present

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

Arguments

Argument Type Default value Description
textstrNone
actionstrACCEPT

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

Examples

${res} Is Alert Present alert message

Is Checkbox Selected

Is checkbox selected

Arguments

Argument Type Default value Description
locatorstrnull

locator element locator

Examples

${res} Is Checkbox Selected id:taxes-paid

Is Element Attribute Equal To

Is element attribute equal to expected value

Arguments

Argument Type Default value Description
locatorstrnull
attributestrnull
expectedstrnull

locator element locator

attribute element attribute to check for

expected is attribute value equal to this

Examples

${res} Is Element Attribute Equal To h1 id main

Is Element Disabled

Is element disabled

Arguments

Argument Type Default value Description
locatorstrnull
missing_okboolTrue

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

Examples

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

Is Element Enabled

Is element enabled

Arguments

Argument Type Default value Description
locatorstrnull
missing_okboolTrue

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

Examples

${res} Is Element Enabled input.field1

Is Element Focused

Is element focused

Arguments

Argument Type Default value Description
locatorstrnull
missing_okboolTrue

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

Examples

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

Is Element Text

Is element text expected

Arguments

Argument Type Default value Description
locatorstrnull
expectedstrnull
ignore_caseboolFalse

locator element locator

expected expected element text

ignore_case should check be case insensitive, default False

Examples

${res} Is Element Text id:name john doe
${res} Is Element Text id:name john doe ignore_case=True

Is Element Visible

Is element visible

Arguments

Argument Type Default value Description
locatorstrnull
missing_okboolTrue

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

Examples

${res} Is Element Visible id:confirmation

Is List Selected

Is any option selected in the

Arguments

Argument Type Default value Description
locatorstrnull

locator element locator

Examples

${res} Is List Selected id:cars

Is List Selection

Is list selected with expected values

Arguments

Argument Type Default value Description
locatorstrnull
expectedstrnull

locator element locator

expected expected selected options

Examples

${res} Is List Selection id:cars Ford

Is Location

Is current URL expected url

Arguments

Argument Type Default value Description
urlstrnull

url expected current URL

Examples

Open Available Browser https://www.robocorp.com
${res} Is Location https://www.robocorp.com

Is Radio Button Selected

Is any radio button selected in the button group

Arguments

Argument Type Default value Description
group_namestrnull

group_name radio button group name

Examples

${res} Is Radio Button Selected group_name=gender

Is Radio Button Set To

Is radio button group set to expected value

Arguments

Argument Type Default value Description
group_namestrnull
valuestrnull

group_name radio button group name

value expected value

Examples

${res} Is Radio Button Set To group_name=gender value=female

Is Textarea Value

Is textarea matching expected value

Arguments

Argument Type Default value Description
locatorstrnull
expectedstrnull

locator element locator

expected expected textarea value

Examples

${res} Is Textarea Value //textarea Yours sincerely

Is Textfield Value

Is textfield value expected

Arguments

Argument Type Default value Description
locatorstrnull
expectedstrnull

locator element locator

expected expected textfield value

Examples

${res} Is Textfield Value id:lname Lastname

Is Title

Is page title expected

Arguments

Argument Type Default value Description
titlestrnull

title expected title value

Examples

${res} Is Title Webpage title text

List Selection Should Be

Verifies selection list ``locator`` has ``expected`` options selected.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
expectedstrnull

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.

Examples:

List Selection Should Be gender Female
List Selection Should Be interests Test Automation Python

List Should Have No Selections

Verifies selection list ``locator`` has no options selected.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

Verifies selection list locator has no options selected.

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

Location Should Be

Verifies that the current URL is exactly ``url``.

Arguments

Argument Type Default value Description
urlstrnull
messagestrNone

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.

Location Should Contain

Verifies that the current URL contains ``expected``.

Arguments

Argument Type Default value Description
expectedstrnull
messagestrNone

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.

Log Location

Logs and returns the current browser window URL.

Log Source

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

Arguments

Argument Type Default value Description
loglevelstrINFO

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

Log Title

Logs and returns the title of the current page.

Maximize Browser Window

Maximizes current browser window.

Mouse Down

Simulates pressing the left mouse button on the element ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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.

Mouse Down On Image

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

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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 Out

Simulates moving the mouse away from the element ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

Simulates moving the mouse away from the element locator.

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

Mouse Over

Simulates hovering the mouse over the element ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

Simulates hovering the mouse over the element locator.

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

Mouse Up

Simulates releasing the left mouse button on the element ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

Simulates releasing the left mouse button on the element locator.

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

Open Available Browser

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.

Arguments

Argument Type Default value Description
urlstrNone
use_profileboolFalse
headlessAnyAUTO
maximizedboolFalse
browser_selectionAnyAUTO
aliasstrNone
profile_namestrNone
profile_pathstrNone
preferencesdictNone
proxystrNone
user_agentstrNone
downloadAnyAUTO

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 overriden with the user_agent argument.

Examples

Open Available Browser https://www.robocorp.com
${index}= Open Available Browser ${URL} browser_selection=opera,firefox
Open Available Browser ${URL} headless=True alias=HeadlessBrowser

Browser order

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

Platform Default order
Windows | Chrome, Firefox, Edge, IE, Opera
Linux | Chrome, Firefox, Opera
Darwin | Chrome, Safari, Firefox, Opera

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

Webdriver download

The library can (if requested) automatically download webdrivers for all 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

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

2. Loop through listed browsers:

a. Set the webdriver options for the browser.

b. Download webdriver (if requested).

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

3. 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, i.e. a container.

Chrome options

Some features are currently available only for Chrome/Chromium. 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.

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

Chrome can additionally connect through a proxy, which should be given as either local or remote address.

Open Browser

Opens a new browser instance to the optional ``url``.

Arguments

Argument Type Default value Description
urlstrNone
browserstrfirefox
aliasstrNone
remote_urlbool, strFalse
desired_capabilitiesdict, None, strNone
ff_profile_dirFirefoxProfile, str, NoneNone
optionsAnyNone
service_log_pathstrNone
executable_pathstrNone

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.

Browser Name(s)
Firefox firefox, ff
Google Chrome googlechrome, chrome, gc
Headless Firefox headlessfirefox
Headless Chrome headlesschrome
Internet Explorer internetexplorer, ie
Edge edge
Safari safari
Opera opera
Android android
Iphone iphone
PhantomJS phantomjs
HTMLUnit htmlunit
HTMLUnit with Javascript htmlunitwithjs

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 can be used to configure, for example, logging preferences for a browser or a browser and operating system when using Sauce Labs. Desired capabilities can be given either as a Python dictionary or as a string in the format key1:value1,key2:value2. Selenium documentation lists possible capabilities that can be enabled.

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 options argument. Example: It is possible to use FirefoxProfile set_preference to define different profile settings. See options 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. If browser argument is android then Chrome options is used. 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.

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

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

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

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.

Examples:

Open Browser http://example.com Chrome
Open Browser http://example.com Firefox alias=Firefox
Open Browser http://example.com Edge remote_url=http://127.0.0.1:4444/wd/hub
Open Browser about:blank
Open Browser browser=Chrome

Alias examples:

${1_index} = Open Browser http://example.com Chrome alias=Chrome # Opens new browser because alias is new.
${2_index} = Open Browser http://example.com Firefox # Opens new browser because alias is not defined.
${3_index} = Open Browser http://example.com Chrome alias=Chrome # Switches to the browser with Chrome alias.
${4_index} = Open Browser http://example.com Chrome alias=${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 Browser http://example.com Chrome options=add_argument("--disable-popup-blocking"); add_argument("--ignore-certificate-errors") # Sting format.
${options} = Get Options # Selenium options instance.
Open Browser http://example.com Chrome options=${options}
Open Browser None Chrome options=binary_location="/path/to/binary";add_argument("remote-debugging-port=port") # Start Chomium-based application.
Open Browser None Chrome options=binary_location=r"C:\\path\\to\\binary" # Windows OS path escaping.

Example for FirefoxProfile

Open Browser http://example.com Firefox ff_profile_dir=/path/to/profile # Using profile from disk.
Open Browser http://example.com Firefox ff_profile_dir=${FirefoxProfile_instance} # Using instance of FirefoxProfile.
Open Browser http://example.com Firefox ff_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.

Open Chrome Browser

Open Chrome browser. See ``Open Available Browser`` for descriptions of arguments.

Arguments

Argument Type Default value Description
urlstrnull
use_profileboolFalse
headlessboolFalse
maximizedboolFalse
aliasstrNone
profile_namestrNone
profile_pathstrNone
preferencesdictNone
proxystrNone
user_agentstrNone

Open Chrome browser. See Open Available Browser for descriptions of arguments.

Open Context Menu

Opens the context menu on the element identified by ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

Opens the context menu on the element identified by locator.

Open Headless Chrome Browser

Open Chrome browser in headless mode.

Arguments

Argument Type Default value Description
urlstrnull

url URL to open

Examples

${idx} Open Headless Chrome Browser https://www.google.com

Open User Browser

Open URL with user's default browser

Arguments

Argument Type Default value Description
urlstrnull
tabTrue

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

The keyword Attach Chrome Browser can be used to access 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 (default True) or in new window (False)

Examples

Open User Browser https://www.google.com?q=rpa
Open User Browser https://www.google.com?q=rpa tab=False

Page Should Contain

Verifies that current page contains ``text``.

Arguments

Argument Type Default value Description
textstrnull
loglevelstrTRACE

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 DEBUG, INFO (default), WARN, and NONE. If the log level is NONE or below the current active log level the source will not be logged.

Page Should Contain Button

Verifies button ``locator`` is found from current page.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
messagestrNone
loglevelstrTRACE

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.

Page Should Contain Checkbox

Verifies checkbox ``locator`` is found from the current page.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
messagestrNone
loglevelstrTRACE

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.

Page Should Contain Element

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

Arguments

Argument Type Default value Description
locatorWebElement, strnull
messagestrNone
loglevelstrTRACE
limitintNone

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 Element div_name limit=1 # Keyword fails.
Page Should Contain Element div_name limit=2 # Keyword passes.
Page Should Contain Element div_name limit=none # None is considered one or more.
Page Should Contain Element div_name # Same as above.

The limit argument is new in SeleniumLibrary 3.0.

Page Should Contain Image

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

Arguments

Argument Type Default value Description
locatorWebElement, strnull
messagestrNone
loglevelstrTRACE

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 List

Verifies selection list ``locator`` is found from current page.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
messagestrNone
loglevelstrTRACE

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.

Page Should Contain Radio Button

Verifies radio button ``locator`` is found from current page.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
messagestrNone
loglevelstrTRACE

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.

Page Should Contain Textfield

Verifies text field ``locator`` is found from current page.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
messagestrNone
loglevelstrTRACE

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.

Page Should Not Contain

Verifies the current page does not contain ``text``.

Arguments

Argument Type Default value Description
textstrnull
loglevelstrTRACE

Verifies the current page does not contain text.

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

Page Should Not Contain Button

Verifies button ``locator`` is not found from current page.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
messagestrNone
loglevelstrTRACE

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.

Page Should Not Contain Checkbox

Verifies checkbox ``locator`` is not found from the current page.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
messagestrNone
loglevelstrTRACE

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.

Page Should Not Contain Element

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

Arguments

Argument Type Default value Description
locatorWebElement, strnull
messagestrNone
loglevelstrTRACE

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.

Page Should Not Contain Image

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

Arguments

Argument Type Default value Description
locatorWebElement, strnull
messagestrNone
loglevelstrTRACE

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 List

Verifies selection list ``locator`` is not found from current page.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
messagestrNone
loglevelstrTRACE

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.

Page Should Not Contain Radio Button

Verifies radio button ``locator`` is not found from current page.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
messagestrNone
loglevelstrTRACE

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.

Page Should Not Contain Textfield

Verifies text field ``locator`` is not found from current page.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
messagestrNone
loglevelstrTRACE

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.

Press Key

*DEPRECATED in SeleniumLibrary 4.0.* use `Press Keys` instead.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
keystrnull

DEPRECATED in SeleniumLibrary 4.0. use Press Keys instead.

Press Keys

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

Arguments

Argument Type Default value Description
locatorWebElement, None, strNone
keysstrnull

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

Examples:

Press Keys text_field AAAAA # Sends string "AAAAA" to element.
Press Keys None BBBBB # Sends string "BBBBB" to currently active browser.
Press Keys text_field E+N+D # Sends string "END" to element.
Press Keys text_field XXX YY # Sends strings "XXX" and "YY" to element.
Press Keys text_field XXX+YY # Same as above.
Press Keys text_field ALT+ARROW_DOWN # Pressing "ALT" key down, then pressing ARROW_DOWN and then releasing both keys.
Press Keys text_field ALT ARROW_DOWN # Pressing "ALT" key and then pressing ARROW_DOWN.
Press Keys text_field CTRL+c # Pressing CTRL key down, sends string "c" and then releases CTRL key.
Press Keys button RETURN # Pressing "ENTER" key to element.

Radio Button Should Be Set To

Verifies radio button group ``group_name`` is set to ``value``.

Arguments

Argument Type Default value Description
group_namestrnull
valuestrnull

Verifies radio button group group_name is set to value.

group_name is the name of the radio button group.

Radio Button Should Not Be Selected

Verifies radio button group ``group_name`` has no selection.

Arguments

Argument Type Default value Description
group_namestrnull

Verifies radio button group group_name has no selection.

group_name is the name of the radio button group.

Register Keyword To Run On Failure

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

Arguments

Argument Type Default value Description
keywordstr, Nonenull

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.

Examples

Register Keyword To Run On Failure Log Source
${previous kw}= Register Keyword To Run On Failure NONE
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.

Reload Page

Simulates user reloading page.

Remove Location Strategy

Removes a previously added custom location strategy.

Arguments

Argument Type Default value Description
strategy_namestrnull

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

Screenshot

Capture page and/or element screenshot.

Arguments

Argument Type Default value Description
locatorstrNone
filenamestr

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

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

Examples

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

Scroll Element Into View

Scrolls the element identified by ``locator`` into view.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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

Select All From List

Selects all options from multi-selection list ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

Selects all options from multi-selection list locator.

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

Select Checkbox

Selects the checkbox identified by ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

Selects the checkbox identified by locator.

Does nothing if checkbox is already selected.

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

Select Frame

Sets frame identified by ``locator`` as the current frame.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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.

Examples

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

Select From List By Index

Selects options from selection list ``locator`` by ``indexes``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
indexesstrnull

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.

Select From List By Label

Selects options from selection list ``locator`` by ``labels``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
labelsstrnull

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.

Select From List By Value

Selects options from selection list ``locator`` by ``values``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
valuesstrnull

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.

Select Radio Button

Sets the radio button group ``group_name`` to ``value``.

Arguments

Argument Type Default value Description
group_namestrnull
valuestrnull

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.

Examples:

Select Radio Button size XL
Select Radio Button contact email

Set Browser Implicit Wait

Sets the implicit wait value used by Selenium.

Arguments

Argument Type Default value Description
valuetimedeltanull

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

Set Download Directory

Set browser download directory

Arguments

Argument Type Default value Description
directorystrNone
download_pdfboolTrue

directory target directory for downloads, defaults to None which means that setting is removed download_pdf if True then PDF is downloaded instead of shown with browser's internal viewer

Set Focus To Element

Sets the focus to the element identified by ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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.

Set Screenshot Directory

Sets the directory for captured screenshots.

Arguments

Argument Type Default value Description
pathNone, strnull

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.

Set Selenium Implicit Wait

Sets the implicit wait value used by Selenium.

Arguments

Argument Type Default value Description
valuetimedeltanull

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.

Examples

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

Set Selenium Speed

Sets the delay that is waited after each Selenium command.

Arguments

Argument Type Default value Description
valuetimedeltanull

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.

Examples

Set Selenium Speed 0.5 seconds

Set Selenium Timeout

Sets the timeout that is used by various keywords.

Arguments

Argument Type Default value Description
valuetimedeltanull

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.

Examples

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

Set Window Position

Sets window position using ``x`` and ``y`` coordinates.

Arguments

Argument Type Default value Description
xintnull
yintnull

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.

Examples

Set Window Position 100 200

Set Window Size

Sets current windows size to given ``width`` and ``height``.

Arguments

Argument Type Default value Description
widthintnull
heightintnull
innerboolFalse

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.

Examples

Set Window Size 800 600
Set Window Size 800 600 True

Simulate Event

Simulates ``event`` on the element identified by ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
eventstrnull

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.

Submit Form

Submits a form identified by ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, None, strNone

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.

Switch Browser

Switches between active browsers using ``index_or_alias``.

Arguments

Argument Type Default value Description
index_or_aliasstrnull

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.

Examples

Open Browser http://google.com ff
Location Should Be http://google.com
Open Browser http://yahoo.com ie alias=second
Location Should Be http://yahoo.com
Switch Browser 1 # index
Page Should Contain I'm feeling lucky
Switch Browser second # alias
Page Should Contain More 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 Browser http://google.com
# Do something ...
Switch Browser ${index}

Switch Window

Switches to browser window matching ``locator``.

Arguments

Argument Type Default value Description
locatorlist, strMAIN
timeoutstrNone
browserstrCURRENT

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.

Examples

Click Link popup1 # Open new window
Switch Window example # Select window using default strategy
Title Should Be Pop-up 1
Click Button popup2 # Open another window
${handle} = Switch Window NEW # Select latest opened window
Title Should Be Pop-up 2
Switch Window ${handle} # Select window using handle
Title Should Be Pop-up 1
Switch Window MAIN # Select the main window
Title Should Be Main
${excludes} = Get Window Handles # Get list of current windows
Click Link popup3 # Open one more window
Switch Window ${excludes} # Select window using excludes
Title Should Be Pop-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.

Table Cell Should Contain

Verifies table cell contains text ``expected``.

Arguments

Argument Type Default value Description
locatorWebElement, None, strnull
rowintnull
columnintnull
expectedstrnull
loglevelstrTRACE

Verifies table cell contains text expected.

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

Table Column Should Contain

Verifies table column contains text ``expected``.

Arguments

Argument Type Default value Description
locatorWebElement, None, strnull
columnintnull
expectedstrnull
loglevelstrTRACE

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.

Table Header Should Contain

Verifies table header contains text ``expected``.

Arguments

Argument Type Default value Description
locatorWebElement, None, strnull
expectedstrnull
loglevelstrTRACE

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.

Table Row Should Contain

Verifies that table row contains text ``expected``.

Arguments

Argument Type Default value Description
locatorWebElement, None, strnull
rowintnull
expectedstrnull
loglevelstrTRACE

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.

Table Should Contain

Verifies table contains text ``expected``.

Arguments

Argument Type Default value Description
locatorWebElement, None, strnull
expectedstrnull
loglevelstrTRACE

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.

Textarea Should Contain

Verifies text area ``locator`` contains text ``expected``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
expectedstrnull
messagestrNone

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.

Textarea Value Should Be

Verifies text area ``locator`` has exactly text ``expected``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
expectedstrnull
messagestrNone

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.

Textfield Should Contain

Verifies text field ``locator`` contains text ``expected``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
expectedstrnull
messagestrNone

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.

Textfield Value Should Be

Verifies text field ``locator`` has exactly text ``expected``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
expectedstrnull
messagestrNone

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.

Title Should Be

Verifies that the current page title equals ``title``.

Arguments

Argument Type Default value Description
titlestrnull
messagestrNone

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.

Unselect All From List

Unselects all options from multi-selection list ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

Unselects all options from multi-selection list locator.

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

New in SeleniumLibrary 3.0.

Unselect Checkbox

Removes the selection of checkbox identified by ``locator``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull

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.

Unselect Frame

Sets the main frame as the current frame.

In practice cancels the previous Select Frame call.

Unselect From List By Index

Unselects options from selection list ``locator`` by ``indexes``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
indexesstrnull

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.

Unselect From List By Label

Unselects options from selection list ``locator`` by ``labels``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
labelsstrnull

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.

Unselect From List By Value

Unselects options from selection list ``locator`` by ``values``.

Arguments

Argument Type Default value Description
locatorWebElement, strnull
valuesstrnull

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.

Wait And Click Button

Click button identified by ``locator``, once it becomes visible.

Arguments

Argument Type Default value Description
locatorstrnull
modifierstrNone

Click button identified by locator, once it becomes visible.

locator element locator

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

Examples

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

Wait For Condition

Waits until ``condition`` is true or ``timeout`` expires.

Arguments

Argument Type Default value Description
conditionstrnull
timeouttimedeltaNone
errorstrNone

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.

Examples:

Wait For Condition return document.title == "New Title"
Wait For Condition return jQuery.active == 0
Wait For Condition style = document.querySelector('h1').style; return style.background == "red" && style.color == "white"

Wait Until Element Contains

Waits until the element ``locator`` contains ``text``.

Arguments

Argument Type Default value Description
locatorWebElement, None, strnull
textstrnull
timeouttimedeltaNone
errorstrNone

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.

Wait Until Element Does Not Contain

Waits until the element ``locator`` does not contain ``text``.

Arguments

Argument Type Default value Description
locatorWebElement, None, strnull
textstrnull
timeouttimedeltaNone
errorstrNone

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.

Wait Until Element Is Enabled

Waits until the element ``locator`` is enabled.

Arguments

Argument Type Default value Description
locatorWebElement, None, strnull
timeouttimedeltaNone
errorstrNone

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.

Wait Until Element Is Not Visible

Waits until the element ``locator`` is not visible.

Arguments

Argument Type Default value Description
locatorWebElement, None, strnull
timeouttimedeltaNone
errorstrNone

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.

Wait Until Element Is Visible

Waits until the element ``locator`` is visible.

Arguments

Argument Type Default value Description
locatorWebElement, None, strnull
timeouttimedeltaNone
errorstrNone

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.

Wait Until Location Contains

Waits until the current URL contains ``expected``.

Arguments

Argument Type Default value Description
expectedstrnull
timeouttimedeltaNone
messagestrNone

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

Wait Until Location Does Not Contain

Waits until the current URL does not contains ``location``.

Arguments

Argument Type Default value Description
locationstrnull
timeouttimedeltaNone
messagestrNone

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

Wait Until Location Is

Waits until the current URL is ``expected``.

Arguments

Argument Type Default value Description
expectedstrnull
timeouttimedeltaNone
messagestrNone

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

Wait Until Location Is Not

Waits until the current URL is not ``location``.

Arguments

Argument Type Default value Description
locationstrnull
timeouttimedeltaNone
messagestrNone

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

Wait Until Page Contains

Waits until ``text`` appears on the current page.

Arguments

Argument Type Default value Description
textstrnull
timeouttimedeltaNone
errorstrNone

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.

Wait Until Page Contains Element

Waits until the element ``locator`` appears on the current page.

Arguments

Argument Type Default value Description
locatorWebElement, None, strnull
timeouttimedeltaNone
errorstrNone
limitintNone

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

Wait Until Page Does Not Contain

Waits until ``text`` disappears from the current page.

Arguments

Argument Type Default value Description
textstrnull
timeouttimedeltaNone
errorstrNone

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.

Wait Until Page Does Not Contain Element

Waits until the element ``locator`` disappears from the current page.

Arguments

Argument Type Default value Description
locatorWebElement, None, strnull
timeouttimedeltaNone
errorstrNone
limitintNone

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