RPA.Browser.Playwright
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
- Scope Setting
- Extending Browser library with a JavaScript module
- Plugins
- 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 a 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 user 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:
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 a 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 while 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 strict mode is used, 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:
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:
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:
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 the 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 an 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
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 an 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:
Here's a keyword call that clicks the button inside the frame.
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 Browser Library modifies the selector, as explained in above. In all cases, the library does not alter the selector in any way, instead it is passed as is to the 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, none of them do pierce shadow roots automatically, which may be inconvenient when working with Shadow DOM and Web Components.
For that reason, the 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:
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 an action is performed, the 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:
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 messages can be overwritten with a message
argument. The message
argument accepts {value}, {value_type}, {expected} and {expected_type} format options. The {value} is the value returned by the keyword and the {expected} is the expected value defined by the user, usually the 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 the same type. If types are not the 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 a 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:
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
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. The 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 the Browser package is PLAYWRIGHT_BROWSERS_PATH=0 node Browser/wrapper/index.js PORT
.
PORT
is the 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 ..
.
Scope Setting
Some keywords which manipulates library settings have a scope argument. With that scope argument one can set the "live time" of that setting. Available Scopes are: Global, Suite and Test/Task See Scope. Is a scope finished, this scoped setting, like timeout, will no longer be used.
Live Times:
- A Global scope will live forever until it is overwritten by another Global scope. Or locally temporarily overridden by a more narrow scope.
- A Suite scope will locally override the Global scope and live until the end of the Suite within it is set, or if it is overwritten by a later setting with Global or same scope. Children suite does inherit the setting from the parent suite but also may have its own local Suite setting that then will be inherited to its children suites.
- A Test or Task scope will be inherited from its parent suite but when set, lives until the end of that particular test or task.
A new set higher order scope will always remove the lower order scope which may be in charge. So the setting of a Suite scope from a test, will set that scope to the robot file suite where that test is and removes the Test scope that may have been in place.
Extending Browser library with a JavaScript module
Browser library can be extended with JavaScript. The 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.
Functions can contain any number of arguments and arguments may have default values.
There are some reserved arguments that are not accessible from Robot Framework side. They are injected to the function if they are in the arguments:
page
: the playwright Page object.
args
: the rest of values from Robot Framework keyword call *args
.
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
also argument name self
can not be used.
Example module.js
Example Robot Framework side
Also selector syntax can be extended with a custom selector using a js module
Example module keyword for custom selector registering
Plugins
Browser library offers plugins as a way to modify and add library keywords and modify some of the internal functionality without creating a new library or hacking the source code. See plugin API documentation for further details.
Importing
Browser library can be taken into use with optional arguments:
Argument | Description |
---|---|
*deprecated_pos_args | Positional arguments are deprecated for Library import. Please use named arguments instead. We will remove positional arguments after RoboCon 2023 Online in March. Old positional order was: timeout , enable_playwright_debug , auto_closing_level , retry_assertions_for , run_on_failure , external_browser_executable , jsextension , enable_presenter_mode , playwright_process_port , strict , show_keyword_call_banner . |
auto_closing_level | Configure context and page automatic closing. Default is TEST , for more details, see AutoClosingLevel |
enable_playwright_debug | Enable low level debug information from the playwright tool. Mainly Useful for the library developers and for debugging purposes. |
enable_presenter_mode | Automatic highlights to interacted components, slowMo and a small pause at the end. Can be enabled by giving True or can be customized by giving a dictionary: {"duration": "2 seconds", "width": "2px", "style": "dotted", "color": "blue"} Where duration is time format in Robot Framework format, defaults to 2 seconds. width is width of the marker in pixels, defaults the 2px. style is the style of border, defaults to dotted. color is the color of the marker, defaults to blue. |
external_browser_executable | Dict mapping name of browser to path of executable of a browser. Will make opening new browsers of the given type use the set executablePath. Currently only configuring of chromium to a separate executable (chrome, chromium and Edge executables all work with recent versions) works. |
jsextension | Path to Javascript module exposed as extra keywords. The module must be in CommonJS. |
playwright_process_port | Experimental reusing of playwright process. playwright_process_port is preferred over environment variable ROBOT_FRAMEWORK_BROWSER_NODE_PORT . See Experimental: Re-using same node process for more details. |
retry_assertions_for | Timeout for retrying assertions on keywords before failing the keywords. This timeout starts counting from the first failure. Global timeout will still be in effect. This allows stopping execution faster to assertion failure when element is found fast. |
run_on_failure | Sets the keyword to execute in case of a failing Browser keyword. It can be the name of any keyword. If the keyword has arguments those must be separated with two spaces for example My keyword \ arg1 \ arg2 . If no extra action should be done after a failure, set it to None or any other robot falsy value. Run on failure is not applied when library methods are executed directly from Python. |
selector_prefix | Prefix for all selectors. This is useful when you need to use add an iframe selector before each selector. |
show_keyword_call_banner | If set to True , will show a banner with the keyword name and arguments before the keyword is executed at the bottom of the page. If set to False , will not show the banner. If set to None, which is the default, will show the banner only if the presenter mode is enabled. Get Page Source and Take Screenshot will not show the banner, because that could negatively affect your test cases/tasks. This feature may be super helpful when you are debugging your tests and using tracing from New Context or Video recording features. |
strict | If keyword selector points multiple elements and keywords should interact with one element, keyword will fail if strict mode is true. Strict mode can be changed individually in keywords or by `et Strict Mode`` keyword. |
timeout | Timeout for keywords that operate on elements. The keywords will wait for this time for the element to appear into the page. Defaults to "10s" => 10 seconds. |
plugins | Allows extending the Browser library with external Python classes. |
Old deprecated argument order: timeout
, enable_playwright_debug
, auto_closing_level
, retry_assertions_for
, run_on_failure
, external_browser_executable
, jsextension
, enable_presenter_mode
, playwright_process_port
, strict
, show_keyword_call_banner