# Browser 21.0.0 — keyword reference > Every keyword of the Robot Framework Browser library 21.0.0, with its arguments, return value and documentation, followed by every argument type. Keyword names are case-insensitive in Robot Framework, and spaces and underscores in them are ignored. Source: https://robotframework-browser.org/keywords ## Contents - Library documentation - Importing - Keywords (alphabetical) - Types ## Library documentation Browser library is a browser automation library for Robot Framework. This is the keyword documentation for Browser library. For installation, guides and everything else, see [robotframework-browser.org](https://robotframework-browser.org). For more information about Robot Framework itself, see [robotframework.org](https://robotframework.org). Browser library uses [Playwright Node module](https://github.com/microsoft/playwright) to automate [Chromium](https://www.chromium.org/Home), [Firefox](https://www.mozilla.org/en-US/firefox/new/) and [WebKit](https://webkit.org/) with a single library. ### Table of contents - `Browser, Context and Page` - `Automatic page and context closing` - `Finding elements` - `Strategies` - `Explicit and implicit strategy` - `Text matching` - `Chaining` - `iFrames` - `Shadow DOM` - `Element references` - `Assertions` - `Implicit waiting` - `Experimental: Re-using same node process` - `Scope Setting` - `Using Browser from Python` - `Language` - `ENVIRONMENT VARIABLES` ### Browser, Context and Page Browser library works in three layers that build on each other. | Layer | Is | Opened with | | --- | --- | --- | | **Browser** | A browser process: `chromium`, `firefox` or `webkit`. | `New Browser` | | **Context** | An isolated session in that process: its own cookies, storage and permissions. Contexts share nothing with each other. | `New Context` | | **Page** | A tab, with its own content and history. Selectors resolve here. | `New Page` | 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 | Ships in | | --- | --- | | `chromium` | Google Chrome, Microsoft Edge, Opera | | `firefox` | Mozilla Firefox | | `webkit` | Safari on macOS and iOS | 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. A context is the cheap unit of isolation — 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. Which layer to open for which job, and the cost of each: [https://robotframework-browser.org/docs/concepts/browser-context-page](https://robotframework-browser.org/docs/concepts/browser-context-page) ### 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, 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. See: `Importing` ### Finding elements Keywords 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. ### Strategies | Strategy | Matches on | Example | | --- | --- | --- | | `role` | ARIA role, with optional accessible name. | `role=button[name="Login"]` | | `data-testid` | `data-testid` attribute. | `data-testid=login` | | `text` | Text content. See `Text matching`. | `text=Login` | | `id` | Element ID attribute. | `id=login_btn` | | `css` | CSS selector. | `css=.class > \#login_btn` | | `xpath` | XPath expression. | `xpath=//input[@id="login_btn"]` | | `data-test-id` | `data-test-id` attribute. | `data-test-id=login` | | `data-test` | `data-test` attribute. | `data-test=login` | | `css:light` | As `css`, but does not pierce shadow DOM. | `css:light=.class` | | `label` | Label, as Playwright's `getByLabel`. | `label=Email` | 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. | Filter | Selects | Example | | --- | --- | --- | | `nth` | The nth match, zero based. `0` first, `-1` last. | `css=button >> nth=1` | | `visible` | Only visible, or only hidden, matches. | `css=button >> visible=true` | 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](https://robotframework-browser.org/docs/concepts/selectors) ### Explicit and implicit strategy 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: | Selector starts with | Read as | Example | | --- | --- | --- | | `//` or `..` | `xpath` | `//span/button` is `xpath=//span/button` | | `"` or `'` | `text`, exact | `"Login"` is `text="Login"` | | anything else | `css` | `span > button` is `css=span > button` | Because `#` starts a comment in Robot Framework data, an id selector must be escaped as `\#id`. `css` follows the [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors) specification and `xpath` the [XPath](https://developer.mozilla.org/en-US/docs/Web/XPath) specification; neither is re-documented here. ### Text matching 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 | Matches | | --- | --- | | `text=Login` | Substring, case-insensitive, leading and trailing whitespace ignored. | | `text="Login "` | Exact: case, whitespace and all. Escape a quote as `\"`. | | `text=/^Hi .*!$/i` | JavaScript-style [regular expression](https://regex101.com/) with flags: e.g. `i` for case-insensitive. | ### Chaining 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 `>>` or `>>>` must be quoted, as in `text="some >> text"`; a regular expression (`text=/a>>b/`) cannot contain them. ```robotframework Click css=.checkout >> text=Confirm Get Element *css=article >> text=Hello # returns the article ``` ### iFrames A chain does not cross a frame boundary. `>>>`, with whitespace around it, combines a selector for the frame element with a selector inside it; the clause immediately before `>>>` must select the frame itself. Without whitespace, `a>>>b` is read as `a >> >b`, as it always was. ```robotframework Click id=iframe >>> id=btn ``` A selector that starts with `>>>` searches in every frame of the page, the main frame included, so the frames around the element need not be named. The rest of the selector must match inside a single frame; elements in several frames are an error, also without strict mode and in keywords that count or list elements such as `Get Element Count`. With a selector prefix set, the prefix comes first and `>>>` enters the frame it selects, as before; a prefix of only `>>>` searches every frame. ```robotframework Click >>> id=btn # a button in any frame, or the page itself Click >>> id=inner >>> id=btn # a button in the frame inner, wherever that frame is ``` For several keywords inside one frame, set a prefix with `Set Selector Prefix`. ### Shadow DOM All 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 are never entered, and iframes only with `>>>`. Use `css:light` to stop at the shadow boundary. Worked examples of what each matches: [https://robotframework-browser.org/docs/concepts/selectors](https://robotframework-browser.org/docs/concepts/selectors) ### Element references `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 `>>`: ```robotframework ${ref}= Get Element .some_class Click ${ref} >> .some_child Click ${ref} >> .other_child ``` Clauses 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. ### Assertions 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: | Operator | Alternative Operators | Description | Validate Equivalent | | --- | --- | --- | --- | | `==` | `equal`, `equals`, `should be` | Checks if returned value is equal to expected value. | `value == expected` | | `!=` | `inequal`, `should not be` | Checks if returned value is not equal to expected value. | `value != expected` | | `>` | `greater than` | Checks if returned value is greater than expected value. | `value > expected` | | `>=` | | Checks if returned value is greater than or equal to expected value. | `value >= expected` | | `<` | `less than` | Checks if returned value is less than expected value. | `value < expected` | | `<=` | | Checks if returned value is less than or equal to expected value. | `value <= expected` | | `*=` | `contains` | Checks if returned value contains expected value as substring. | `expected in value` | | | `not contains` | Checks if returned value does not contain expected value as substring. | `expected in value` | | `^=` | `should start with`, `starts` | Checks if returned value starts with expected value. | `re.search(f"^{expected}", value)` | | `$=` | `should end with`, `ends` | Checks if returned value ends with expected value. | `re.search(f"{expected}$", value)` | | `matches` | | Checks if given RegEx matches minimum once in returned value. | `re.search(expected, value)` | | `validate` | | Checks if given Python expression evaluates to `True`. | | | `evaluate` | `then` | When using this operator, the keyword does return the evaluated Python expression. | | 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...) 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. Currently supported formatters for assertions are: | Formatter | Description | | --- | --- | | `normalize spaces` | Substitutes multiple spaces to single space from the value | | `strip` | Removes spaces from the beginning and end of the value | | `case insensitive` | Converts value to lower case before comparing | | `apply to expected` | Applies rules also for the expected value | Formatters are applied to the value before assertion is performed and keywords returns a value where rule is applied. Formatter is only applied to the value which keyword returns and not all rules are valid for all assertion operators. If `apply to expected` formatter is defined, then formatters are then formatter are also applied to expected value. 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. Examples: - `Get Text` returns a string even when it looks like a number - `Get Element Count` returns an integer. - `Get BoundingBox` and `Get Viewport Size` return a dictionary unfiltered and a number when a key is selected. Comparing 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`. ```robotframework Get Text h1 validate value.startswith("Welcome") ${id}= Get Property a#link href then value.split("/")[-1] ``` A failing assertion has a default message, replaceable with `message`. It accepts the [format](https://docs.python.org/3/library/stdtypes.html#str.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](https://robotframework-browser.org/docs/concepts/assertions) ### 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](https://playwright.dev/docs/actionability/) 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 The 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](https://robotframework-browser.org/docs/operations/node-process) ### 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. ### Using Browser from Python 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](https://robotframework-browser.org/docs/extending/python-libraries) ### Language Keyword 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](https://robotframework-browser.org/docs/extending/translations) ### ENVIRONMENT VARIABLES These 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. | Environment variable | Description | | --- | --- | | `ROBOT_FRAMEWORK_BROWSER_NODE_PORT` | Port number for connecting to an existing node process. This is an alternative to `playwright_process_port` import argument. | | `ROBOT_FRAMEWORK_BROWSER_NODE_COVERAGE` | If 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. | | `ROBOT_FRAMEWORK_BROWSER_NODE_DEBUG_OPTIONS` | Debug options for the node process. This is a comma-separated list of arguments, for example `--inspect`. This must not be used in production environments. | Which of these to prefer over an import parameter, and how they behave with BrowserBatteries: [https://robotframework-browser.org/docs/operations/environment-variables](https://robotframework-browser.org/docs/operations/environment-variables) ## Importing `Library Browser`, with these optional arguments: - `*_` — Positional arguments are ignored. All arguments must be passed as named arguments. - `auto_closing_level: AutoClosingLevel = TEST` (named-only) — Configure context and page automatic closing. Default is `TEST`, for more details, see AutoClosingLevel - `auto_delete_passed_tracing: bool = False` (named-only) — If `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, will not be saved. Also temp files will all be deleted after the whole execution ends. - `enable_playwright_debug: PlaywrightLogTypes | bool = library` (named-only) — Enable low level debug information from the playwright to playwright-log.txt file. For more details, see PlaywrightLogTypes. - `enable_presenter_mode: HighLightElement | bool = False` (named-only) — Automatic 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. - `external_browser_executable: dict[SupportedBrowsers, str] | None = None` (named-only) — Dict mapping name of browser to path of executable of a browser. Will make opening new browsers of the given type use the set executablePath. Currently only configuring of `chromium` to a separate executable (chrome, chromium and Edge executables all work with recent versions) works. - `highlight_on_failure: bool = False` (named-only) — If 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. - `jsextension: list[str] | str | None = None` (named-only) — Path 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`, `playwright`, `adoptContext` and `defaultTimeout` are filled in by the library rather than taken from the keyword call. `defaultTimeout` is the library timeout in milliseconds, as `Set Browser Timeout` sets it; only a Python library that calls the function with `call_js_keyword` may pass its own instead. `adoptContext(context, options)` makes a BrowserContext that the function created itself, such as the context of an Electron app, the active browser, so the other keywords work on it. The context gets the library timeout, and is traced and recorded like a context of `New Context`. Can be a single path, a comma-separated list of paths or a real list of strings. The options of `adoptContext` and examples are in [https://robotframework-browser.org/docs/extending/javascript-extensions](https://robotframework-browser.org/docs/extending/javascript-extensions) - `language: str | None = None` (named-only) — Defines language which is used to translate keyword names and documentation. - `playwright_process_host: str | None = None` (named-only) — Hostname / Host address which should be used when spawning the Playwright process. Defaults to 127.0.0.1. - `playwright_process_port: int | None = None` (named-only) — Experimental reusing of playwright process. `playwright_process_port` is preferred over environment variable `ROBOT_FRAMEWORK_BROWSER_NODE_PORT`. See `Experimental: Re-using same node process` for more details. - `plugins: list[str] | str | None = None` (named-only) — Allows 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](https://robotframework-browser.org/docs/extending/python-plugins) - `retry_assertions_for: timedelta = 0:00:01` (named-only) — Timeout for retrying assertions on keywords before failing the keywords. This timeout starts counting from the first failure. Global `timeout` will still be in effect. This allows stopping execution faster to assertion failure when element is found fast. - `run_on_failure: str = Take Screenshot \ fail-screenshot-{index}` (named-only) — Sets the keyword to execute in case of a failing Browser keyword. It can be the name of any keyword. If the keyword has arguments those must be separated with two spaces for example `My keyword \ arg1 \ arg2`. If no extra action should be done after a failure, set it to `None` or any other robot falsy value. Run on failure is not applied when library methods are executed directly from Python. - `selector_prefix: str | None = None` (named-only) — Prefix for all selectors. This is useful when you need to add an iframe selector before each selector. - `show_keyword_call_banner: bool | None = None` (named-only) — If set to `True`, will show a banner with the keyword name and arguments before the keyword is executed at the bottom of the page. If set to `False`, will not show the banner. If set to None, which is the default, will show the banner only if the presenter mode is enabled. `Get Page Source` and `Take Screenshot` will not show the banner, because that could negatively affect your test cases/tasks. This feature may be super helpful when you are debugging your tests and using the `tracing` or `recordVideo` arguments of `New Context`. - `strict: bool = True` (named-only) — If keyword selector points multiple elements and keywords should interact with one element, keyword will fail if `strict` mode is true. Strict mode can be changed individually in keywords or by `Set Strict Mode` keyword. - `timeout: timedelta = 0:00:10` (named-only) — Timeout for keywords that operate on elements. The keywords will wait for this time for the element to appear into the page. Defaults to "10s" => 10 seconds. - `tracing_group_mode: TracingGroupMode = Full` (named-only) — Defines how Robot Framework keyword calls are logged in Playwright trace log. Default is `Full`. ## Keywords ### Add Cookie Arguments: - `name: str` — Name of the cookie. - `value: str` — Given value for the cookie. - `url: str | None = None` — Given url for the cookie. Defaults to None. Either `url` or the `domain` / `path` pair must be set, but not both. - `domain: str | None = None` — Given domain for the cookie. Defaults to None. Either `url` or the `domain` / `path` pair must be set, but not both. - `path: str | None = None` — Given path for the cookie. Defaults to None. Either `url` or the `domain` / `path` pair must be set, but not both. - `expires: str | datetime | None = None` — Given expiry for the cookie. Can be a date, a unix time or a datetime object. Supports the same formats as the [DateTime](http://robotframework.org/robotframework/latest/libraries/DateTime.html) library or an epoch timestamp. Example: `2027-09-28 16:21:35` - `httpOnly: bool | None = None` — Sets the httpOnly token. - `secure: bool | None = None` — Sets the secure token. - `sameSite: CookieSameSite | None = None` — Sets the sameSite mode. Can be `Strict`, `Lax` or `None`. Tags: BrowserControl, Setter Adds a cookie to the currently active browser context. Example: ```robotframework Add Cookie foo bar http://address.com/path/to/site # Using url argument. Add Cookie foo bar domain=example.com path=/foo/bar # Using domain and path arguments. Add Cookie foo bar http://address.com/path/to/site expires=2027-09-28 16:21:35 # Expires as timestamp. Add Cookie foo bar http://address.com/path/to/site expires=1822137695 # Expires as epoch seconds. ``` ### Add Locator Handler Click Arguments: - `selector: str` — Is the selector to the element which indicates that the locator handler should be called. - `click_selector: str` — Is the selector to the element to be clicked. - `noWaitAfter: bool = True` (named-only) — Defaults 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. - `times: int | None = None` (named-only) — Is how many times the locator handler is called. `None`, the default, means unlimited. - `click_clickCount: int = 1` (named-only) — Is the number of times to click the element. Defaults to 1. - `click_delay: int = 0` (named-only) — Time to wait between mousedown and mouseup in milliseconds. Defaults to 0. - `click_force: bool = False` (named-only) — Whether to bypass checks and dispatch the event directly. Defaults to false. Tags: PageContent, Setter 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](https://playwright.dev/docs/api/class-page#page-add-locator-handler) method. 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: ```robotframework New Page ${URL} Add Locator Handler Click id=Overlay id=ButtonInOverlay # Add locator handler to page Type Text id:username user # If element with id=Overlay appears, the handler will click the button id=ButtonInOverlay Type Text id:password password # Or if overlay is visible here, then handler is called here Click id:login Remove Locator Handler id=Overlay # Removes the locator handler from page ``` ### Add Locator Handler Custom Arguments: - `selector: str` — Is the selector to the element which indicates that the locator handler should be called. - `handler_spec: list[dict]` — Is a list of dictionaries which defines the actions to be performed. - `noWaitAfter: bool = True` — Defaults 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. - `times: int | None = None` — Is how many times the locator handler is called. `None`, the default, means unlimited. Tags: PageContent, Setter 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`. 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](https://playwright.dev/docs/api/class-locator#locator-click), [fill](https://playwright.dev/docs/api/class-locator#locator-fill), [check](https://playwright.dev/docs/api/class-locator#locator-check) and [uncheck](https://playwright.dev/docs/api/class-locator#locator-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](https://playwright.dev/docs/api/class-locator#locator-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](https://playwright.dev/docs/api/class-page#page-add-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. 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. Please 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: ```robotframework New Page ${URL} VAR &{handler_spec_fill} ... action=Fill ... selector=id=overlayInput ... value=Hello VAR &{handler_spec_click} ... action=click ... selector=id=OverlayCloseButton Add Locator Handler Custom ... id=overlay ... [${handler_spec_fill}, ${handler_spec_click}] Type Text id:username user # If element with id=overlay appears, the handler fills id=overlayInput and clicks id=OverlayCloseButton Type Text id:password password # Or if overlay is visible here, then handler is called here Click id:login ``` Example with click and different options and types: ```robotframework VAR &{handler_spec} ... action=CLICK # Action is case insensitive ... selector=id=OverlayCloseButton ... button=left ... clickCount=${1} ... delay=${0.1} ... force=${True} Add Locator Handler Custom id=overlay [${handler_spec}] ``` The 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. Example: ```robotframework async function customLocatorHandler(locator, pageLocator, clickLocator, page) { console.log("Adding custom locator handler for: " + locator); const pageLocator = page.locator(locator).first(); await page.addLocatorHandler( pageLocator, async () => { console.log("Handling custom locator: " + clickLocator); // More complex interactions can be added here await page.locator(clickLocator).click(); } ); } exports.__esModule = true; exports.customLocatorHandler = customLocatorHandler; ``` ### Add Style Tag Arguments: - `content: str` — Raw CSS content to be injected into the current page. Tags: PageContent, Setter Adds a