Browser library is a browser automation library for Robot Framework.
\nThis is the keyword documentation for Browser library. For installation, guides and everything else, see robotframework-browser.org. For more information about Robot Framework itself, see robotframework.org.
\nBrowser library uses Playwright Node module to automate Chromium, Firefox and WebKit with a single library.
\nBrowser library works in three layers that build on each other.
\n| Layer | \nIs | \nOpened with | \n
|---|---|---|
| Browser | \nA browser process: chromium, firefox or webkit. | \nNew Browser | \n
| Context | \nAn isolated session in that process: its own cookies, storage and permissions. Contexts share nothing with each other. | \nNew Context | \n
| Page | \nA tab, with its own content and history. Selectors resolve here. | \nNew Page | \n
Playwright brings its own browser binaries, so no separate driver is needed. A browser starts headless unless New Browser's headless argument is set to False.
| Engine | \nShips in | \n
|---|---|
chromium | \nGoogle Chrome, Microsoft Edge, Opera | \n
firefox | \nMozilla Firefox | \n
webkit | \nSafari on macOS and iOS | \n
The layers fill themselves in downwards: New Page with nothing open starts a browser and a context first, using defaults. Open Browser opens all three at once and is meant for experiments and debugging rather than for suites.
\nA context is the cheap unit of isolation \u2014 opening one is roughly a thousand times cheaper than starting a browser, so a clean session per test does not mean a new process. Context-level settings include viewport, geolocation, locale, colorScheme and httpCredentials; downloads are accepted unless acceptDownloads=False is given.
Each browser, context and page has an id. Get Browser Catalog returns everything currently open.
\nWhich layer to open for which job, and the cost of each: https://robotframework-browser.org/docs/concepts/browser-context-page
\nControls when contexts and pages are closed during the test execution.
\nIf 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, context and pages are automatically closed when test execution ends.
If automatic closing level is KEEP, nothing is closed automatically while the test execution is ongoing. Also, nothing is closed when test execution ends, including the node process. Therefore, it is users responsibility to close all browsers, context and pages and ensure that all process that are left running after the test execution end are closed. This level is only intended for test case development and must not be used when running tests in CI or similar environments.
Automatic closing can be configured or switched off with the auto_closing_level library import parameter.
\nSee: Importing
\nKeywords that act on an element take a selector argument. A selector is one or more clauses, each naming a strategy, chained with >>.
Under strict mode a selector matching more than one element fails the keyword. It is on by default, changeable in the library importing or with Set Strict Mode, and each keyword's documentation states whether it applies.
\n| Strategy | \nMatches on | \nExample | \n
|---|---|---|
role | \nARIA role, with optional accessible name. | \nrole=button[name=\"Login\"] | \n
data-testid | \ndata-testid attribute. | \ndata-testid=login | \n
text | \nText content. See Text matching. | \ntext=Login | \n
id | \nElement ID attribute. | \nid=login_btn | \n
css | \nCSS selector. | \ncss=.class > \\#login_btn | \n
xpath | \nXPath expression. | \nxpath=//input[@id=\"login_btn\"] | \n
data-test-id | \ndata-test-id attribute. | \ndata-test-id=login | \n
data-test | \ndata-test attribute. | \ndata-test=login | \n
css:light | \nAs css, but does not pierce shadow DOM. | \ncss:light=.class | \n
An attribute engine is equivalent to the matching css attribute selector: data-test-id=foo is css=[data-test-id=\"foo\"].
css:light is the only non-piercing engine still supported. All other locator, except xpath, pierce shadow DOM automatically.
Two filters narrow what a clause already matched. Filter order changes the result.
\n| Filter | \nSelects | \nExample | \n
|---|---|---|
nth | \nThe nth match, zero based. 0 first, -1 last. | \ncss=button >> nth=1 | \n
visible | \nOnly visible, or only hidden, matches. | \ncss=button >> visible=true | \n
Playwright's CSS pseudo-classes (:has(), :has-text(), :nth-match()) and its layout selectors (:right-of(), :below()) are available inside a css clause. Which strategy to prefer, and the full list with examples: https://robotframework-browser.org/docs/concepts/selectors
A strategy is named with a strategy=value prefix. Spaces around the separator are ignored, so css=foo, css= foo and css = foo are the same.
Without a prefix the strategy is inferred:
\n| Selector starts with | \nRead as | \nExample | \n
|---|---|---|
// or .. | \nxpath | \n//span/button is xpath=//span/button | \n
\" or ' | \ntext, exact | \n\"Login\" is text=\"Login\" | \n
| anything else | \ncss | \nspan > button is css=span > button | \n
Because # starts a comment in Robot Framework data, an id selector must be escaped as \\#id.
css follows the CSS selector specification and xpath the XPath specification; neither is re-documented here.
The text engine matches a text node, and the value of button and submit inputs. In keywords that insert text it also matches a field by its label.
| Form | \nMatches | \n
|---|---|
text=Login | \nSubstring, case-insensitive, leading and trailing whitespace ignored. | \n
text=\"Login \" | \nExact: case, whitespace and all. Escape a quote as \\\". | \n
text=/^Hi .*!$/i | \nJavaScript-style regular expression with flags: e.g. i for case-insensitive. | \n
Clauses are separated by >> and each searches inside the result of the previous one. The chain returns what the last clause matched; prefix a clause with * to return that one instead. A value containing >> must be quoted, as in text=\"some >> text\".
\nClick css=.checkout >> text=Confirm\nGet Element *css=article >> text=Hello # returns the article\n\n
A chain does not cross a frame boundary. >>> combines a selector for the frame element with a selector inside it; the clause immediately before >>> must select the frame itself.
\nClick id=iframe >>> id=btn\n\n
For several keywords inside one frame, set a prefix with Set Selector Prefix.
\nAll engines, except css:light and xpath, pierce open shadow roots automatically: every descendant combinator, including the implicit one at the start of a selector, crosses any number of them. Light DOM is searched first, then open shadow roots, in document order. Closed shadow roots and iframes are never entered.
Use css:light to stop at the shadow boundary. Worked examples of what each matches: https://robotframework-browser.org/docs/concepts/selectors
Get Element returns a selector string for what it matched, and Get Elements returns a list of them. They are ordinary selectors, so they go in the first clause of another selector, chained with >>:
\n${ref}= Get Element .some_class\n Click ${ref} >> .some_child\n Click ${ref} >> .other_child\n\nClauses after the reference are relative to it. Because the value is a selector rather than a captured DOM node, it is resolved from the page again on every use. A reference works like any other first clause, >>> included: if it points at an iframe, ${ref} >>> h1 crosses into it.
Keywords taking assertion_operator <AssertionOperator> and assertion_expected can assert on the value they return, and still return it. An assertion retries until it passes or retry_assertions_for expires; see Importing for that setting, which defaults to 1 second.
Currently supported assertion operators are:
\n| Operator | \nAlternative Operators | \nDescription | \nValidate Equivalent | \n
|---|---|---|---|
== | \nequal, equals, should be | \nChecks if returned value is equal to expected value. | \nvalue == expected | \n
!= | \ninequal, should not be | \nChecks if returned value is not equal to expected value. | \nvalue != expected | \n
> | \ngreater than | \nChecks if returned value is greater than expected value. | \nvalue > expected | \n
>= | \n\n | Checks if returned value is greater than or equal to expected value. | \nvalue >= expected | \n
< | \nless than | \nChecks if returned value is less than expected value. | \nvalue < expected | \n
<= | \n\n | Checks if returned value is less than or equal to expected value. | \nvalue <= expected | \n
*= | \ncontains | \nChecks if returned value contains expected value as substring. | \nexpected in value | \n
| \n | not contains | \nChecks if returned value does not contain expected value as substring. | \nexpected in value | \n
^= | \nshould start with, starts | \nChecks if returned value starts with expected value. | \nre.search(f\"^{expected}\", value) | \n
$= | \nshould end with, ends | \nChecks if returned value ends with expected value. | \nre.search(f\"{expected}$\", value) | \n
matches | \n\n | Checks if given RegEx matches minimum once in returned value. | \nre.search(expected, value) | \n
validate | \n\n | Checks if given Python expression evaluates to True. | \n\n |
evaluate | \nthen | \nWhen using this operator, the keyword does return the evaluated Python expression. | \n\n |
There are three different possibilities what keyword returns when matches operator is used: string, tuple or dictionary. What keyword returns depends on how the RegEx is formed. If RegEx does not contain group(s), then keyword will return the string without modifications. If RegEx contains groups, meaning (...), then keyword will return a tuple. Each tuple item contains the text which is matched by the group. If there is group and group has a name, (?P<name>...) syntax, then keyword returns a dictionary. In this case dictionary key is the group name and value contains the matched text. If there mix of groups and groups with names, then tuple is returned.
\nCurrently supported formatters for assertions are:
\n| Formatter | \nDescription | \n
|---|---|
normalize spaces | \nSubstitutes multiple spaces to single space from the value | \n
strip | \nRemoves spaces from the beginning and end of the value | \n
case insensitive | \nConverts value to lower case before comparing | \n
apply to expected | \nApplies rules also for the expected value | \n
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.
Expected values are generally used as given, so they must already have the type returned by the keyword. Keywords returning numbers are an exception and convert the expected value.
\nExamples:
\nComparing strings with < or > compares code points character by character and stops at the first difference; length is never considered. Example: A < Z, Z < a, ac < dc, 'abcde' < 'abd'.
validate takes a Python expression over value. then and evaluate do not assert: they return the result of an expression over value.
\nGet Text h1 validate value.startswith(\"Welcome\")\n${id}= Get Property a#link href then value.split(\"/\")[-1]\n\nA failing assertion has a default message, replaceable with message. It accepts the format fields {value}, {expected}, {value_type} and {expected_type}.
What each operator is for, why a type mismatch is the usual failure, and the formatters that normalise a value before comparison: https://robotframework-browser.org/docs/concepts/assertions
\nBrowser 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.
\nOn 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.
\nThe Node.js side can be started as a standalone process and shared by every Browser library running on the same machine, instead of each one starting its own. This can speed up parallel runs. Start it from the directory where the Browser package is installed with ` PLAYWRIGHT_BROWSERS_PATH=0 node Browser/wrapper/index.js HOST PORT ` , for example ... index.js 127.0.0.1 12345. Both arguments are required: the script reads the host first and exits with No port defined if only one is given. Point runs at it with the playwright_process_port import parameter or the ROBOT_FRAMEWORK_BROWSER_NODE_PORT environment variable, for example ROBOT_FRAMEWORK_BROWSER_NODE_PORT=PORT pabot ...
What this costs, how to run it under Pabot, and how to pass Node flags such as --inspect: https://robotframework-browser.org/docs/operations/node-process
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:
\nGlobal scope will live forever until it is overwritten by another Global scope. Or locally temporarily overridden by a more narrow scope.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.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.
Browser keywords can be called directly from Python, from your own Robot Framework library. Arguments convert the same way Robot Framework converts them, so browser.click(\"//button\", \"middle\") works, and a Python None is passed through unchanged. Robot Framework's own features do not all follow: Automatic page and context closing and Scope Setting need Browser's listener to be registered, and run_on_failure never applies to a keyword your library calls from Python.
Getting started, and what your own library gets in each case: https://robotframework-browser.org/docs/extending/python-libraries
\nKeyword names and their documentation can be translated. Install a Python package whose name starts with robotframework_browser_translation and set the language import parameter to the language that the package declares; Browser discovers it on the module search path through the Python plugin API.
A template for a new translation, containing every keyword in the correct format, is produced by rfbrowser translation /path/to/translation.json. Keywords coming from library plugins and JavaScript extensions can be included with the --plugings and --jsextension arguments.
Writing and packaging a translation: https://robotframework-browser.org/docs/extending/translations
\nThese environment variables modify the behaviour of the library. Two of them are development features and must not be set in production; they are listed here so that nobody uses them by accident.
\n| Environment variable | \nDescription | \n
|---|---|
ROBOT_FRAMEWORK_BROWSER_NODE_PORT | \nPort number for connecting to an existing node process. This is an alternative to playwright_process_port import argument. | \n
ROBOT_FRAMEWORK_BROWSER_NODE_COVERAGE | \nIf set to 1, will collect code coverage for the node process. This must not be used in production environments and is not supported on Windows. | \n
ROBOT_FRAMEWORK_BROWSER_NODE_DEBUG_OPTIONS | \nDebug options for the node process. This is a comma-separated list of arguments, for example --inspect. This must not be used in production environments. | \n
Which of these to prefer over an import parameter, and how they behave with BrowserBatteries: https://robotframework-browser.org/docs/operations/environment-variables
", + "version": "20.4.0", + "generated": "2026-08-19T20:07:51+00:00", + "type": "LIBRARY", + "scope": "GLOBAL", + "docFormat": "HTML", + "source": "Browser/browser.py", + "lineno": 130, + "tags": [ + "Assertion", + "BrowserControl", + "Clock", + "Config", + "Coverage", + "Crawling", + "Credential", + "Experimental", + "Getter", + "HTTP", + "PageContent", + "Setter", + "Wait" + ], + "inits": [ + { + "name": "__init__", + "args": [ + { + "name": "_", + "type": null, + "defaultValue": null, + "kind": "VAR_POSITIONAL", + "required": false, + "repr": "*_" + }, + { + "name": "auto_closing_level", + "type": { + "name": "AutoClosingLevel", + "typedoc": "AutoClosingLevel", + "nested": [], + "union": false + }, + "defaultValue": "TEST", + "kind": "NAMED_ONLY", + "required": false, + "repr": "auto_closing_level: AutoClosingLevel = TEST" + }, + { + "name": "auto_delete_passed_tracing", + "type": { + "name": "bool", + "typedoc": "boolean", + "nested": [], + "union": false + }, + "defaultValue": "False", + "kind": "NAMED_ONLY", + "required": false, + "repr": "auto_delete_passed_tracing: bool = False" + }, + { + "name": "enable_playwright_debug", + "type": { + "name": "Union", + "typedoc": null, + "nested": [ + { + "name": "PlaywrightLogTypes", + "typedoc": "PlaywrightLogTypes", + "nested": [], + "union": false + }, + { + "name": "bool", + "typedoc": "boolean", + "nested": [], + "union": false + } + ], + "union": true + }, + "defaultValue": "library", + "kind": "NAMED_ONLY", + "required": false, + "repr": "enable_playwright_debug: PlaywrightLogTypes | bool = library" + }, + { + "name": "enable_presenter_mode", + "type": { + "name": "Union", + "typedoc": null, + "nested": [ + { + "name": "HighLightElement", + "typedoc": "HighLightElement", + "nested": [], + "union": false + }, + { + "name": "bool", + "typedoc": "boolean", + "nested": [], + "union": false + } + ], + "union": true + }, + "defaultValue": "False", + "kind": "NAMED_ONLY", + "required": false, + "repr": "enable_presenter_mode: HighLightElement | bool = False" + }, + { + "name": "external_browser_executable", + "type": { + "name": "Union", + "typedoc": null, + "nested": [ + { + "name": "dict", + "typedoc": "dictionary", + "nested": [ + { + "name": "SupportedBrowsers", + "typedoc": "SupportedBrowsers", + "nested": [], + "union": false + }, + { + "name": "str", + "typedoc": "string", + "nested": [], + "union": false + } + ], + "union": false + }, + { + "name": "None", + "typedoc": "None", + "nested": [], + "union": false + } + ], + "union": true + }, + "defaultValue": "None", + "kind": "NAMED_ONLY", + "required": false, + "repr": "external_browser_executable: dict[SupportedBrowsers, str] | None = None" + }, + { + "name": "highlight_on_failure", + "type": { + "name": "bool", + "typedoc": "boolean", + "nested": [], + "union": false + }, + "defaultValue": "False", + "kind": "NAMED_ONLY", + "required": false, + "repr": "highlight_on_failure: bool = False" + }, + { + "name": "jsextension", + "type": { + "name": "Union", + "typedoc": null, + "nested": [ + { + "name": "list", + "typedoc": "list", + "nested": [ + { + "name": "str", + "typedoc": "string", + "nested": [], + "union": false + } + ], + "union": false + }, + { + "name": "str", + "typedoc": "string", + "nested": [], + "union": false + }, + { + "name": "None", + "typedoc": "None", + "nested": [], + "union": false + } + ], + "union": true + }, + "defaultValue": "None", + "kind": "NAMED_ONLY", + "required": false, + "repr": "jsextension: list[str] | str | None = None" + }, + { + "name": "language", + "type": { + "name": "Union", + "typedoc": null, + "nested": [ + { + "name": "str", + "typedoc": "string", + "nested": [], + "union": false + }, + { + "name": "None", + "typedoc": "None", + "nested": [], + "union": false + } + ], + "union": true + }, + "defaultValue": "None", + "kind": "NAMED_ONLY", + "required": false, + "repr": "language: str | None = None" + }, + { + "name": "playwright_process_host", + "type": { + "name": "Union", + "typedoc": null, + "nested": [ + { + "name": "str", + "typedoc": "string", + "nested": [], + "union": false + }, + { + "name": "None", + "typedoc": "None", + "nested": [], + "union": false + } + ], + "union": true + }, + "defaultValue": "None", + "kind": "NAMED_ONLY", + "required": false, + "repr": "playwright_process_host: str | None = None" + }, + { + "name": "playwright_process_port", + "type": { + "name": "Union", + "typedoc": null, + "nested": [ + { + "name": "int", + "typedoc": "integer", + "nested": [], + "union": false + }, + { + "name": "None", + "typedoc": "None", + "nested": [], + "union": false + } + ], + "union": true + }, + "defaultValue": "None", + "kind": "NAMED_ONLY", + "required": false, + "repr": "playwright_process_port: int | None = None" + }, + { + "name": "plugins", + "type": { + "name": "Union", + "typedoc": null, + "nested": [ + { + "name": "list", + "typedoc": "list", + "nested": [ + { + "name": "str", + "typedoc": "string", + "nested": [], + "union": false + } + ], + "union": false + }, + { + "name": "str", + "typedoc": "string", + "nested": [], + "union": false + }, + { + "name": "None", + "typedoc": "None", + "nested": [], + "union": false + } + ], + "union": true + }, + "defaultValue": "None", + "kind": "NAMED_ONLY", + "required": false, + "repr": "plugins: list[str] | str | None = None" + }, + { + "name": "retry_assertions_for", + "type": { + "name": "timedelta", + "typedoc": "timedelta", + "nested": [], + "union": false + }, + "defaultValue": "0:00:01", + "kind": "NAMED_ONLY", + "required": false, + "repr": "retry_assertions_for: timedelta = 0:00:01" + }, + { + "name": "run_on_failure", + "type": { + "name": "str", + "typedoc": "string", + "nested": [], + "union": false + }, + "defaultValue": "Take Screenshot \\ fail-screenshot-{index}", + "kind": "NAMED_ONLY", + "required": false, + "repr": "run_on_failure: str = Take Screenshot \\ fail-screenshot-{index}" + }, + { + "name": "selector_prefix", + "type": { + "name": "Union", + "typedoc": null, + "nested": [ + { + "name": "str", + "typedoc": "string", + "nested": [], + "union": false + }, + { + "name": "None", + "typedoc": "None", + "nested": [], + "union": false + } + ], + "union": true + }, + "defaultValue": "None", + "kind": "NAMED_ONLY", + "required": false, + "repr": "selector_prefix: str | None = None" + }, + { + "name": "show_keyword_call_banner", + "type": { + "name": "Union", + "typedoc": null, + "nested": [ + { + "name": "bool", + "typedoc": "boolean", + "nested": [], + "union": false + }, + { + "name": "None", + "typedoc": "None", + "nested": [], + "union": false + } + ], + "union": true + }, + "defaultValue": "None", + "kind": "NAMED_ONLY", + "required": false, + "repr": "show_keyword_call_banner: bool | None = None" + }, + { + "name": "strict", + "type": { + "name": "bool", + "typedoc": "boolean", + "nested": [], + "union": false + }, + "defaultValue": "True", + "kind": "NAMED_ONLY", + "required": false, + "repr": "strict: bool = True" + }, + { + "name": "timeout", + "type": { + "name": "timedelta", + "typedoc": "timedelta", + "nested": [], + "union": false + }, + "defaultValue": "0:00:10", + "kind": "NAMED_ONLY", + "required": false, + "repr": "timeout: timedelta = 0:00:10" + }, + { + "name": "tracing_group_mode", + "type": { + "name": "TracingGroupMode", + "typedoc": "TracingGroupMode", + "nested": [], + "union": false + }, + "defaultValue": "Full", + "kind": "NAMED_ONLY", + "required": false, + "repr": "tracing_group_mode: TracingGroupMode = Full" + } + ], + "returnType": null, + "doc": "Browser library can be taken into use with optional arguments:
\n| Argument | \nDescription | \n
|---|---|
auto_closing_level | \nConfigure context and page automatic closing. Default is TEST, for more details, see AutoClosingLevel | \n
auto_delete_passed_tracing | \nIf auto_closing_level is set to SUITE or TEST and tracing of New Context active, traces of passed tests or suites, depending on the context scope, not be saved. Also temp files will all be deleted after the whole execution ends. | \n
enable_playwright_debug | \nEnable low level debug information from the playwright to playwright-log.txt file. For more details, see PlaywrightLogTypes. | \n
enable_presenter_mode | \nAutomatic highlights the 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. By default, the call banner keyword is also enabled unless explicitly disabled. | \n
external_browser_executable | \nDict 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. | \n
highlight_on_failure | \nIf set to True, will highlight the element in the screenshot when a keyword fails, by highlighting the selector used in the failed keyword. If set to False, will not highlight the element. | \n
jsextension | \nPath to JavaScript modules exposed as extra keywords. The modules must be in CommonJS format; exported functions become keywords and an fn.rfdoc string becomes a keyword's documentation. The argument names page, context, browser, logger and playwright are filled in by the library rather than taken from the keyword call. Can be a single path, a comma-separated list of paths or a real list of strings. See https://robotframework-browser.org/docs/extending/javascript-extensions | \n
language | \nDefines language which is used to translate keyword names and documentation. | \n
playwright_process_host | \nHostname / Host address which should be used when spawning the Playwright process. Defaults to 127.0.0.1. | \n
playwright_process_port | \nExperimental 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. | \n
plugins | \nAllows extending the Browser library with external Python classes, which can add keywords and modify some internal behaviour without forking the library. Can be a single class/module, a comma-separated list or a real list of strings. See https://robotframework-browser.org/docs/extending/python-plugins | \n
retry_assertions_for | \nTimeout 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. | \n
run_on_failure | \nSets 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. | \n
selector_prefix | \nPrefix for all selectors. This is useful when you need to use add an iframe selector before each selector. | \n
show_keyword_call_banner | \nIf 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. | \n
strict | \nIf 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 Set Strict Mode keyword. | \n
timeout | \nTimeout 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. | \n
tracing_group_mode | \nDefines how Robot Framework keyword calls are logged in Playwright trace log. Default is Full. For more details, see TracingGroupMode. | \n
Adds a cookie to the currently active browser context.
\n| Arguments | \nDescription | \n
|---|---|
name | \nName of the cookie. | \n
value | \nGiven value for the cookie. | \n
url | \nGiven url for the cookie. Defaults to None. Either url or the domain / path pair must be set, but not both. | \n
domain | \nGiven domain for the cookie. Defaults to None. Either url or the domain / path pair must be set, but not both. | \n
path | \nGiven path for the cookie. Defaults to None. Either url or the domain / path pair must be set, but not both. | \n
expires | \nGiven expiry for the cookie. Can be a date, a unix time or a datetime object. Supports the same formats as the DateTime library or an epoch timestamp. Example: 2027-09-28 16:21:35 | \n
httpOnly | \nSets the httpOnly token. | \n
secure | \nSets the secure token. | \n
sameSite | \nSets the sameSite mode. Can be Strict, Lax or None. | \n
Example:
\n\nAdd Cookie foo bar http://address.com/path/to/site # Using url argument.\nAdd Cookie foo bar domain=example.com path=/foo/bar # Using domain and path arguments.\nAdd Cookie foo bar http://address.com/path/to/site expires=2027-09-28 16:21:35 # Expires as timestamp.\nAdd Cookie foo bar http://address.com/path/to/site expires=1822137695 # Expires as epoch seconds.\n\n", + "shortdoc": "Adds a cookie to the currently active browser context.", + "tags": [ + "BrowserControl", + "Setter" + ], + "source": "Browser/keywords/cookie.py", + "lineno": 90 + }, + { + "name": "Add Locator Handler Click", + "args": [ + { + "name": "selector", + "type": { + "name": "str", + "typedoc": "string", + "nested": [], + "union": false + }, + "defaultValue": null, + "kind": "POSITIONAL_OR_NAMED", + "required": true, + "repr": "selector: str" + }, + { + "name": "click_selector", + "type": { + "name": "str", + "typedoc": "string", + "nested": [], + "union": false + }, + "defaultValue": null, + "kind": "POSITIONAL_OR_NAMED", + "required": true, + "repr": "click_selector: str" + }, + { + "name": "", + "type": null, + "defaultValue": null, + "kind": "NAMED_ONLY_MARKER", + "required": false, + "repr": "*" + }, + { + "name": "noWaitAfter", + "type": { + "name": "bool", + "typedoc": "boolean", + "nested": [], + "union": false + }, + "defaultValue": "True", + "kind": "NAMED_ONLY", + "required": false, + "repr": "noWaitAfter: bool = True" + }, + { + "name": "times", + "type": { + "name": "Union", + "typedoc": null, + "nested": [ + { + "name": "int", + "typedoc": "integer", + "nested": [], + "union": false + }, + { + "name": "None", + "typedoc": "None", + "nested": [], + "union": false + } + ], + "union": true + }, + "defaultValue": "None", + "kind": "NAMED_ONLY", + "required": false, + "repr": "times: int | None = None" + }, + { + "name": "click_clickCount", + "type": { + "name": "int", + "typedoc": "integer", + "nested": [], + "union": false + }, + "defaultValue": "1", + "kind": "NAMED_ONLY", + "required": false, + "repr": "click_clickCount: int = 1" + }, + { + "name": "click_delay", + "type": { + "name": "int", + "typedoc": "integer", + "nested": [], + "union": false + }, + "defaultValue": "0", + "kind": "NAMED_ONLY", + "required": false, + "repr": "click_delay: int = 0" + }, + { + "name": "click_force", + "type": { + "name": "bool", + "typedoc": "boolean", + "nested": [], + "union": false + }, + "defaultValue": "False", + "kind": "NAMED_ONLY", + "required": false, + "repr": "click_force: bool = False" + } + ], + "returnType": null, + "doc": "
Add a handler function which will activate when selector is visible and click.
The handler will click the element indicated by click_selector.
When testing a web page, sometimes unexpected overlays, for example an \"Accept Cookies\" dialog, might appear and block the interaction with the page, like the Click keyword. These overlays can be problematic to handle, because they might appear randomly in the page. This keyword allows to create an automatic method, which will close those overlays by clicking the element indicated by click_selector. The handler is activated when the element indicated by selector is visible. For further information, see Playwright's addLocatorHandler method.
| Arguments | \nDescription | \n
|---|---|
selector | \nIs the selector to the element which indicates that the locator handler should be called. | \n
noWaitAfter | \nDefaults to True, which means that the overlay may stay visible after the handler has run. If set to False, Playwright waits until the overlay becomes hidden, and only then the library continues with the action/assertion that triggered the handler. | \n
times | \nIs how many times the locator handler is called. None, the default, means unlimited. | \n
click_selector | \nIs the selector to the element to be clicked. | \n
click_clickCount | \nIs the number of times to click the element. Defaults to 1. | \n
click_delay | \nTime to wait between mousedown and mouseup in milliseconds. Defaults to 0. | \n
click_force | \nWhether to bypass checks and dispatch the event directly. Defaults to false. | \n
The arguments click_selector, click_clickCount, click_delay and click_force correspond to the arguments of the Click With Options keyword, but click_delay is given as a plain number of milliseconds. The selector, noWaitAfter and times are for the locator handler. The handler is tied to the active page, if there is need to add handler to another page, this keyword needs to be called separately for each page. If the times argument is set to a positive value, the locator handler is removed after the handler has been called the specified number of times.
Example add locator handler to click button with id=\"ButtonInOverlay\" when id=Overlay is visible:
\n\nNew Page ${URL}\nAdd Locator Handler Click id=Overlay id=ButtonInOverlay # Add locator handler to page\nType Text id:username user # If element with id=Overlay appears, the handler will click the button id=ButtonInOverlay\nType Text id:password password # Or if overlay is visible here, then handler is called here\nClick id:login\nRemove Locator Handler id=Overlay # Removes the locator handler from page\n", + "shortdoc": "Add a handler function which will activate when ``selector`` is visible and click.", + "tags": [ + "PageContent", + "Setter" + ], + "source": "Browser/keywords/locator_handler.py", + "lineno": 24 + }, + { + "name": "Add Locator Handler Custom", + "args": [ + { + "name": "selector", + "type": { + "name": "str", + "typedoc": "string", + "nested": [], + "union": false + }, + "defaultValue": null, + "kind": "POSITIONAL_OR_NAMED", + "required": true, + "repr": "selector: str" + }, + { + "name": "handler_spec", + "type": { + "name": "list", + "typedoc": "list", + "nested": [ + { + "name": "dict", + "typedoc": "dictionary", + "nested": [], + "union": false + } + ], + "union": false + }, + "defaultValue": null, + "kind": "POSITIONAL_OR_NAMED", + "required": true, + "repr": "handler_spec: list[dict]" + }, + { + "name": "noWaitAfter", + "type": { + "name": "bool", + "typedoc": "boolean", + "nested": [], + "union": false + }, + "defaultValue": "True", + "kind": "POSITIONAL_OR_NAMED", + "required": false, + "repr": "noWaitAfter: bool = True" + }, + { + "name": "times", + "type": { + "name": "Union", + "typedoc": null, + "nested": [ + { + "name": "int", + "typedoc": "integer", + "nested": [], + "union": false + }, + { + "name": "None", + "typedoc": "None", + "nested": [], + "union": false + } + ], + "union": true + }, + "defaultValue": "None", + "kind": "POSITIONAL_OR_NAMED", + "required": false, + "repr": "times: int | None = None" + } + ], + "returnType": null, + "doc": "
Add a handler function which will activate when selector is visible and performs handler specification.
When the element indicated by selector is visible, the handler will perform the actions specified in the handler_spec.
| Arguments | \nDescription | \n
|---|---|
selector | \nIs the selector to the element which indicates that the locator handler should be called. | \n
handler_spec | \nIs a list of dictionaries which defines the actions to be performed. | \n
noWaitAfter | \nDefaults to True, which means that the overlay may stay visible after the handler has run. If set to False, Playwright waits until the overlay becomes hidden, and only then the library continues with the action/assertion that triggered the handler. | \n
times | \nIs how many times the locator handler is called. None, the default, means unlimited. | \n
The handler_spec is a list of dictionaries, where each dictionary defines one action. The dictionary must contain the key action which defines the action to be performed. The action can be one of the following: click, fill, check and uncheck. Action is also case insensitive. The dictionary must also contain the key selector which defines the element to be interacted with. The fill action must also contain the key value which defines the value to be filled in the element. For the other actions the key value must not be defined. Additional keys are passed to the action as keyword arguments. For example for the click action refer to Playwright's documentation to see which options are possible.
The selectors in the handler_spec are not resolved in strict mode. If a selector matches more than one element, the first matching element is used. If an action in the handler fails, the error is only logged on the Browser library node side and the keyword which triggered the handler does not fail because of it.
The selector, noWaitAfter and times are for the locator handler method. The handler is tied to the active page, if there is need to add handler to another page, this keyword needs to be called separately for each page. If the times argument is set to a positive value, the locator handler is removed after the handler has been called the specified number of times.
Running the handler will alter your page state mid-test. For example it will change the currently focused element and move the mouse. Make sure that keywords that run after the handler are self-contained and do not rely on the focus and mouse state being unchanged.
\nPlease note that the automatic argument conversion is not done for the handler_spec dictionary. This is because Robot Framework does not convert values inside the dictionary that are actually arguments to a separate Playwright API call. Therefore the user is responsible for converting the values to the correct type. For example if a timeout is needed, the value must be converted to a number on the Robot Framework test data side.
Example adds locator handler to fill input id=overlayInput with value \"Hello\" and click element id=OverlayCloseButton when id=Overlay is visible:
\n\nNew Page ${URL}\nVAR &{handler_spec_fill}\n... action=Fill\n... selector=id=overlayInput\n... value=Hello\nVAR &{handler_spec_click}\n... action=click\n... selector=id=OverlayCloseButton\nAdd Locator Handler Custom\n... id=overlay\n... [${handler_spec_fill}, ${handler_spec_click}]\nType Text id:username user # If element with id=overlay appears, the handler fills id=overlayInput and clicks id=OverlayCloseButton\nType Text id:password password # Or if overlay is visible here, then handler is called here\nClick id:login\n\n
Example with click and different options and types:
\n\nVAR &{handler_spec}\n... action=CLICK # Action is case insensitive\n... selector=id=OverlayCloseButton\n... button=left\n... clickCount=${1}\n... delay=${0.1}\n... force=${True}\nAdd Locator Handler Custom id=overlay [${handler_spec}]\n\nThe keyword can only handle click, fill, check and uncheck Playwright API calls. If there is a need for more complex interactions, it is recommended to create a custom js extension to handle the interactions.
\nExample:
\n\nasync function customLocatorHandler(locator, pageLocator, clickLocator, page) {\n console.log(\"Adding custom locator handler for: \" + locator);\n const pageLocator = page.locator(locator).first();\n await page.addLocatorHandler(\n pageLocator,\n async () => {\n console.log(\"Handling custom locator: \" + clickLocator);\n // More complex interactions can be added here\n await page.locator(clickLocator).click();\n }\n );\n}\nexports.__esModule = true;\nexports.customLocatorHandler = customLocatorHandler;\n",
+ "shortdoc": "Add a handler function which will activate when ``selector`` is visible and performs handler specification.",
+ "tags": [
+ "PageContent",
+ "Setter"
+ ],
+ "source": "Browser/keywords/locator_handler.py",
+ "lineno": 108
+ },
+ {
+ "name": "Add Style Tag",
+ "args": [
+ {
+ "name": "content",
+ "type": {
+ "name": "str",
+ "typedoc": "string",
+ "nested": [],
+ "union": false
+ },
+ "defaultValue": null,
+ "kind": "POSITIONAL_OR_NAMED",
+ "required": true,
+ "repr": "content: str"
+ }
+ ],
+ "returnType": null,
+ "doc": "Adds a <style type=\"text/css\"> tag with the content.
\nThe tag is added to the currently active page and it is lost when the page is navigated to a new url.
\n| Arguments | \nDescription | \n
|---|---|
content | \nRaw CSS content to be injected into the current page. | \n
Example:
\n\nAdd Style Tag \\#username_field:focus {background-color: aqua;}\n\n", + "shortdoc": "Adds a