Browser library is a browser automation library for Robot Framework.
This is the keyword documentation for Browser library. For information about installation, support, and more please visit the project pages. For more information about Robot Framework itself, see robotframework.org.
Browser library uses Playwright Node module to automate Chromium, Firefox and WebKit with a single library.
Table of contents
- Browser, Context and Page
- Automatic page and context closing
- Finding elements
- Assertions
- Implicit waiting
- Experimental: Re-using same node process
- Extending Browser library with a JavaScript module
- Importing
- Keywords
Browser, Context and Page
Browser library works with three different layers that build on each other: Browser, Context and Page.
Browsers
A browser can be started with one of the three different engines Chromium, Firefox or Webkit.
Supported Browsers
Browser | Browser with this engine |
chromium |
Google Chrome, Microsoft Edge (since 2020), Opera |
firefox |
Mozilla Firefox |
webkit |
Apple Safari, Mail, AppStore on MacOS and iOS |
Since Playwright comes with a pack of builtin binaries for all browsers, no additional drivers e.g. geckodriver are needed.
All these browsers that cover more than 85% of the world wide used browsers, can be tested on Windows, Linux and MacOS. There is no need for dedicated machines anymore.
A browser process is started headless
(without a GUI) by default. Run New Browser with specified arguments if a browser with a GUI is requested or if a proxy has to be configured. A browser process can contain several contexts.
Contexts
A context corresponds to set of independent incognito pages in a browser that share cookies, sessions or profile settings. Pages in two separate contexts do not share cookies, sessions or profile settings. Compared to Selenium, these do not require their own browser process. To get a clean environment a test can just open a new context. Due to this new independent browser sessions can be opened with Robot Framework Browser about 10 times faster than with Selenium by just opening a New Context within the opened browser.
To make pages in the same suite share state, use the same context by opening the context with New Context on suite setup.
The context layer is useful e.g. for testing different users sessions on the same webpage without opening a whole new browser context. Contexts can also have detailed configurations, such as geo-location, language settings, the viewport size or color scheme. Contexts do also support http credentials to be set, so that basic authentication can also be tested. To be able to download files within the test, the acceptDownloads
argument must be set to True
in New Context keyword. A context can contain different pages.
Pages
A page does contain the content of the loaded web site and has a browsing history. Pages and browser tabs are the same.
Typical usage could be:
* Test Cases * Starting a browser with a page New Browser chromium headless=false New Context viewport={'width': 1920, 'height': 1080} New Page https://marketsquare.github.io/robotframework-browser/Browser.html Get Title == Browser
The Open Browser keyword opens a new browser, a new context and a new page. This keyword is useful for quick experiments or debugging sessions.
When a New Page is called without an open browser, New Browser and New Context are executed with default values first.
Each Browser, Context and Page has a unique ID with which they can be addressed. A full catalog of what is open can be received by Get Browser Catalog as dictionary.
Automatic page and context closing
Controls when contexts and pages are closed during the test execution.
If automatic closing level is TEST, contexts and pages that are created during a single test are automatically closed when the test ends. Contexts and pages that are created during suite setup are closed when the suite teardown ends.
If automatic closing level is SUITE, all contexts and pages that are created during the test suite are closed when the suite teardown ends.
If automatic closing level is MANUAL, nothing is closed automatically during the test execution is ongoing.
All browsers are automatically closed, always and regardless of the automatic closing level at the end of the test execution. This will also close all remaining pages and contexts.
Automatic closing can be configured or switched off with the auto_closing_level library import parameter.
See: Importing
Finding elements
All keywords in the library that need to interact with an element on a web page take an argument typically named selector
that specifies how to find the element. Keywords can find elements with strict mode. If strict mode is true and locator finds multiple elements from the page, keyword will fail. If keyword finds one element, keyword does not fail because of strict mode. If strict mode is false, keyword does not fail if selector points many elements. Strict mode is enabled by default, but can be changed in library importing or Set Strict Mode keyword. Keyword documentation states if keyword uses strict mode. If keyword does not state that is used strict mode, then strict mode is not applied for the keyword. For more details, see Playwright strict documentation.
Selector strategies that are supported by default are listed in the table below.
Strategy | Match based on | Example |
---|---|---|
css |
CSS selector. | css=.class > \#login_btn |
xpath |
XPath expression. | xpath=//input[@id="login_btn"] |
text |
Browser text engine. | text=Login |
id |
Element ID Attribute. | id=login_btn |
CSS Selectors can also be recorded with Record selector keyword.
Explicit Selector Strategy
The explicit selector strategy is specified with a prefix using syntax strategy=value
. Spaces around the separator are ignored, so css=foo
, css= foo
and css = foo
are all equivalent.
Implicit Selector Strategy
The default selector strategy is css.
If selector does not contain one of the know explicit selector strategies, it is assumed to contain css selector.
Selectors that are starting with //
or ..
are considered as xpath selectors.
Selectors that are in quotes are considered as text selectors.
Examples:
Click span > button.some_class # This is equivalent Click css=span > button.some_class # to this. Click //span/button[@class="some_class"] Click xpath=//span/button[@class="some_class"] Click "Login" Click text="Login"
CSS
As written before, the default selector strategy is css. See css selector for more information.
Any malformed selector not starting with //
or ..
nor starting and ending with a quote is assumed to be a css selector.
Note that #
is a comment character in Robot Framework syntax and needs to be escaped like \#
to work as a css ID selector.
Examples:
Click span > button.some_class Get Text \#username_field == George
XPath
XPath engine is equivalent to Document.evaluate. Example: xpath=//html/body//span[text()="Hello World"]
.
Malformed selector starting with //
or ..
is assumed to be an xpath selector. For example, //html/body
is converted to xpath=//html/body
. More examples are displayed in Examples.
Note that xpath does not pierce shadow_roots.
Text
Text engine finds an element that contains a text node with the passed text. For example, Click text=Login
clicks on a login button, and Wait For Elements State text="lazy loaded text"
waits for the "lazy loaded text" to appear in the page.
Text engine finds fields based on their labels in text inserting keywords.
Malformed selector starting and ending with a quote (either "
or '
) is assumed to be a text selector. For example, Click "Login"
is converted to Click text="Login"
. Be aware that these leads to exact matches only! More examples are displayed in Examples.
Insensitive match
By default, the match is case-insensitive, ignores leading/trailing whitespace and searches for a substring. This means text= Login
matches <button>Button loGIN (click me)</button>
.
Exact match
Text body can be escaped with single or double quotes for precise matching, insisting on exact match, including specified whitespace and case. This means text="Login "
will only match <button>Login </button>
with exactly one space after "Login". Quoted text follows the usual escaping rules, e.g. use \"
to escape double quote in a double-quoted string: text="foo\"bar"
.
RegEx
Text body can also be a JavaScript-like regex wrapped in / symbols. This means text=/^hello .*!$/i
or text=/^Hello .*!$/
will match <span>Hello Peter Parker!</span>
with any name after Hello
, ending with !
. The first one flagged with i
for case-insensitive. See https://regex101.com for more information about RegEx.
Button and Submit Values
Input elements of the type button and submit are rendered with their value as text, and text engine finds them. For example, text=Login
matches <input type=button value="Login">
.
Cascaded selector syntax
Browser library supports the same selector strategies as the underlying Playwright node module: xpath, css, id and text. The strategy can either be explicitly specified with a prefix or the strategy can be implicit.
A major advantage of Browser is, that multiple selector engines can be used within one selector. It is possible to mix XPath, CSS and Text selectors while selecting a single element.
Selectors are strings that consists of one or more clauses separated by >>
token, e.g. clause1 >> clause2 >> clause3
. When multiple clauses are present, next one is queried relative to the previous one's result. Browser library supports concatenation of different selectors separated by >>
.
For example:
Highlight Elements "Hello" >> ../.. >> .select_button Highlight Elements text=Hello >> xpath=../.. >> css=.select_button
Each clause contains a selector engine name and selector body, e.g. engine=body
. Here engine
is one of the supported engines (e.g. css or a custom one). Selector body
follows the format of the particular engine, e.g. for css engine it should be a css selector. Body format is assumed to ignore leading and trailing white spaces, so that extra whitespace can be added for readability. If selector engine needs to include >>
in the body, it should be escaped inside a string to not be confused with clause separator, e.g. text="some >> text"
.
Selector engine name can be prefixed with *
to capture element that matches the particular clause instead of the last one. For example, css=article >> text=Hello
captures the element with the text Hello
, and *css=article >> text=Hello
(note the *) captures the article element that contains some element with the text Hello.
For convenience, selectors in the wrong format are heuristically converted to the right format. See Implicit Selector Strategy
Examples
Get Element css=div Get Element //html/body/div Get Element text=foo Get Element xpath=//html/body/div >> css=span Get Element div Get Element //html/body/div Get Element "foo" Get Element \#foo >> css=span:nth-child(2n+1) >> div Get Element id=foo >> css=span:nth-child(2n+1) >> div
Be aware that using #
as a starting character in Robot Framework would be interpreted as comment. Due to that fact a #id
must be escaped as \#id
.
Frames
By default, selector chains do not cross frame boundaries. It means that a simple CSS selector is not able to select and element located inside an iframe or a frameset. For this use case, there is a special selector >>>
which can be used to combine a selector for the frame and a selector for an element inside a frame.
Given this simple pseudo html snippet:
<iframe id="iframe" src="src.html"> #document <!DOCTYPE html> <html> <head></head> <body> <button id="btn">Click Me</button> </body> </html> </iframe>
Here's a keyword call that clicks the button inside the frame.
Click id=iframe >>> id=btn
The selectors on the left and right side of >>>
can be any valid selectors. The selector clause directly before the frame opener >>>
must select the frame element. Frame selection is the only place where Library modifies the selector, as explained in above. In all cases, library does not alter selector in any way, instead it is passed as is to Playwright side.
WebComponents and Shadow DOM
Playwright and so also Browser are able to do automatic piercing of Shadow DOMs and therefore are the best automation technology when working with WebComponents.
Also other technologies claim that they can handle Shadow DOM and Web Components. However, non of them do pierce shadow roots automatically, which may be inconvenient when working with Shadow DOM and Web Components.
For that reason, css engine pierces shadow roots. More specifically, every Descendant combinator pierces an arbitrary number of open shadow roots, including the implicit descendant combinator at the start of the selector.
That means, it is not necessary to select each shadow host, open its shadow root and select the next shadow host until you reach the element that should be controlled.
CSS:light
css:light
engine is equivalent to Document.querySelector and behaves according to the CSS spec. However, it does not pierce shadow roots.
css
engine first searches for elements in the light dom in the iteration order, and then recursively inside open shadow roots in the iteration order. It does not search inside closed shadow roots or iframes.
Examples:
<article> <div>In the light dom</div> <div slot='myslot'>In the light dom, but goes into the shadow slot</div> <open mode shadow root> <div class='in-the-shadow'> <span class='content'> In the shadow dom <open mode shadow root> <li id='target'>Deep in the shadow</li> </open mode shadow root> </span> </div> <slot name='myslot'></slot> </open mode shadow root> </article>
Note that <open mode shadow root>
is not an html element, but rather a shadow root created with element.attachShadow({mode: 'open'})
.
- Both
"css=article div"
and"css:light=article div"
match the first<div>In the light dom</div>
. - Both
"css=article > div"
and"css:light=article > div"
match twodiv
elements that are direct children of thearticle
. "css=article .in-the-shadow"
matches the<div class='in-the-shadow'>
, piercing the shadow root, while"css:light=article .in-the-shadow"
does not match anything."css:light=article div > span"
does not match anything, because both light-domdiv
elements do not contain aspan
."css=article div > span"
matches the<span class='content'>
, piercing the shadow root."css=article > .in-the-shadow"
does not match anything, because<div class='in-the-shadow'>
is not a direct child ofarticle
"css:light=article > .in-the-shadow"
does not match anything."css=article li#target"
matches the<li id='target'>Deep in the shadow</li>
, piercing two shadow roots.
text:light
text
engine open pierces shadow roots similarly to css
, while text:light
does not. Text engine first searches for elements in the light dom in the iteration order, and then recursively inside open shadow roots in the iteration order. It does not search inside closed shadow roots or iframes.
id, data-testid, data-test-id, data-test and their :light counterparts
Attribute engines are selecting based on the corresponding attribute value. For example: data-test-id=foo
is equivalent to css=[data-test-id="foo"]
, and id:light=foo
is equivalent to css:light=[id="foo"]
.
Element reference syntax
It is possible to get a reference to a Locator by using Get Element and Get Elements keywords. Keywords do not save reference to an element in the HTML document, instead it saves reference to a Playwright Locator. In nutshell Locator captures the logic of how to retrieve that element from the page. Each time action is performed, locator re-searches the elements in the page. This reference can be used as a first part of a selector by using a special selector syntax element=. like this:
${ref}= Get Element .some_class Click ${ref} >> .some_child # Locator searches an element from the page. Click ${ref} >> .other_child # Locator searches again an element from the page.
The .some_child and .other_child selectors in the example are relative to the element referenced by ${ref}. Please note that frame piercing is not possible with element reference.
Assertions
Keywords that accept arguments assertion_operator
<AssertionOperator> and assertion_expected
can optionally assert that a specified condition holds. Keywords will return the value even when the assertion is performed by the keyword.
Assert will retry and fail only after a specified timeout. See Importing and retry_assertions_for
(default is 1 second) for configuring this timeout.
Currently supported assertion operators are:
Operator | Alternative Operators | Description | Validate Equivalent |
---|---|---|---|
== |
equal , should be |
Checks if returned value is equal to expected value. | value == expected |
!= |
inequal , should not be |
Checks if returned value is not equal to expected value. | value != expected |
> |
greater than |
Checks if returned value is greater than expected value. | value > expected |
>= |
Checks if returned value is greater than or equal to expected value. | value >= expected |
|
< |
less than |
Checks if returned value is less than expected value. | value < expected |
<= |
Checks if returned value is less than or equal to expected value. | value <= expected |
|
*= |
contains |
Checks if returned value contains expected value as substring. | expected in value |
not contains |
Checks if returned value does not contain expected value as substring. | expected in value |
|
^= |
should start with , starts |
Checks if returned value starts with expected value. | re.search(f"^{expected}", value) |
$= |
should end with , ends |
Checks if returned value ends with expected value. | re.search(f"{expected}$", value) |
matches |
Checks if given RegEx matches minimum once in returned value. | re.search(expected, value) |
|
validate |
Checks if given Python expression evaluates to True . |
||
evaluate |
then |
When using this operator, the keyword does return the evaluated Python expression. |
Currently supported formatters for assertions are:
Formatter | Description |
---|---|
normalize spaces |
Substitutes multiple spaces to single space from the value |
strip |
Removes spaces from the beginning and end of the value |
apply to expected |
Applies rules also for the expected value |
Formatters are applied to the value before assertion is performed and keywords returns a value where rule is applied. Formatter is only applied to the value which keyword returns and not all rules are valid for all assertion operators. If apply to expected
formatter is defined, then formatters are then formatter are also applied to expected value.
By default, keywords will provide an error message if an assertion fails. Default error message can be overwritten with a message
argument. The message
argument accepts {value}, {value_type}, {expected} and {expected_type} format options. The {value} is value returned by the keyword and the {expected} is expected value defined by the user, usually value in the assertion_expected
argument. The {value_type} and {expected_type} are the type definitions from {value} and {expected} arguments. In similar fashion as Python type returns type definition. Assertions will retry until timeout
has expired if they do not pass.
The assertion assertion_expected
value is not converted by the library and is used as is. Therefore when assertion is made, the assertion_expected
argument value and value returned the keyword must have same type. If types are not same, assertion will fail. Example Get Text always returns a string and has to be compared with a string, even the returned value might look like a number.
Other Keywords have other specific types they return. Get Element Count always returns an integer. Get Bounding Box and Get Viewport Size can be filtered. They return a dictionary without filter and a number when filtered. These Keywords do automatic conversion for the expected value if a number is returned.
* < less or greater > With Strings* Comparisons of strings with greater than
or less than
compares each character, starting from 0 regarding where it stands in the code page. Example: A < Z
, Z < a
, ac < dc It does never compare the length of elements. Neither lists nor strings. The comparison stops at the first character that is different. Examples: `'abcde' < 'abd'
, '100.000' < '2'
In Python 3 and therefore also in Browser it is not possible to compare numbers with strings with a greater or less operator. On keywords that return numbers, the given expected value is automatically converted to a number before comparison.
The getters Get Page State and Get Browser Catalog return a dictionary. Values of the dictionary can directly asserted. Pay attention of possible types because they are evaluated in Python. For example:
Get Page State validate 2020 >= value['year'] # Comparison of numbers Get Page State validate "IMPORTANT MESSAGE!" == value['message'] # Comparison of strings
The 'then' or 'evaluate' closure
Keywords that accept arguments assertion_operator
and assertion_expected
can optionally also use then
or evaluate
closure to modify the returned value with BuiltIn Evaluate. Actual value can be accessed with value
.
For example Get Title then 'TITLE: '+value
. See Builtin Evaluating expressions for more info on the syntax.
Examples
Get Title equal Page Title Get Title ^= Page Get Style //*[@id="div-element"] width > 100 Get Title matches \\w+\\s\\w+ Get Title validate value == "Login Page" Get Title evaluate value if value == "some value" else "something else"
Implicit waiting
Browser library and Playwright have many mechanisms to help in waiting for elements. Playwright will auto-wait before performing actions on elements. Please see Auto-waiting on Playwright documentation for more information.
On top of Playwright auto-waiting Browser assertions will wait and retry for specified time before failing any Assertions. Time is specified in Browser library initialization with retry_assertions_for
.
Browser library also includes explicit waiting keywords such as Wait for Elements State if more control for waiting is needed.
Experimental: Re-using same node process
Browser library integrated nodejs and python. NodeJS side can be also executed as a standalone process. Browser libraries running on the same machine can talk to that instead of starting new node processes. This can speed execution when running tests parallel. To start node side run on the directory when Browser package is PLAYWRIGHT_BROWSERS_PATH=0 node Browser/wrapper/index.js PORT
. PORT
is port you want to use for the node process. To execute tests then with pabot for example do ROBOT_FRAMEWORK_BROWSER_NODE_PORT=PORT pabot ..
.
Extending Browser library with a JavaScript module
Browser library can be extended with JavaScript. Module must be in CommonJS format that Node.js uses. You can translate your ES6 module to Node.js CommonJS style with Babel. Many other languages can be also translated to modules that can be used from Node.js. For example TypeScript, PureScript and ClojureScript just to mention few.
async function myGoToKeyword(page, args, logger, playwright) { logger(args.toString()) playwright.coolNewFeature() return await page.goto(args[0]); }
page
: the playwright Page object.
args
: list of strings from Robot Framework keyword call.
!! A BIT UNSTABLE AND SUBJECT TO API CHANGES !! logger
: callback function that takes strings as arguments and writes them to robot log. Can be called multiple times.
playwright
: playwright module (* from 'playwright'). Useful for integrating with Playwright features that Browser library doesn't support with it's own keywords. API docs
Example module.js
async function myGoToKeyword(page, args) { await page.goto(args[0]); return await page.title(); } exports.__esModule = true; exports.myGoToKeyword = myGoToKeyword;
Example Robot Framework side
* Settings * Library Browser jsextension=${CURDIR}/module.js * Test Cases * Hello New Page ${title}= myGoToKeyword https://playwright.dev Should be equal ${title} Playwright
Also selector syntax can be extended with a custom selector using a js module
Example module keyword for custom selector registering
async function registerMySelector(page, args, log, playwright) { playwright.selectors.register("myselector", () => ({ // Returns the first element matching given selector in the root's subtree. query(root, selector) { return root.querySelector(a[data-title="${selector}"]); }, // Returns all elements matching given selector in the root's subtree. queryAll(root, selector) { return Array.from(root.querySelectorAll(a[data-title="${selector}"])); } })); return 1; } exports.__esModule = true; exports.registerMySelector = registerMySelector;