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

Browser library works with three different layers that build on each other: Browser, Context and Page.


A browser can be started with one of the three different engines Chromium, Firefox or Webkit.

Supported Browsers

BrowserBrowser with this engine
chromiumGoogle Chrome, Microsoft Edge (since 2020), Opera
firefoxMozilla Firefox
webkitApple 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.


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.


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

StrategyMatch based onExample
cssCSS selector.css=.class > \#login_btn
xpathXPath expression.xpath=//input[@id="login_btn"]
textBrowser text engine.text=Login
idElement 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.


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"


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.


Click span > button.some_class Get Text \#username_field == George


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


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


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.


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:

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


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

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


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:

OperatorAlternative OperatorsDescriptionValidate Equivalent
==equal, equals, should beChecks if returned value is equal to expected value.value == expected
!=inequal, should not beChecks if returned value is not equal to expected value.value != expected
>greater thanChecks 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 thanChecks if returned value is less than expected value.value < expected
<=Checks if returned value is less than or equal to expected value.value <= expected
*=containsChecks if returned value contains expected value as substring.expected in value
not containsChecks if returned value does not contain expected value as substring.expected in value
^=should start with, startsChecks if returned value starts with expected value.re.search(f"^{expected}", value)
$=should end with, endsChecks if returned value ends with expected value.re.search(f"{expected}$", value)
matchesChecks if given RegEx matches minimum once in returned value.re.search(expected, value)
validateChecks if given Python expression evaluates to True.
evaluatethenWhen using this operator, the keyword does return the evaluated Python expression.

Currently supported formatters for assertions are:

normalize spacesSubstitutes multiple spaces to single space from the value
stripRemoves spaces from the beginning and end of the value
case insensitiveConverts value to lower case before comparing
apply to expectedApplies 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:

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.


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

Experimental: Provide parameters to node process

Browser library is integrated with NodeJSand and Python. Browser library starts a node process, to communicate Playwright API in NodeJS side. It is possible to provide parameters for the started node process by defining ROBOT_FRAMEWORK_BROWSER_NODE_DEBUG_OPTIONS environment variable, before starting the test execution. Example: ROBOT_FRAMEWORK_BROWSER_NODE_DEBUG_OPTIONS=--inspect;robot path/to/tests. There can be multiple arguments defined in the environment variable and arguments must be separated with comma.

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.

async function myGoToKeyword(url, args, page, logger, playwright) { logger(args.toString()) playwright.coolNewFeature() return await page.goto(url); }

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

async function myGoToKeyword(pageUrl, page) { await page.goto(pageUrl); 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(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;


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.

Automatic headless detection is supported when opening a new browser.


Browser library can be taken into use with optional arguments:

auto_closing_levelConfigure context and page automatic closing. Default is TEST, for more details, see AutoClosingLevel
enable_playwright_debugEnable low level debug information from the playwright to playwright-log.txt file. Mainly Useful for the library developers and for debugging purposes. Will og everything as plain text, also including secrects.
enable_presenter_modeAutomatic 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_executableDict 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.
jsextensionPath to Javascript modules exposed as extra keywords. The modules must be in CommonJS. It can either be a single path, a comma-separated lists of path or a real list of strings
playwright_process_portExperimental 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.
pluginsAllows extending the Browser library with external Python classes. Can either be a single class/module, a comma-separated list or a real list of strings
retry_assertions_forTimeout 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_failureSets 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_prefixPrefix for all selectors. This is useful when you need to use add an iframe selector before each selector.
show_keyword_call_bannerIf 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.
strictIf 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.
timeoutTimeout 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.