Python API¶

Browser.Selenium¶

exception RPA.Browser.Selenium.BrowserNotFoundError¶

Bases: ValueError

Raised when browser can’t be initialized.

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class RPA.Browser.Selenium.Selenium(*args, **kwargs)¶

Bases: SeleniumLibrary.SeleniumLibrary

Browser is a web testing library for Robot Framework, based on the popular SeleniumLibrary.

It uses the Selenium WebDriver modules internally to control a web browser. See http://seleniumhq.org for more information about Selenium in general.

= Locating elements =

All keywords in the browser library that need to interact with an element on a web page take an argument typically named locator that specifies how to find the element. Most often the locator is given as a string using the locator syntax described below, but using WebElements is possible too.

== Locator syntax ==

Finding elements can be done using different strategies such as the element id, XPath expressions, or CSS selectors. The strategy can either be explicitly specified with a prefix or the strategy can be implicit.

=== Default locator strategy ===

By default, locators are considered to use the keyword specific default locator strategy. All keywords support finding elements based on id and name attributes, but some keywords support additional attributes or other values that make sense in their context. For example, Click Link supports the href attribute and the link text and addition to the normal id and name.

Examples:

Click Element | example | # Match based on id or name.            |
Click Link    | example | # Match also based on link text and href.   |
Click Button  | example | # Match based on id, name or value. |

If a locator accidentally starts with a prefix recognized as explicit locator strategy or implicit XPath strategy, it is possible to use the explicit default prefix to enable the default strategy.

Examples:

Click Element | name:foo         | # Find element with name foo.               |
Click Element | default:name:foo | # Use default strategy with value name:foo. |
Click Element | //foo            | # Find element using XPath //foo.           |
Click Element | default: //foo   | # Use default strategy with value //foo.    |

=== Explicit locator strategy ===

The explicit locator strategy is specified with a prefix using either syntax strategy:value or strategy=value. The former syntax is preferred because the latter is identical to Robot Framework’s [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#named-argument-syntax| named argument syntax] and that can cause problems. Spaces around the separator are ignored, so id:foo, id: foo and id : foo are all equivalent.

Locator strategies that are supported by default are listed in the table below. In addition to them, it is possible to register custom locators.

= Strategy = |          = Match based on =         |         = Example =            |
id           | Element id.                     | id:example                 |
name         | name attribute.                 | name:example               |
identifier   | Either id or name.          | identifier:example         |
class        | Element class.                  | class:example              |
tag          | Tag name.                           | tag:div                    |
xpath        | XPath expression.                   | xpath://div[@id="example"] |
css          | CSS selector.                       | css:div#example            |
dom          | DOM expression.                     | dom:document.images[5]     |
link         | Exact text a link has.              | link:The example           |
partial link | Partial link text.                  | partial link:he ex         |
sizzle       | Sizzle selector deprecated.         | sizzle:div.example         |
jquery       | jQuery expression.                  | jquery:div.example         |
default      | Keyword specific default behavior.  | default:example            |

See the Default locator strategy section below for more information about how the default strategy works. Using the explicit default prefix is only necessary if the locator value itself accidentally matches some of the explicit strategies.

Different locator strategies have different pros and cons. Using ids, either explicitly like id:foo or by using the default locator strategy simply like foo, is recommended when possible, because the syntax is simple and locating elements by id is fast for browsers. If an element does not have an id or the id is not stable, other solutions need to be used. If an element has a unique tag name or class, using tag, class or css strategy like tag:h1, class:example or css:h1.example is often an easy solution. In more complex cases using XPath expressions is typically the best approach. They are very powerful but a downside is that they can also get complex.

Examples:

Click Element | id:foo                      | # Element with id ‘foo’. |
Click Element | css:div#foo h1              | # h1 element under div with id ‘foo’. |
Click Element | xpath: //div[@id=”foo”]//h1 | # Same as the above using XPath, not CSS. |
Click Element | xpath: //*[contains(text(), “example”)] | # Element containing text ‘example’. |

NOTE:

Using the sizzle strategy or its alias jquery requires that the system under test contains the jQuery library.

=== Implicit XPath strategy ===

If the locator starts with // or (//, the locator is considered to be an XPath expression. In other words, using //div is equivalent to using explicit xpath://div.

Examples:

Click Element | //div[@id=”foo”]//h1 |

Click Element | (//div)[2] |

=== Chaining locators ===

It’s possible to chain multiple locators together as a single locator. Each chained locator must start with a locator strategy. Chained locators must be separated with a single space, two greater than characters, and followed with a space. It’s also possible to mix different locator strategies, such as css or xpath. Also, a list can also be used to specify multiple locators, for instance when the chaining separator would conflict with the actual locator, or when an existing web element is used as a base.

Although all locators support chaining, some locator strategies don’t chain properly with previous values. This is because some locator strategies use JavaScript to find elements and JavaScript is executed for the whole browser context and not for the element found by the previous locator. Locator strategies that support chaining are the ones that are based on the Selenium API, such as xpath or css, but for example chaining is not supported by sizzle or jquery.

Examples: | Click Element | css:.bar >> xpath://a | # To find a link which is present inside an element with class “bar” |

List examples: | ${locator_list} = | Create List | css:div#div_id | xpath://*[text(), ” >> “] | | Page Should Contain Element | ${locator_list} | | | | ${element} = | Get WebElement | xpath://*[text(), ” >> “] | | | ${locator_list} = | Create List | css:div#div_id | ${element} | | Page Should Contain Element | ${locator_list} | | |

== Using WebElements ==

In addition to specifying a locator as a string, it is possible to use Selenium’s WebElement objects. This requires first getting a WebElement, for example, by using the Get WebElement keyword.

${elem} = | Get WebElement | id:example |

Click Element | ${elem} | |

== Custom locators ==

If more complex lookups are required than what is provided through the default locators, custom lookup strategies can be created. Using custom locators is a two part process. First, create a keyword that returns a WebElement that should be acted on:

Custom Locator Strategy | [Arguments] | ${browser} | ${locator} | ${tag} | ${constraints} |

| ${element}= | Execute Javascript | return window.document.getElementById(‘${locator}’); |

| [Return] | ${element} |

This keyword is a reimplementation of the basic functionality of the id locator where ${browser} is a reference to a WebDriver instance and ${locator} is the name of the locator strategy. To use this locator, it must first be registered by using the Add Location Strategy keyword:

Add Location Strategy | custom | Custom Locator Strategy |

The first argument of Add Location Strategy specifies the name of the strategy and it must be unique. After registering the strategy, the usage is the same as with other locators:

Click Element | custom:example |

See the Add Location Strategy keyword for more details.

= Browser and Window =

There is different conceptual meaning when this library talks about windows or browsers. This chapter explains those differences.

== Browser ==

When Open Browser or Create WebDriver keyword is called, it will create a new Selenium WebDriver instance by using the [https://www.seleniumhq.org/docs/03_webdriver.jsp|Selenium WebDriver] API. In this library’s terms, a new browser is created. It is possible to start multiple independent browsers (Selenium Webdriver instances) at the same time, by calling Open Browser or Create WebDriver multiple times. These browsers are usually independent of each other and do not share data like cookies, sessions or profiles. Typically when the browser starts, it creates a single window which is shown to the user.

== Window ==

Windows are the part of a browser that loads the web site and presents it to the user. All content of the site is the content of the window. Windows are children of a browser. In this context a browser is a synonym for WebDriver instance. One browser may have multiple windows. Windows can appear as tabs, as separate windows or pop-ups with different position and size. Windows belonging to the same browser typically share the sessions detail, like cookies. If there is a need to separate sessions detail, example login with two different users, two browsers (Selenium WebDriver instances) must be created. New windows can be opened example by the application under test or by example Execute Javascript keyword:

Execute Javascript window.open() # Opens a new window with location about:blank

The example below opens multiple browsers and windows, to demonstrate how the different keywords can be used to interact with browsers, and windows attached to these browsers.

Example: | Open Browser | https://robotframework.org | ${BROWSER} | alias=BrowserA | # BrowserA with first window is opened. | | Execute Javascript | window.open() | | | # In BrowserA second window is opened. | | Switch Window | locator=NEW | | | # Switched to second window in BrowserA | | Go To | https://robocon.io | | | # Second window navigates to robocon site. | | Execute Javascript | window.open() | | | # In BrowserA third window is opened. | | ${handle} | Switch Window | locator=NEW | | # Switched to third window in BrowserA | | Go To | https://github.com/robotframework/ | | | # Third windows goes to robot framework github site. | | Open Browser | https://github.com | ${BROWSER} | alias=BrowserB | # BrowserB with first windows is opened. | | ${location} | Get Location | | | # ${location} is: https://www.github.com | | Switch Window | ${handle} | browser=BrowserA | | # BrowserA second windows is selected. | | ${location} | Get Location | | | # ${location} = https://robocon.io/ | | @{locations 1} | Get Locations | | | # By default, lists locations under the currectly active browser (BrowserA). | | @{locations 2} | Get Locations | browser=ALL | | # By using browser=ALL argument keyword list all locations from all browsers. |

The above example, @{locations 1} contains the following items: https://robotframework.org/, https://robocon.io/ and https://github.com/robotframework/’. The @{locations 2} contains the following items: https://robotframework.org/, https://robocon.io/, https://github.com/robotframework/’ and ‘https://github.com/.

= Timeouts, waits, and delays =

This section discusses different ways how to wait for elements to appear on web pages and to slow down execution speed otherwise. It also explains the time format that can be used when setting various timeouts, waits, and delays.

== Timeout ==

This library contains various keywords that have an optional timeout argument that specifies how long these keywords should wait for certain events or actions. These keywords include, for example, Wait ... keywords and keywords related to alerts. Additionally Execute Async Javascript. Although it does not have timeout, argument, uses a timeout to define how long asynchronous JavaScript can run.

The default timeout these keywords use can be set globally either by using the Set Selenium Timeout keyword or with the timeout argument when importing the library. See time format below for supported timeout syntax.

== Implicit wait ==

Implicit wait specifies the maximum time how long Selenium waits when searching for elements. It can be set by using the Set Selenium Implicit Wait keyword or with the implicit_wait argument when importing the library. See [https://www.seleniumhq.org/docs/04_webdriver_advanced.jsp|Selenium documentation] for more information about this functionality.

See time format below for supported syntax.

== Selenium speed ==

Selenium execution speed can be slowed down globally by using Set Selenium speed keyword. This functionality is designed to be used for demonstrating or debugging purposes. Using it to make sure that elements appear on a page is not a good idea. The above-explained timeouts and waits should be used instead.

See time format below for supported syntax.

== Time format ==

All timeouts and waits can be given as numbers considered seconds (e.g. 0.5 or 42) or in Robot Framework’s time syntax (e.g. 1.5 seconds or 1 min 30 s). For more information about the time syntax see the [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format|Robot Framework User Guide].

= Run-on-failure functionality =

This library has a handy feature that it can automatically execute a keyword if any of its own keywords fails. By default, it uses the Capture Page Screenshot keyword, but this can be changed either by using the Register Keyword To Run On Failure keyword or with the run_on_failure argument when importing the library. It is possible to use any keyword from any imported library or resource file.

The run-on-failure functionality can be disabled by using a special value NOTHING or anything considered false (see Boolean arguments) such as NONE.

= Auto closing browser =

By default browser instances created during task execution are closed at the end of the task. This can be prevented with the auto_close argument when importing the library.

Value needs to be set to False or anything considered false (see Boolean arguments).

AVAILABLE_OPTIONS = {'chrome': 'ChromeOptions', 'firefox': 'FirefoxOptions'}¶

ROBOT_LIBRARY_DOC_FORMAT = 'ROBOT'¶

ROBOT_LIBRARY_SCOPE = 'GLOBAL'¶

ROBOT_LIBRARY_VERSION = '5.1.3'¶

add_library_components(library_components)¶

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

Attach to an existing instance of Chrome or Chromium.

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

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

Example:

Attach Chrome Browser | port=9222 |

clear_all_highlights()¶: Remove all highlighting made by Highlight Elements.

click_button_when_visible(locator: str, modifier: Optional[str] = None) → None¶

Click button identified by locator, once it becomes visible.

locator element locator

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

Example:

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

click_element_if_visible(locator: str) → None¶

Click element if it is visible

locator element locator

Example:

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

click_element_when_visible(locator: str, modifier: Optional[str] = None, action_chain: bool = False) → None¶

Click element identified by locator, once it becomes visible.

locator element locator

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

action_chain store action in Selenium ActionChain queue

Example:

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

does_alert_contain(text: str = None, timeout: float = None) → bool¶

Does alert contain text.

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

Example:

${res} | Does Alert Contain | alert message |

does_alert_not_contain(text: str = None, timeout: float = None) → bool¶

Does alert not contain text.

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

Example:

${res} | Does Alert Not Contain | unexpected message |

does_element_contain(locator: str, expected: str, ignore_case: bool = False) → bool¶

Does element contain expected text

locator element locator

expected expected element text

ignore_case should check be case insensitive, default False

Example:

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

does_frame_contain(locator: str, text: str) → bool¶

Does frame contain expected text

locator locator of the frame to check

text does frame contain this text

Example:

${res} | Does Frame Contain | id:myframe | secret |

does_location_contain(expected: str) → bool¶

Does current URL contain expected

expected URL should contain this

Example:

Open Available Browser | https://robocorp.com |

${res} | Does Location Contain | robocorp |

does_page_contain(text: str) → bool¶

Does page contain expected text

text page should contain this

Example:

Open Available Browser | https://google.com |

${res} | Does Page Contain | Gmail |

does_page_contain_button(locator: str) → bool¶

Does page contain expected button

locator element locator

Example:

${res} | Does Page Contain Button | search-button |

does_page_contain_checkbox(locator: str) → bool¶

Does page contain expected checkbox

locator element locator

Example:

${res} | Does Page Contain Checkbox | random-selection |

does_page_contain_element(locator: str, count: int = None) → bool¶

Does page contain expected element

locator element locator

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

Example:

${res} | Does Page Contain Element | textarea |

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

does_page_contain_image(locator: str) → bool¶

Does page contain expected image

locator element locator

Example:

Open Available Browser | https://google.com |

${res} | Does Page Contain Image | Google |

does_page_contain_link(locator: str) → bool¶

Does page contain expected link

locator element locator

Example:

${res} | Does Page Contain Link | id:submit |

does_page_contain_list(locator: str) → bool¶

Does page contain expected list

locator element locator

Example:

${res} | Does Page Contain List | class:selections |

does_page_contain_radio_button(locator: str) → bool¶

Does page contain expected radio button

locator element locator

Example:

${res} | Does Page Contain Radio Button | male |

does_page_contain_textfield(locator: str) → bool¶

Does page contain expected textfield

locator element locator

Example:

${res} | Does Page Contain Textfield | id:address |

does_table_cell_contain(locator: str, row: int, column: int, expected: str) → bool¶

Does table cell contain expected text

locator element locator for the table

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

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

expected expected text in table row

Example:

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

does_table_column_contain(locator: str, column: int, expected: str) → bool¶

Does table column contain expected text

locator element locator for the table

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

expected expected text in table column

Example:

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

does_table_contain(locator: str, expected: str) → bool¶

Does table contain expected text

locator element locator

expected expected text in table

Example:

${res} | Does Table Contain | //table | February |

does_table_footer_contain(locator: str, expected: str) → bool¶

Does table footer contain expected text

locator element locator for the table

expected expected text in table footer

Example:

${res} | Does Table Footer Contain | //table | Sum |

does_table_header_contain(locator: str, expected: str) → bool¶

Does table header contain expected text

locator element locator for the table

expected expected text in table header

Example:

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

does_table_row_contain(locator: str, row: int, expected: str) → bool¶

Does table row contain expected text

locator element locator for the table

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

expected expected text in table row

Example:

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

does_textarea_contain(locator: str, expected: str) → bool¶

Does textarea contain expected text

locator element locator

expected expected text in textarea

Example:

${res} | Does Textarea Contain | //textarea | sincerely |

does_textfield_contain(locator: str, expected: str) → bool¶

Does textfield contain expected text

locator element locator

expected expected text in textfield

Example:

${res} | Does Textfield Contain | id:lname | Last |

property driver¶

Current active driver.

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

execute_cdp(command, parameters)¶

Executes Chrome DevTools Protocol commands

Works only with Chrome/Chromium

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

command command to execute as string

parameters parameters for command as a dictionary

Example:

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 |

failure_occurred()¶

Method that is executed when a SeleniumLibrary keyword fails.

By default, executes the registered run-on-failure keyword. Libraries extending SeleniumLibrary can overwrite this hook method if they want to provide custom functionality instead.

find_element(locator: str, parent: Optional[selenium.webdriver.remote.webelement.WebElement] = None) → selenium.webdriver.remote.webelement.WebElement¶

Find element matching locator.

Parameters

locator (str or selenium.webdriver.remote.webelement.WebElement) – Locator to use when searching the element. See library documentation for the supported locator syntax.
parent (selenium.webdriver.remote.webelement.WebElement) – Optional parent WebElememt to search child elements from. By default, search starts from the root using WebDriver.

Returns

Found WebElement.

Return type

selenium.webdriver.remote.webelement.WebElement

Raises

SeleniumLibrary.errors.ElementNotFound – If element not found.

find_elements(locator: str, parent: selenium.webdriver.remote.webelement.WebElement = None) → List[selenium.webdriver.remote.webelement.WebElement]¶

Find all elements matching locator.

Parameters

locator (str or selenium.webdriver.remote.webelement.WebElement) – Locator to use when searching the element. See library documentation for the supported locator syntax.
parent (selenium.webdriver.remote.webelement.WebElement) – Optional parent WebElememt to search child elements from. By default, search starts from the root using WebDriver.

Returns

list of found WebElement or e,mpty if elements are not found.

Return type

list[selenium.webdriver.remote.webelement.WebElement]

get_browser_capabilities() → dict¶

Get dictionary of browser properties

Example:

${caps}= | Get Browser Capabilities |

get_element_status(locator: str) → dict¶

Return dictionary containing element status of:

visible

enabled

disabled

focused

locator element locator

Example:

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

get_keyword_arguments(name)¶

get_keyword_documentation(name: str) → str¶

get_keyword_names()¶

get_keyword_source(keyword_name)¶

get_keyword_tags(name: str) → list¶

get_keyword_types(name)¶

get_testability_status() → bool¶: Get SeleniumTestability plugin status

highlight_elements(locator: str, width: str = '2px', style: str = 'dotted', color: str = 'blue')¶

Highlight all matching elements by locator.

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

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

Example:

Highlight Elements | xpath://h2 |

input_text_when_element_is_visible(locator: str, text: str) → None¶

Input text into locator after it has become visible.

locator element locator

text insert text to locator

Example:

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

is_alert_present(text: str = None, action: str = 'ACCEPT') → bool¶

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

Other possible actions are DISMISS and LEAVE.

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

action possible action if alert is present, default ACCEPT

Example:

${res} | Is Alert Present | alert message |

is_checkbox_selected(locator: str) → bool¶

Is checkbox selected

locator element locator

Example:

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

is_element_attribute_equal_to(locator: str, attribute: str, expected: str) → bool¶

Is element attribute equal to expected value

locator element locator

attribute element attribute to check for

expected is attribute value equal to this

Example:

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

is_element_disabled(locator: str, missing_ok: bool = True) → bool¶

Is element disabled

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

Example:

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

is_element_enabled(locator: str, missing_ok: bool = True) → bool¶

Is element enabled

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

Example:

${res} | Is Element Enabled | input.field1 |

is_element_focused(locator: str, missing_ok: bool = True) → bool¶

Is element focused

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

Example:

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

is_element_text(locator: str, expected: str, ignore_case: bool = False) → bool¶

Is element text expected

locator element locator

expected expected element text

ignore_case should check be case insensitive, default False

Example:

${res} | Is Element Text | id:name | john doe |

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

is_element_visible(locator: str, missing_ok: bool = True) → bool¶

Is element visible

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

Example:

${res} | Is Element Visible | id:confirmation |

is_list_selected(locator: str) → bool¶

Is any option selected in the

locator element locator

Example:

${res} | Is List Selected | id:cars |

is_list_selection(locator: str, *expected: str) → bool¶

Is list selected with expected values

locator element locator

expected expected selected options

Example:

${res} | Is List Selection | id:cars | Ford |

is_location(url: str) → bool¶

Is current URL expected url

url expected current URL

Example:

Open Available Browser | https://www.robocorp.com |

${res} | Is Location | https://www.robocorp.com |

is_radio_button_selected(group_name: str) → bool¶

Is any radio button selected in the button group

group_name radio button group name

Example:

${res} | Is Radio Button Selected | group_name=gender |

is_radio_button_set_to(group_name: str, value: str) → bool¶

Is radio button group set to expected value

group_name radio button group name

value expected value

Example:

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

is_textarea_value(locator: str, expected: str) → bool¶

Is textarea matching expected value

locator element locator

expected expected textarea value

Example:

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

is_textfield_value(locator: str, expected: str) → bool¶

Is textfield value expected

locator element locator

expected expected textfield value

Example:

${res} | Is Textfield Value | id:lname | Lastname |

is_title(title: str) → bool¶

Is page title expected

title expected title value

Example:

${res} | Is Title | Webpage title text |

property location¶: Return browser location.

open_available_browser(url: Optional[str] = None, use_profile: bool = False, headless: Any = 'AUTO', maximized: bool = False, browser_selection: Any = 'AUTO', alias: Optional[str] = None, profile_name: Optional[str] = None, profile_path: Optional[str] = None, preferences: Optional[dict] = None, proxy: str = None, user_agent: Optional[str] = None, download: Any = 'AUTO') → int¶

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.

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

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

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

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

Example:

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

== Browser order ==

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

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

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

== Webdriver download ==

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

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

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

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

== Opening process ==

Parse list of preferred browser order. If not given, use values from above table.
Loop through listed browsers:
1. Set the webdriver options for the browser.
2. Download webdriver (if requested).
3. Attempt to launch the webdriver and stop the loop if successful.
Return index/alias if webdriver was created, or raise an exception if no browsers were successfully opened.

== Headless mode ==

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

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

It can be explicitly enabled or disabled with the argument headless. By default it will be disabled, unless it detects that it is running in a Linux environment without a display, i.e. a container.

== Chrome options ==

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

If a custom profile is stored somewhere outside of the default location, the path to the profiles directory and the name of the profile can be controlled with profile_path and profile_name respectively.

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

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

open_chrome_browser(url: str, use_profile: bool = False, headless: bool = False, maximized: bool = False, alias: Optional[str] = None, profile_name: Optional[str] = None, profile_path: Optional[str] = None, preferences: Optional[dict] = None, proxy: str = None, user_agent: Optional[str] = None) → int¶: Open Chrome browser. See Open Available Browser for descriptions of arguments.

open_headless_chrome_browser(url: str) → int¶

Open Chrome browser in headless mode.

url URL to open

Example:

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

open_user_browser(url: str, tab=True) → None¶

Open URL with user’s default browser

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

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

url URL to open tab defines is url is opened in a tab (default True) or

in new window (False)

Example:

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

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

print_to_pdf(output_path: str = None, params: dict = None)¶

Print the current page to a PDF document using Chromium devtools.

For supported parameters see: https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF

output_path filepath for the generated pdf. By default it is saved to: the output folder with name out.pdf.

params parameters for the Chrome print method. By default uses values:

``{: “landscape”: False, “displayHeaderFooter”: False, “printBackground”: True, “preferCSSPageSize”: True,

}``

register_driver(driver: selenium.webdriver.remote.webdriver.WebDriver, alias: str)¶

Add’s a driver to the library WebDriverCache.

Parameters

driver (selenium.webdriver.remote.webdriver.WebDriver) – Instance of the Selenium WebDriver.
alias (str) – Alias given for this WebDriver instance.

Returns

The index of the WebDriver instance.

Return type

int

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

screenshot(locator: str = None, filename: str = '') → None¶

Capture page and/or element screenshot.

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

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

Example:

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 |

set_download_directory(directory: str = None, download_pdf: bool = True) → None¶

Set browser download directory

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

wait_and_click_button(locator: str, modifier: Optional[str] = None) → None¶

Click button identified by locator, once it becomes visible.

locator element locator

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

Example:

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

RPA.Browser.Selenium.html_table(header, rows)¶: Create HTML table that can be used for logging.

RPA.Browser.Selenium.suppress_logging()¶: Suppress webdrivermanager warnings and errors in scope.