RPA.Browser.Selenium
Adds a cookie to your current session.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
name | str | null | |
value | str | null | |
path | str, None | None | |
domain | str, None | None | |
secure | bool, None | None | |
expiry | str, None | None |
name
and value
are required, path
, domain
, secure
and expiry
are optional. Expiry supports the same formats as the DateTime library or an epoch timestamp.
Examples
Add Cookie | foo | bar | ||
Add Cookie | foo | bar | domain=example.com | |
Add Cookie | foo | bar | expiry=2027-09-28 16:21:35 | # Expiry as timestamp. |
Add Cookie | foo | bar | expiry=1822137695 | # Expiry as epoch seconds. |
Prior to SeleniumLibrary 3.0 setting expiry did not work.
Adds a custom location strategy.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
strategy_name | str | null | |
strategy_keyword | str | null | |
persist | bool | False |
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.
Verifies that an alert is present and by default, accepts it.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
text | str | ||
action | str | ACCEPT | |
timeout | timedelta, None | None |
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.
Verifies that no alert is present.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
action | str | ACCEPT | |
timeout | timedelta, None | None |
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.
Assigns a temporary id
to the element specified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
id | str | null |
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 to an existing instance of Chrome browser.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
port | int | null | |
alias | str, None | None |
Requires that the browser was started with the command line option --remote-debugging-port=<port>
, where port is any 4-digit number not being used by other applications.
Note. The first Chrome instance on the system needs to be started with this command line option or this won't have an effect.
That port can then be used to connect using this keyword.
Examples
Attach Chrome Browser | port=9222 |
Captures a screenshot from the element identified by locator
and embeds it into log file.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, None, str | null | |
filename | str | selenium-element-screenshot-{index}.png |
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 |
Takes a screenshot of the current page and embeds it into a log file.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
filename | str | selenium-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 |
Verifies checkbox locator
is selected/checked.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
See the Locating elements section for details about the locator syntax.
Verifies checkbox locator
is not selected/checked.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
See the Locating elements section for details about the locator syntax.
Inputs the file_path
into the file input field locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
file_path | str | null |
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 |
Remove all highlighting made by Highlight Elements
.
Clears the value of the text-input-element identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
See the Locating elements section for details about the locator syntax.
Clicks the button identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
modifier | bool, str | False |
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 identified by locator
, once it becomes visible.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, ShadowRoot, str | null | |
modifier | str, None | None |
locator
element locator
modifier
press given keys while clicking the element, e.g. CTRL
Examples
Click Button When Visible | //button[@class="mybutton"] |
Click the element identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
modifier | bool, str | False | |
action_chain | bool | False |
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 the element locator
at xoffset/yoffset
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
xoffset | int | null | |
yoffset | int | null |
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.
Waits for and clicks an element until is fully ready to be clicked.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, ShadowRoot, str | null | |
timeout | str, int, timedelta, None | None |
If a normal click doesn't work, then JavaScript-oriented workarounds are tried as a fallback mechanism.
Parameter locator
targets the element to be clicked. Parameter timeout
optionally configures a custom duration to wait for the element to become clickable, until it gives up.
Examples
Click Element When Clickable | example |
Click element identified by locator
, once it becomes visible.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, ShadowRoot, str | null | |
modifier | str, None | None | |
action_chain | bool | False |
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 |
Clicks an image identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
modifier | bool, str | False |
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
Clicks a link identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
modifier | bool, str | False |
See the Locating elements section for details about the locator syntax. When using the default locator strategy, links are searched using id
, name
, href
and the link text.
See the Click Element keyword for details about the modifier
argument.
The modifier
argument is new in SeleniumLibrary 3.3
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.
Closes the current browser.
Closes currently opened and selected browser window/tab.
Will cover elements identified by locator
with a blue div without breaking page layout.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
See the Locating elements section for details about the locator syntax.
New in SeleniumLibrary 3.3.0
Example: |Cover Element | css:div#container |
Creates an instance of Selenium WebDriver.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
driver_name | str | null | |
alias | str, None | None | |
kwargs | {} | ||
init_kwargs | null |
Like Open Browser, but allows passing arguments to the created WebDriver instance directly. This keyword should only be used if the functionality provided by Open Browser is not adequate.
driver_name
must be a WebDriver implementation name like Firefox, Chrome, Ie, Edge, Safari, or Remote.
The initialized WebDriver can be configured either with a Python dictionary kwargs
or by using keyword arguments **init_kwargs
. These arguments are passed directly to WebDriver without any processing. See Selenium API documentation for details about the supported arguments.
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} |
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.
Verifies that the current frame contains text
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
text | str | null | |
loglevel | str | TRACE |
See Page Should Contain for an explanation about the loglevel
argument.
Prior to SeleniumLibrary 3.0 this keyword was named Current Frame Contains.
Verifies that the current frame does not contain text
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
text | str | null | |
loglevel | str | TRACE |
See Page Should Contain for an explanation about the loglevel
argument.
Deletes all cookies.
Deletes the cookie matching name
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
name | null |
If the cookie is not found, nothing happens.
Does element contain expected text
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, ShadowRoot, str | null | |
expected | str | null | |
ignore_case | bool | False |
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 current URL contain expected
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
expected | str | null |
expected
URL should contain this
Examples
Open Available Browser | https://robocorp.com | |
${res} | Does Location Contain | robocorp |
Does page contain expected text
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
text | str | null |
text
page should contain this
Examples
Open Available Browser | https://google.com | |
${res} | Does Page Contain | Gmail |
Does page contain expected element
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, ShadowRoot, str | null | |
count | int, None | None |
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 expected image
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, ShadowRoot, str | null |
locator
element locator
Examples
Open Available Browser | https://google.com | |
${res} | Does Page Contain Image |
Does table cell contain expected text
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, ShadowRoot, str | null | |
row | int | null | |
column | int | null | |
expected | str | null |
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 expected text
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, ShadowRoot, str | null | |
column | int | null | |
expected | str | null |
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 row contain expected text
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, ShadowRoot, str | null | |
row | int | null | |
expected | str | null |
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 |
Double clicks the element identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
See the Locating elements section for details about the locator syntax.
Drags the element identified by locator
into the target
element.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
target | WebElement, str | null |
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 |
Drags the element identified with locator
by xoffset/yoffset
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
xoffset | int | null | |
yoffset | int | null |
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 |
Verifies element identified by locator
contains expected attribute value.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
attribute | str | null | |
expected | None, str | null | |
message | str, None | None |
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.
Verifies that element identified by locator
is disabled.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
This keyword considers also elements that are read-only to be disabled.
See the Locating elements section for details about the locator syntax.
Verifies that element identified by locator
is enabled.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
This keyword considers also elements that are read-only to be disabled.
See the Locating elements section for details about the locator syntax.
Verifies that element identified by locator
is focused.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
See the Locating elements section for details about the locator syntax.
New in SeleniumLibrary 3.0.
Verifies that the element identified by locator
is visible.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None |
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.
Verifies that element locator
contains text expected
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
expected | None, str | null | |
message | str, None | None | |
ignore_case | bool | False |
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.
Verifies that the element identified by locator
is NOT visible.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None |
Passes if the element does not exists. See Element Should Be Visible for more information about visibility and supported arguments.
Verifies that element locator
does not contain text expected
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
expected | None, str | null | |
message | str, None | None | |
ignore_case | bool | False |
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.
Verifies that element locator
contains exact the text expected
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
expected | None, str | null | |
message | str, None | None | |
ignore_case | bool | False |
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.
Verifies that element locator
does not contain exact the text not_expected
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
not_expected | None, str | null | |
message | str, None | None | |
ignore_case | bool | False |
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
Executes asynchronous JavaScript code with possible arguments.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
code | WebElement, str | null |
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 |
Executes Chromium DevTools Protocol commands
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
command | null | ||
parameters | null |
Works only with Chromium-based browsers!
For more information, available commands and parameters, see: https://chromedevtools.github.io/devtools-protocol/
command
command to execute as string
parameters
parameters for command as a dictionary
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 |
Executes the given JavaScript code with possible arguments.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
code | WebElement, str | null |
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]); |
Verifies that frame identified by locator
contains text
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
text | str | null | |
loglevel | str | TRACE |
See the Locating elements section for details about the locator syntax.
See Page Should Contain for an explanation about the loglevel
argument.
Gets the currently stored value for chain_delay_value in timestr format.
Returns a list containing ids of all links found in current page.
If a link has no id, an empty string will be in the list instead.
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
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
Returns information of cookie with name
as an object.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
name | str | null |
If no cookie is found with name
, keyword fails. The cookie object contains details about the cookie. Attributes available in the object are documented in the table below.
Attribute | Explanation |
---|---|
name | The name of a cookie. |
value | Value of the cookie. |
path | Indicates a URL path, for example / . |
domain | The domain, the cookie is visible to. |
secure | When true, the cookie is only used with HTTPS connections. |
httpOnly | When true, the cookie is not accessible via JavaScript. |
expiry | Python datetime object indicating when the cookie expires. |
extra | Possible attributes outside of the WebDriver specification |
See the WebDriver specification for details about the cookie information. Notice that expiry
is specified as a datetime object, not as seconds since Unix Epoch like WebDriver natively does.
In some cases, example when running a browser in the cloud, it is possible that the cookie contains other attributes than is defined in the WebDriver specification. These other attributes are available in an extra
attribute in the cookie object and it contains a dictionary of the other attributes. The extra
attribute is new in SeleniumLibrary 4.0.
Examples
Add Cookie | foo | bar |
${cookie} = | Get Cookie | foo |
Should Be Equal | ${cookie.name} | foo |
Should Be Equal | ${cookie.value} | bar |
Should Be True | ${cookie.expiry.year} > 2017 |
New in SeleniumLibrary 3.0.
Returns all cookies of the current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
as_dict | bool | False |
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
Returns the value of attribute
from the element locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
attribute | str | null |
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.
Returns the number of elements matching locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
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.
Returns width and height of the element identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
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 |
Return dictionary containing element status of:
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, ShadowRoot, str | null |
- 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} |
Returns the horizontal position of the element identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
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.
Returns all labels or values of selection list locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
values | bool | False |
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.
Returns the current browser window URL.
Returns and logs URLs of all windows of the selected browser.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
browser | str | CURRENT |
Browser Scope:
The browser
argument specifies the browser that shall return its windows information.
browser
can beindex_or_alias
like in Switch Browser.
- If
browser
isCURRENT
(default, case-insensitive) the currently active browser is selected.
- If
browser
isALL
(case-insensitive) the window information of all windows of all opened browsers are returned.
Returns the label of selected option from selection list locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
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.
Returns labels of selected options from selection list locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
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.
Returns the value of selected option from selection list locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
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.
Returns values of selected options from selection list locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
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.
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.
Gets the timeout to wait for a page load to complete before throwing an error.
The value is returned as a human-readable string like 1 second
.
See the Page load section above for more information.
New in SeleniumLibrary 6.1
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.
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.
Returns the currently active browser session id.
New in SeleniumLibrary 3.2
Returns the entire HTML source of the current page or frame.
Returns contents of a table cell.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, None, str | null | |
row | int | null | |
column | int | null | |
loglevel | str | TRACE |
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 SeleniumTestability plugin status
Returns the text value of the element identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
See the Locating elements section for details about the locator syntax.
Returns the title of the current page.
Returns the value attribute of the element identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
See the Locating elements section for details about the locator syntax.
Returns the vertical position of the element identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
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.
Returns the first Element
matching the given locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, ShadowRoot, str | null | |
parent | WebElement, ShadowRoot, None | None | |
shadow | bool | False |
With the parent
parameter you can optionally specify a parent to start the search from. Set shadow
to True
if you're targeting and expecting a shadow root in return. Read more on the shadow root: https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot
See the Locating elements section for details about the locator syntax.
Returns a list of WebElement objects matching the locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
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.
Returns all child window handles of the selected browser as a list.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
browser | str | CURRENT |
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.
Returns and logs id attributes of all windows of the selected browser.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
browser | str | CURRENT |
How to select the browser
scope of this keyword, see Get Locations.
Returns and logs names of all windows of the selected browser.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
browser | str | CURRENT |
How to select the browser
scope of this keyword, see Get Locations.
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 |
Returns current window width and height as integers.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
inner | bool | False |
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 |
Returns and logs titles of all windows of the selected browser.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
browser | str | CURRENT |
How to select the browser
scope of this keyword, see Get Locations.
Simulates the user clicking the back button on their browser.
Navigates the current browser window to the provided url
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
url | str | null |
Handles the current alert and returns its message.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
action | str | ACCEPT | |
timeout | timedelta, None | None |
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. pressOk
. Default.DISMISS
: Dismiss the alert i.e. pressCancel
.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 all matching elements by locator.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, ShadowRoot, str | null | |
width | str | 2px | |
style | str | dotted | |
color | str | blue |
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 |
Types the given password into the text field identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
password | str | null | |
clear | bool | True |
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.
Types the given text
into the text field identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
text | str | null | |
clear | bool | True |
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
Types the given text
into an input field in an alert.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
text | str | null | |
action | str | ACCEPT | |
timeout | timedelta, None | None |
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.
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 |
---|---|---|---|
text | str, None | None | |
action | str | ACCEPT |
Other possible actions are DISMISS and LEAVE.
text
check if alert text is matching to this, if None will check if alert is present at all
action
possible action if alert is present, default ACCEPT
Examples
${res} | Is Alert Present | alert message |
Is element attribute equal to expected value
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, ShadowRoot, str | null | |
attribute | str | null | |
expected | str | null |
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 text expected
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, ShadowRoot, str | null | |
expected | str | null | |
ignore_case | bool | False |
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 current URL expected url
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
url | str | null |
url
expected current URL
Examples
Open Available Browser | https://www.robocorp.com | |
${res} | Is Location | https://www.robocorp.com |
Verifies selection list locator
has expected
options selected.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
expected | str | null |
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 |
Verifies selection list locator
has no options selected.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
See the Locating elements section for details about the locator syntax.
Verifies that the current URL is exactly url
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
url | str | null | |
message | str, None | None |
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.
Verifies that the current URL contains expected
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
expected | str | null | |
message | str, None | None |
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.
Logs and returns the current browser window URL.
Logs and returns the HTML source of the current page or frame.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
loglevel | str | INFO |
The loglevel
argument defines the used log level. Valid log levels are WARN
, INFO
(default), DEBUG
, TRACE
and NONE
(no logging).
Logs and returns the title of the current page.
Maximizes current browser window.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
args | null | ||
force | bool | False | |
kwargs | null |
The window won't be maximized in headless mode since there's no way to know the screen size to set the window size to in the absence of an UI. Use the Set Window Size
keyword with a specific side or set the force param to True if you still want to enforce this undefined behaviour.
Simulates pressing the left mouse button on the element locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
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.
Simulates a mouse down event on an image identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
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
.
Simulates a mouse down event on a link identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
See the Locating elements section for details about the locator syntax. When using the default locator strategy, links are searched using id
, name
, href
and the link text.
Simulates moving the mouse away from the element locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
See the Locating elements section for details about the locator syntax.
Simulates hovering the mouse over the element locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
See the Locating elements section for details about the locator syntax.
Simulates releasing the left mouse button on the element locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
See the Locating elements section for details about the locator syntax.
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 |
---|---|---|---|
url | str, None | None | |
use_profile | bool | False | |
headless | bool, str | AUTO | |
maximized | bool | False | |
browser_selection | Any | AUTO | |
alias | str, None | None | |
profile_name | str, None | None | |
profile_path | str, None | None | |
preferences | dict, None | None | |
proxy | str, None | None | |
user_agent | str, None | None | |
download | Any | AUTO | |
options | ArgOptions, str, Dict[str, str | List | Dict], None | None | |
port | int, None | None |
Currently supported browsers: Chrome, Firefox, Edge, ChromiumEdge, Safari, Ie
Optionally can be given a url
as the first argument, to open the browser directly to the given page.
Returns either a generated index or a custom alias
for the browser instance. The returned value can be used to refer to that specific browser instance in other keywords.
If the browser should start in a maximized window, this can be enabled with the argument maximized
, but is disabled by default.
For certain applications it might also be required to force a certain user-agent string for Selenium, which can be overridden with the user_agent
argument.
WebDriver creation can be customized with options
. This accepts a class instance (e.g. ChromeOptions
), a string like add_argument("--incognito");set_capability("acceptInsecureCerts", True) or even a simple dictionary like: {"arguments": ["--incognito"], "capabilities": {"acceptInsecureCerts": True}}
A custom port
can be provided to start the browser webdriver without a randomly picked one. Make sure you provide every time a unique system-available local port if you plan to have multiple browsers being controlled in parallel.
For incompatible web apps designed to work in Internet Explorer only, Edge can run in IE mode by simply setting ie in the browser_selection
param. Robot example: https://github.com/robocorp/example-ie-mode-edge
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 |
Open Available Browser | ${URL} | options=add_argument("user-data-dir=path/to/data");add_argument("--incognito") | |
Open Available Browser | ${URL} | port=${8888} |
Browser order
The default order of supported browsers is based on the operating system and is as follows:
Platform | Default order |
Windows | Chrome, Firefox, Edge |
Linux | Chrome, Firefox, Edge |
Darwin | Chrome, Firefox, Edge, Safari |
The order can be overridden with a custom list by using the argument browser_selection
. The argument can be either a comma-separated string or a list object.
Example:
Open Available Browser | ${URL} | browser_selection=ie |
Webdriver download
The library can (if requested) automatically download webdrivers for all the supported browsers. This can be controlled with the argument download
.
If the value is False
, it will only attempt to start webdrivers found from the system PATH.
If the value is True
, it will download a webdriver that matches the current browser.
By default the argument has the value AUTO
, which means it first attempts to use webdrivers found in PATH and if that fails forces a webdriver download.
Opening process
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, e.g. a container or if the RPA_HEADLESS_MODE env var is set to a number different than 0.
Chromium options
Some features are currently available only for Chromium-based browsers. This includes using an existing user profile. By default Selenium uses a new profile for each session, but it can use an existing one by enabling the use_profile
argument.
If a custom profile is stored somewhere outside of the default location, the path to the profiles directory and the name of the profile can be controlled with profile_path
and profile_name
respectively. Keep in mind that the profile_path
for the Chrome browser for e.g. ends usually with "Chrome", "User Data" or "google-chrome" (based on platform) and the profile_name
is a directory relative to profile_path
, usually named "Profile 1", "Profile 2" etc. (and not as your visible name in the Chrome browser). Similar behavior is observed with Edge as well.
Example:
Open Available Browser | https://www.robocorp.com | use_profile=${True} | ||
Open Available Browser | https://www.robocorp.com | use_profile=${True} | profile_name=Default | |
Open Available Browser | https://www.robocorp.com | use_profile=${True} | profile_name=Profile 2 | |
Open Available Browser | https://www.robocorp.com | use_profile=${True} | profile_name=Profile 1 | profile_path=path/to/custom/user_data_dir |
Profile preferences can be further overridden with the preferences
argument by giving a dictionary of key/value pairs.
Chromium-based browsers can additionally connect through a proxy
, which should be given as either a local or remote address.
Opens a new browser instance to the optional url
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
url | str, None | None | |
browser | str | firefox | |
alias | str, None | None | |
remote_url | bool, str | False | |
desired_capabilities | dict, None, str | None | |
ff_profile_dir | FirefoxProfile, str, None | None | |
options | ArgOptions, str, Dict[str, str | List | Dict], None | None | |
service_log_path | str, None | None | |
executable_path | str, None | None |
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 |
To be able to actually use one of these browsers, you need to have a matching Selenium browser driver available. See the project documentation for more details. Headless Firefox and Headless Chrome are new additions in SeleniumLibrary 3.1.0 and require Selenium 3.8.0 or newer.
After opening the browser, it is possible to use optional url
to navigate the browser to the desired address.
Optional alias
is an alias given for this browser instance and it can be used for switching between browsers. When same alias
is given with two Open Browser keywords, the first keyword will open a new browser, but the second one will switch to the already opened browser and will not open a new browser. The alias
definition overrules browser
definition. When same alias
is used but a different browser
is defined, then switch to a browser with same alias is done and new browser is not opened. An alternative approach for switching is using an index returned by this keyword. These indices start from 1, are incremented when new browsers are opened, and reset back to 1 when Close All Browsers is called. See Switch Browser for more information and examples.
Optional remote_url
is the URL for a Selenium Grid.
Optional desired_capabilities
is deprecated and will be ignored. Capabilities of each individual browser is now done through options or services. Please refer to those arguments for configuring specific browsers.
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. 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:
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.
Opens a Chrome browser.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
url | str | null | |
use_profile | bool | False | |
headless | bool, str | AUTO | |
maximized | bool | False | |
alias | str, None | None | |
profile_name | str, None | None | |
profile_path | str, None | None | |
preferences | dict, None | None | |
proxy | str, None | None | |
user_agent | str, None | None |
See Open Available Browser
for a full descriptions of the arguments.
Opens the Chrome browser in headless mode.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
url | str | null |
url
URL to open
Examples
${idx} = | Open Headless Chrome Browser | https://www.google.com |
Opens an URL with te user's default browser.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
url | str | null | |
tab | True |
The browser opened with this keyword is not accessible with Selenium. To interact with the opened browser it is possible to use RPA.Desktop
or RPA.Windows
library keywords.
The keyword Attach Chrome Browser can be used to access an already open browser with Selenium keywords.
Read more: https://robocorp.com/docs/development-guide/browser/how-to-attach-to-running-chrome-browser
url
URL to open tab
defines is url is opened in a tab (defaults to True
) or in new window (if set to False
)
Examples
Open User Browser | https://www.google.com?q=rpa | |
Open User Browser | https://www.google.com?q=rpa | tab=${False} |
Verifies that current page contains text
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
text | str | null | |
loglevel | str | TRACE |
If this keyword fails, it automatically logs the page source using the log level specified with the optional loglevel
argument. Valid log levels are TRACE
(default), DEBUG
, INFO
, WARN
, and NONE
. If the log level is NONE
or below the current active log level the source will not be logged.
Verifies button locator
is found from current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None | |
loglevel | str | TRACE |
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
.
Verifies checkbox locator
is found from the current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None | |
loglevel | str | TRACE |
See Page Should Contain Element for an explanation about message
and loglevel
arguments.
See the Locating elements section for details about the locator syntax.
Verifies that element locator
is found on the current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None | |
loglevel | str | TRACE | |
limit | int, None | None |
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.
Verifies image identified by locator
is found from current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None | |
loglevel | str | TRACE |
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.
Verifies link identified by locator
is found from current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None | |
loglevel | str | TRACE |
See the Locating elements section for details about the locator syntax. When using the default locator strategy, links are searched using id
, name
, href
and the link text.
See Page Should Contain Element for an explanation about message
and loglevel
arguments.
Verifies selection list locator
is found from current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None | |
loglevel | str | TRACE |
See Page Should Contain Element for an explanation about message
and loglevel
arguments.
See the Locating elements section for details about the locator syntax.
Verifies radio button locator
is found from current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None | |
loglevel | str | TRACE |
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
.
Verifies text field locator
is found from current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None | |
loglevel | str | TRACE |
See Page Should Contain Element for an explanation about message
and loglevel
arguments.
See the Locating elements section for details about the locator syntax.
Verifies the current page does not contain text
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
text | str | null | |
loglevel | str | TRACE |
See Page Should Contain for an explanation about the loglevel
argument.
Verifies button locator
is not found from current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None | |
loglevel | str | TRACE |
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
.
Verifies checkbox locator
is not found from the current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None | |
loglevel | str | TRACE |
See Page Should Contain Element for an explanation about message
and loglevel
arguments.
See the Locating elements section for details about the locator syntax.
Verifies that element locator
is not found on the current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None | |
loglevel | str | TRACE |
See the Locating elements section for details about the locator syntax.
See Page Should Contain for an explanation about message
and loglevel
arguments.
Verifies image identified by locator
is not found from current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None | |
loglevel | str | TRACE |
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.
Verifies link identified by locator
is not found from current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None | |
loglevel | str | TRACE |
See the Locating elements section for details about the locator syntax. When using the default locator strategy, links are searched using id
, name
, href
and the link text.
See Page Should Contain Element for an explanation about message
and loglevel
arguments.
Verifies selection list locator
is not found from current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None | |
loglevel | str | TRACE |
See Page Should Contain Element for an explanation about message
and loglevel
arguments.
See the Locating elements section for details about the locator syntax.
Verifies radio button locator
is not found from current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None | |
loglevel | str | TRACE |
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
.
Verifies text field locator
is not found from current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
message | str, None | None | |
loglevel | str | TRACE |
See Page Should Contain Element for an explanation about message
and loglevel
arguments.
See the Locating elements section for details about the locator syntax.
DEPRECATED in SeleniumLibrary 4.0. use Press Keys instead.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
key | str | null |
Simulates the user pressing key(s) to an element or on the active browser.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, None, str | None | |
keys | str | null |
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. |
Print the current page to a PDF document using Chrome's DevTools.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
output_path | str, None | None | |
params | dict, None | None |
Attention: With some older browsers, this may work in headless mode only! For a list of supported parameters see: https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF Returns the output PDF file path.
Parameter output_path
specifies the file path for the generated PDF document. By default, it is saved to the output folder with the default name of out.pdf. Parameter params
specify parameters for the browser printing method. By default, it uses the following values: ` { "landscape": False, "displayHeaderFooter": False, "printBackground": True, "preferCSSPageSize": True, } `
Verifies radio button group group_name
is set to value
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
group_name | str | null | |
value | str | null |
group_name
is the name
of the radio button group.
Verifies radio button group group_name
has no selection.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
group_name | str | null |
group_name
is the name
of the radio button group.
Sets the keyword to execute, when a SeleniumLibrary keyword fails.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
keyword | str, None | null |
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 PythonNone
to disable the functionality. - Return Python
None
when the functionality was disabled earlier. In previous versions special valueNo Keyword
was returned and it could not be used to restore the original state.
Simulates user reloading page.
Removes a previously added custom location strategy.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
strategy_name | str | null |
See Custom locators for information on how to create and use custom strategies.
Capture page and/or element screenshot.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, ShadowRoot, str, None | None | |
filename | str, None |
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 |
Scrolls the element identified by locator
into view.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
See the Locating elements section for details about the locator syntax.
New in SeleniumLibrary 3.2.0
Selects all options from multi-selection list locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
See the Locating elements section for details about the locator syntax.
Selects the checkbox identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
Does nothing if checkbox is already selected.
See the Locating elements section for details about the locator syntax.
Sets frame identified by locator
as the current frame.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
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 |
Selects options from selection list locator
by indexes
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
indexes | str | null |
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.
Selects options from selection list locator
by labels
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
labels | str | null |
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.
Selects options from selection list locator
by values
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
values | str | null |
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.
Sets the radio button group group_name
to value
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
group_name | str | null | |
value | str | null |
The radio button to be selected is located by two arguments:
group_name
is the name of the radio button group.value
is theid
orvalue
attribute of the actual radio button.
Examples:
Select Radio Button | size | XL |
Select Radio Button | contact |
Sets the duration of delay in ActionChains() used by SeleniumLibrary.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
value | timedelta | null |
The value can be given as a number that is considered to be seconds or as a human-readable string like 1 second
.
Value is always stored as milliseconds internally.
The previous value is returned and can be used to restore the original value later if needed.
Sets the implicit wait value used by Selenium.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
value | timedelta | null |
Same as Set Selenium Implicit Wait but only affects the current browser.
Set a custom browser download directory.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
directory | str, None | None | |
download_pdf | bool | True |
This has to be called before opening the browser and it works with the following keywords:
Open Available Browser
Open Chrome Browser
Open Headless Chrome Browser
Supported browsers: Chrome, Edge, Firefox.
If the downloading doesn't work (file is not found on disk), try using the browser in non-headless (headful) mode when opening it. (headless=${False}
)
Parameter directory
sets a path for downloads, defaults to None
, which means that this setting is removed and the default location will be used. Parameter download_pdf
will download a PDF file instead of previewing it within browser's internal viewer when this is set to True
. (enabled by default)
Examples
Set Download Directory | ${OUTPUT_DIR} | |
Open Available Browser | https://cdn.robocorp.com/legal/Robocorp-EULA-v1.0.pdf | |
@{files} = | List Files In Directory | ${OUTPUT_DIR} |
Log List | ${files} |
Sets a value
for the attribute
in the element locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, ShadowRoot, str | null | |
attribute | str | null | |
value | str | null |
See the Locating elements section for details about the locator syntax.
Examples
Set Element Attribute | css:h1 | class | active |
Sets the focus to the element identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
See the Locating elements section for details about the locator syntax.
Prior to SeleniumLibrary 3.0 this keyword was named Focus.
Sets the directory for captured screenshots.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
path | None, str | null |
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.
Sets the implicit wait value used by Selenium.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
value | timedelta | null |
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} |
Sets the page load timeout value used by Selenium.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
value | timedelta | null |
The value can be given as a number that is considered to be seconds or as a human-readable string like 1 second
. The previous value is returned and can be used to restore the original value later if needed.
In contrast to Set Selenium Timeout and Set Selenium Implicit Wait this keywords sets the time for Webdriver to wait until page is loaded before throwing an error.
See the Page load section above for more information.
Examples
${orig page load timeout} = | Set Selenium Page Load Timeout | 30 seconds |
Open page that loads slowly | ||
Set Selenium Page Load Timeout | ${orig page load timeout} |
New in SeleniumLibrary 6.1
Sets the delay that is waited after each Selenium command.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
value | timedelta | null |
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 |
Sets the timeout that is used by various keywords.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
value | timedelta | null |
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} |
Sets window position using x
and y
coordinates.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
x | int | null | |
y | int | null |
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 |
Sets current windows size to given width
and height
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
width | int | null | |
height | int | null | |
inner | bool | False |
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 |
Simulates event
on the element identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
event | str | null |
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.
Submits a form identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, None, str | None |
If locator
is not given, first form on the page is submitted.
See the Locating elements section for details about the locator syntax.
Switches between active browsers using index_or_alias
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
index_or_alias | str | null |
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} |
Switches to browser window matching locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | list, str | MAIN | |
timeout | str, None | None | |
browser | str | CURRENT |
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 formatstrategy:value
(recommended) orstrategy=value
. Supported strategies arename
,title
, andurl
. 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
isNEW
(case-insensitive), the latest opened window is selected. It is an error if this is the same as the current window.
- If the
locator
isMAIN
(default, case-insensitive), the main window is selected.
- If the
locator
isCURRENT
(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
isCURRENT
(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 aliasself
for selecting the current window. Support for these aliases was removed in SeleniumLibrary 3.2.
Verifies table cell contains text expected
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, None, str | null | |
row | int | null | |
column | int | null | |
expected | str | null | |
loglevel | str | TRACE |
See Get Table Cell that this keyword uses internally for an explanation about accepted arguments.
Verifies table column contains text expected
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, None, str | null | |
column | int | null | |
expected | str | null | |
loglevel | str | TRACE |
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.
Verifies table header contains text expected
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, None, str | null | |
expected | str | null | |
loglevel | str | TRACE |
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.
Verifies that table row contains text expected
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, None, str | null | |
row | int | null | |
expected | str | null | |
loglevel | str | TRACE |
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.
Verifies table contains text expected
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, None, str | null | |
expected | str | null | |
loglevel | str | TRACE |
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.
Verifies text area locator
contains text expected
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
expected | str | null | |
message | str, None | None |
message
can be used to override default error message.
See the Locating elements section for details about the locator syntax.
Verifies text area locator
has exactly text expected
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
expected | str | null | |
message | str, None | None |
message
can be used to override default error message.
See the Locating elements section for details about the locator syntax.
Verifies text field locator
contains text expected
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
expected | str | null | |
message | str, None | None |
message
can be used to override the default error message.
See the Locating elements section for details about the locator syntax.
Verifies text field locator
has exactly text expected
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
expected | str | null | |
message | str, None | None |
message
can be used to override default error message.
See the Locating elements section for details about the locator syntax.
Verifies that the current page title equals title
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
title | str | null | |
message | str, None | None |
The message
argument can be used to override the default error message.
message
argument is new in SeleniumLibrary 3.1.
Unselects all options from multi-selection list locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
See the Locating elements section for details about the locator syntax.
New in SeleniumLibrary 3.0.
Removes the selection of checkbox identified by locator
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null |
Does nothing if the checkbox is not selected.
See the Locating elements section for details about the locator syntax.
Sets the main frame as the current frame.
In practice cancels the previous Select Frame call.
Unselects options from selection list locator
by indexes
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
indexes | str | null |
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.
Unselects options from selection list locator
by labels
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
labels | str | null |
This keyword works only with multi-selection lists.
See the Locating elements section for details about the locator syntax.
Unselects options from selection list locator
by values
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, str | null | |
values | str | null |
This keyword works only with multi-selection lists.
See the Locating elements section for details about the locator syntax.
Click button identified by locator
, once it becomes visible.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, ShadowRoot, str | null | |
modifier | str, None | None |
locator
element locator
modifier
press given keys while clicking the element, e.g. CTRL
Examples
Click Button When Visible | //button[@class="mybutton"] |
Waits until condition
is true or timeout
expires.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
condition | str | null | |
timeout | timedelta, None | None | |
error | str, None | None |
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" |
Waits until the element locator
contains text
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, None, str | null | |
text | str | null | |
timeout | timedelta, None | None | |
error | str, None | None |
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.
Waits until the element locator
does not contain text
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, None, str | null | |
text | str | null | |
timeout | timedelta, None | None | |
error | str, None | None |
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.
Waits until the element locator
is enabled.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, None, str | null | |
timeout | timedelta, None | None | |
error | str, None | None |
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.
Waits until the element locator
is not visible.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, None, str | null | |
timeout | timedelta, None | None | |
error | str, None | None |
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.
Waits until the element locator
is visible.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, None, str | null | |
timeout | timedelta, None | None | |
error | str, None | None |
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.
Waits until the current URL contains expected
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
expected | str | null | |
timeout | timedelta, None | None | |
message | str, None | None |
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
Waits until the current URL does not contains location
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
location | str | null | |
timeout | timedelta, None | None | |
message | str, None | None |
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
Waits until the current URL is expected
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
expected | str | null | |
timeout | timedelta, None | None | |
message | str, None | None |
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
Waits until the current URL is not location
.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
location | str | null | |
timeout | timedelta, None | None | |
message | str, None | None |
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
Waits until text
appears on the current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
text | str | null | |
timeout | timedelta, None | None | |
error | str, None | None |
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.
Waits until the element locator
appears on the current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, None, str | null | |
timeout | timedelta, None | None | |
error | str, None | None | |
limit | int, None | None |
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
Waits until text
disappears from the current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
text | str | null | |
timeout | timedelta, None | None | |
error | str, None | None |
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.
Waits until the element locator
disappears from the current page.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
locator | WebElement, None, str | null | |
timeout | timedelta, None | None | |
error | str, None | None | |
limit | int, None | None |
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