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

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

Structure:

BrowserA
           Window 1  (location=https://robotframework.org/)
           Window 2  (location=https://robocon.io/)
           Window 3  (location=https://github.com/robotframework/)

BrowserB
           Window 1  (location=https://github.com/)

Example:

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

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

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

Boolean arguments

Some keywords accept arguments that are handled as Boolean values true or false. If such an argument is given as a string, it is considered false if it is either empty or case-insensitively equal to false, no, off, 0 or none. Other strings are considered true regardless of their value and other argument types are tested using the same rules as in Python.

True examples:

Set Screenshot Directory ${RESULTS} persist=True # Strings are generally true.
Set Screenshot Directory ${RESULTS} persist=yes # Same as the above.
Set Screenshot Directory ${RESULTS} persist=${TRUE} # Python True is true.
Set Screenshot Directory ${RESULTS} persist=${42} # Numbers other than 0 are true.

False examples:

Set Screenshot Directory ${RESULTS} persist=False # String false is false.
Set Screenshot Directory ${RESULTS} persist=no # Also string no is false.
Set Screenshot Directory ${RESULTS} persist=NONE # String NONE is false.
Set Screenshot Directory ${RESULTS} persist=${EMPTY} # Empty string is false.
Set Screenshot Directory ${RESULTS} persist=${FALSE} # Python False is false.
Set Screenshot Directory ${RESULTS} persist=${NONE} # Python None is false.