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.

Browser, Context and Page
Finding elements
Assertions
Automatic page and context closing
Extending Browser library with a JavaScript module
Importing
Keywords
Data types

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. Theres is not 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.

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.

If there is no browser opened in Suite Setup and New Page is executed in Test Setup, the corresponding pages and context is closed automatically at the end of the test. The browser process remains open and will be closed at the end of execution.

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.

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.

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`

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.

Example:

Click  span > button.some_class

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.

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 concatination of different selectors seperated 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 usecase, 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.

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 nessesary 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 two div elements that are direct children of the article.
"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-dom div elements do not contain a span.
"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 of article
"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 an element by using Get Element keyword. 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          element=${ref} >> .some_child

The .some_child selector in the example is relative to the element referenced by ${ref}.

Assertions

Keywords that accept arguments assertion_operator <AssertionOperator> and assertion_expected can optionally assert. 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`
`^=`	`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.

Bu default the keywords will provide an error message if the assertion fails, but 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 the value returned by the keyword and the {expected} is the 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 returnd 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 autoconvert the expected value if a number is returned.

* < less or greater > With Strings* Compairisons of strings with greater than or less than compares each character, starting from 0 reagarding 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']                     # Compairsion of numbers
Get Page State    validate    "IMPORTANT MESSAGE!" == value['message']  # Compairsion 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"

Automatic page and context closing

Library will close pages and contexts that are created during test execution. Pages and contexts created before test in Suite Setup or Suite Teardown will be closed after that suite. This will remove the burden of closing these resources in teardowns.

Browsers will not be automatically closed. A browser is expensive to create and should be reused.

Automatic closing can be configured or switched off with the auto_closing_level library parameter.

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

RPA.Browser.Playwright

Table of contents

Browser, Context and Page

Browsers

Supported Browsers

Contexts

Pages

Finding elements

Explicit Selector Strategy

Implicit Selector Strategy

CSS

XPath

Text

Insensitive match

Exact match

RegEx

Button and Submit Values

Cascaded selector syntax

Examples

Frames

WebComponents and Shadow DOM

CSS:light

text:light

id, data-testid, data-test-id, data-test and their :light counterparts

Element reference syntax

Assertions

The 'then' or 'evaluate' closure

Examples

Automatic page and context closing

Extending Browser library with a JavaScript module

Example module.js

Example Robot Framework side