# Robot Framework Browser

> A browser automation library for Robot Framework, powered by Playwright. Speed, reliability and visibility, with assertions built into the keywords.

Source: [https://robotframework-browser.org/](https://robotframework-browser.org/)

Robot Framework deserves a browser automation solution designed for the 2020s.
Browser library, powered by [Playwright](https://playwright.dev/), provides
speed, reliability and visibility.

- [Get started](https://robotframework-browser.org/#start)
- [Why Browser](https://robotframework-browser.org/why)

- Browser: **21.0.0**
- Playwright: **1.64.1**
- Node: **26.13.0**
- Keywords: **154**
- Stars: **661**
- Contributors: **211**
- Releases: **192**
- Sleeps: **0**

## Speed, reliability and visibility.

**Speed**

One Node process drives Chromium, Firefox and WebKit. No driver binary per
browser, no version to keep in step with an update.

**Reliability**

Every action waits for the element to be actionable before it acts. No sleeps
to tune, and no flake to chase down.

**Visibility**

Video, a Playwright trace and a screenshot on failure, attached to the Robot
Framework log.

- Conscientious assertions
- Precise and fast browser window and tab control
- Chainable selector strategies
- Good shadow DOM support
- Simple descriptors for mobile devices
- Sending HTTP requests

[How it works, and how it compares](https://robotframework-browser.org/why)

## Running in five minutes.

Three blocks. Copy them in order and you have a passing test — nothing to
configure in between.

### Install the library and the browsers

No Node.js needed — the `[bb]` extra brings one along in the wheel.
`rfbrowser install` downloads the browser binaries Playwright drives. The tabs
below pick your shell automatically.

```bash
$ pip install "robotframework-browser[bb]"
Successfully installed robotframework-browser-21.0.0 robotframework-browser-batteries-21.0.0
$ rfbrowser install
Installing Playwright browser binaries…
✓ chromium   downloaded
✓ firefox    downloaded
✓ webkit     downloaded
```

```powershell
PS> py -m pip install "robotframework-browser[bb]"
Successfully installed robotframework-browser-21.0.0 robotframework-browser-batteries-21.0.0
PS> py -m Browser.entry install
Installing Playwright browser binaries…
✓ chromium   downloaded
✓ firefox    downloaded
✓ webkit     downloaded
```

Want a Node toolchain of your own instead, or on a platform with no wheel? That
route is two different commands and [Installation](https://robotframework-browser.org/docs/start/installation) has
both.

### Write a test

One import, no setup keyword, no explicit waits. `Get Text` both reads the
value and asserts it — and it keeps re-reading until the search results arrive,
which is why nothing here waits for them.

```robot [first.robot]
*** Settings ***
Library     Browser

*** Test Cases ***
Search The Syllabus
    New Page      https://syllabus.robotframework.org
    Fill Text     id=search_input_react    Argument Types
    Get Text      body    *=    2.5.2.8
```

### Run it

Robot Framework as usual — the browser opens, acts and closes.

```bash
$ robot first.robot
=========================================================
First
✓ Search Robot Framework
1 test, 1 passed, 0 failed
```

Next: the [getting-started guide](https://robotframework-browser.org/docs/start/getting-started), or the
[keyword reference](https://robotframework-browser.org/keywords).

Writing your tests with an AI assistant? This site is also published for
language models: [llms.txt](https://robotframework-browser.org/llms.txt) lists
every page as Markdown,
[llms-full.txt](https://robotframework-browser.org/llms-full.txt) holds all the
docs in one file, and
[keywords.md](https://robotframework-browser.org/keywords.md) the complete
keyword reference. Point your assistant there.

## Use. Benefit. Contribute.

Browser library is built in the open by the Robot Framework community — 206
people so far. Questions, ideas and bug reports are how most of them started,
and how the library got this far.

- [Community and contributing](https://robotframework-browser.org/community)
- [Forum](https://forum.robotframework.org/c/libraries/browser)
- [GitHub](https://github.com/MarketSquare/robotframework-browser)

### And 206 people who made it better

Bug reports, ideas, documentation, running main against a real suite before it
was ever released. Most of them never wrote a line of code for Browser.
[See who did what](https://robotframework-browser.org/community#hall).

**Let's make the best Browser library.**


# Installation

> The two ways to install Browser — with a bundled Node.js runtime, or with one you provide yourself — and how to upgrade and remove each.

Source: [https://robotframework-browser.org/docs/start/installation](https://robotframework-browser.org/docs/start/installation)

Browser is a Python library that drives Playwright running in Node.js, so
something has to supply that Node.js. There are two ways to do it, and the only
real decision at install time is which.

Both need **Python 3.10 or newer**, and both should be done in a virtual
environment.

## Choose a route

|  | Without Node.js | With Node.js |
| --- | --- | --- |
| `pip install` | `robotframework-browser[bb]` | `robotframework-browser` |
| Then run | `rfbrowser install` | `rfbrowser init` |
| Node.js from | The wheel, already on disk after `pip` | You, on the `PATH` |
| Works on | Linux x64/arm64, Windows x64, macOS x64/arm64 | Anywhere Python and Node.js both run |
| Extra npm packages | No — what ships is what you get | Yes |
| Leaves you `npm` and `npx` | No | Yes |

Start on the left. It is fewer moving parts, and in an environment where
installing Node.js means a ticket and a wait, it removes the whole conversation.

Go right when something in that column is yours: a platform with no wheel, a
JavaScript extension that needs npm packages Browser does not ship, or an
existing Node toolchain you would rather Browser used.

The two are not exclusive and not a one-way door. They differ only in where the
Node.js comes from — the keywords, the arguments and the behaviour are the same
either way — so switching later costs an uninstall and a reinstall, not a
rewrite.

## Without Node.js

### Install

```bash
$ pip install "robotframework-browser[bb]"
Successfully installed robotframework-browser-21.0.0 robotframework-browser-batteries-21.0.0
```

```powershell
PS> py -m pip install "robotframework-browser[bb]"
Successfully installed robotframework-browser-21.0.0 robotframework-browser-batteries-21.0.0
```

The `[bb]` extra pulls in
[robotframework-browser-batteries](https://pypi.org/project/robotframework-browser-batteries/),
a platform-specific wheel carrying an unmodified official Node.js build, the
gRPC wrapper and its production Node dependencies. It is not a single packed
binary: it is a real `node` and a real `node_modules`, installed into
`site-packages/BrowserBatteries/bin/`.

Which Node.js that is moves with the library, so it is a fact about a release
rather than about the package. The [release notes](https://robotframework-browser.org/releases) say which Node.js
the BrowserBatteries wheel was built with — check there for the release you are
installing.

The quotes are for zsh, which is the default shell on macOS and treats bare
square brackets as a glob. `bash` and PowerShell do not need them and do not
mind them.

> **Aside:**
> 
> Installing `robotframework-browser-batteries` by name gets you the same two
> packages — it depends on the matching `robotframework-browser` — so an existing
> requirements file spelling it that way is not wrong. `robotframework-browser[bb]`
> is written from the side you are more likely to remember: the library, with
> batteries.

The two packages are **tied to one version** and having them differ is not
supported. That is what the extra buys beyond a shorter line: pip resolves both
from a single constraint, so they cannot drift apart.

### Where there is a wheel

A wheel is published for each of these, and tagged so that pip declines to
install it where the bundled Node.js could not start:

| Platform | Architecture | Needs at least |
| --- | --- | --- |
| Linux | x64 | glibc 2.28 — Debian 10, RHEL 8, Ubuntu 20.04 |
| Linux | arm64 | glibc 2.28 — Debian 10, RHEL 8, Ubuntu 20.04 |
| Windows | x64 | Windows 10 or Windows Server 2016 |
| macOS | x64 | macOS 13.5 |
| macOS | arm64 | macOS 13.5 |

There is no musl wheel, and none for Windows on arm. Anywhere else, pip reports
that it found no matching distribution — which is the wheel tags doing their
job, and the signal to use the other route.

> **Watch out:**
> 
> macOS **13.0 to 13.4** is the one case the tags cannot catch. Node.js needs
> 13.5, but pip only ever generates `macosx_13_0_*` tags, so the wheel installs
> and then the bundled Node.js fails to start. On those four versions, either
> update macOS or install Node.js yourself.

### Browser binaries

Playwright's browser builds are downloaded separately, because they are not in
the wheel:

```bash
$ rfbrowser install
Installing Playwright browser binaries…
✓ chromium   downloaded
✓ firefox    downloaded
✓ webkit     downloaded
```

```powershell
PS> py -m Browser.entry install
Installing Playwright browser binaries…
✓ chromium   downloaded
✓ firefox    downloaded
✓ webkit     downloaded
```

Three engines, a few hundred megabytes, once per environment. Name one to get
only that one — `rfbrowser install firefox`.

> **Watch out:**
> 
> **rfbrowser init** **is not for this route.** It runs `npm ci` and stops with
> *Couldn't execute npm. Please ensure you have node.js and npm installed and in
> PATH* — which reads like a broken installation and is not one. On this route the
> command is `rfbrowser install`.

You can also skip this step entirely. If you already have a Chromium-based
browser — Chrome or Edge — you can drive that instead by passing a `channel` to
`New Browser`, and download nothing:

```robot-repl
New Browser    chromium    channel=chrome
```

That combination — wheels only, no binary download — is what makes this route
work on a machine with no route to the public internet at all.

### Verify

```bash
$ rfbrowser --version
Installed Browser library version is: "21.0.0"
Installed Robot Framework version: "7.4.1"
Required Playwright is: "1.64.1"
```

It reports the Playwright as *Required* rather than *Installed* here, because
reading the installed version means asking `npm`, and there is no `npm` on this
route. The number is the one that ships in the wheel either way.

Note what it does **not** report: the browser binaries. `rfbrowser --version`
staying green says nothing about whether `rfbrowser install` ever ran.

### Upgrading

Upgrade both packages together, then rebuild the Node side:

```bash
$ pip install -U robotframework-browser robotframework-browser-batteries
$ rfbrowser clean-node
Delete library node dependencies from …/BrowserBatteries/bin/wrapper/node_modules
$ rfbrowser install
```

`clean-node` removes the old Node dependencies and browser binaries. Skipping it
leaves the previous release's binaries behind, and a Playwright that has moved on
does not necessarily drive them.

### Uninstalling

```bash
$ rfbrowser clean-node
$ pip uninstall robotframework-browser robotframework-browser-batteries
```

`clean-node` first, and in that order: it is what deletes the browser binaries,
and once pip has removed the package there is nothing left that knows where they
were.

## With Node.js

### Install

Install [Node.js](https://nodejs.org/en/download/) first — at the time of
writing that is **22, 24 or 26**, and each release states the lines it supports
in its [release notes](https://robotframework-browser.org/releases). Make sure `npm` is on your `PATH`. Then:

```bash
$ pip install robotframework-browser
Successfully installed robotframework-browser-21.0.0
```

```powershell
PS> py -m pip install robotframework-browser
Successfully installed robotframework-browser-21.0.0
```

### Node dependencies and browser binaries

One command does both, and the library does not work until it has run:

```bash
$ rfbrowser init
Installing node dependencies...
Installing browser binaries to 0
rfbrowser init completed
```

```powershell
PS> py -m Browser.entry init
Installing node dependencies...
Installing browser binaries to 0
rfbrowser init completed
```

`init` runs `npm ci --omit=dev` against the lockfile shipped in the package, then
downloads the browsers. Name engines to narrow the download —
`rfbrowser init chromium firefox` — or pass `--skip-browsers` to install the Node
dependencies alone and take responsibility for the binaries yourself.

> **Watch out:**
> 
> **rfbrowser install** **is not for this route.** It exists for installations that
> have BrowserBatteries, and running it here does not install the Node
> dependencies `init` is responsible for. On this route the command is
> `rfbrowser init`.

Do not add npm packages to `Browser/wrapper` by hand either. `init` runs `npm ci`
there, which deletes `node_modules` and reinstalls exactly the shipped
production dependencies, so anything you put there disappears at the next init
or upgrade. Extensions that need their own packages are covered in
[JavaScript extensions](https://robotframework-browser.org/docs/extending/javascript-extensions).

> **Note:**
> 
> **On Node.js 26 with npm 12**, `init` needs two extra steps. npm 12 no longer
> runs post-install scripts unless they are approved, and several of Browser's
> dependencies use them. Run `rfbrowser init` once, then
> `npm approve-scripts --allow-scripts-pending` to list what is waiting, then
> `npm approve-scripts <package> <package>` for the ones belonging to Browser —
> review the list, because it covers every npm project on the machine, not only
> this one — and run `rfbrowser init` again.
> 
> This is a moving target and it is npm's, not ours. It does not arise without
> Node.js, where the dependencies are already built into the wheel.

### Verify

```bash
$ rfbrowser --version
Installed Browser library version is: "21.0.0"
Installed Robot Framework version: "7.4.1"
Installed Playwright is: "1.64.1"
```

*Installed* rather than *Required* means the number came from `npm list` in the
wrapper directory — so a line reading *Installed* is also evidence that `init`
got as far as writing `node_modules`. It still says nothing about the browser
binaries.

### Upgrading

```bash
$ pip install -U robotframework-browser
$ rfbrowser clean-node
Delete library node dependencies from …/Browser/wrapper/node_modules
$ rfbrowser init
```

`clean-node` between the two is not optional housekeeping. `npm ci` reinstalls
from the new lockfile, but the browser binaries from the previous release are
outside its reach and stay until something deletes them.

### Uninstalling

```bash
$ rfbrowser clean-node
$ pip uninstall robotframework-browser
```

## Behind a proxy, or offline

Both routes reach the network, but for different things, and that is the whole
of what changes here.

Without Node.js there is one download — the browser binaries — and it can be
avoided altogether by driving an installed Chrome or Edge through `channel`.
Wheels themselves can travel by hand: `pip download robotframework-browser-batteries`
on a connected machine gets you the pair, and they install from a directory on
the target with no index at all.

With Node.js there are two: npm resolving the wrapper's dependencies, and
Playwright fetching the binaries. Both have to work, and an internal npm
registry usually has to be configured before the first `init`.

The browser download itself is Playwright's, and so are the variables that steer
it through a proxy, a custom certificate authority or an internal mirror. They
reach Playwright unchanged from either route, and
[Playwright documents them](https://playwright.dev/docs/browsers#install-behind-a-firewall-or-a-proxy) —
we deliberately do not copy the list, because a copy is wrong the day it changes.

## Never install into the system Python

> **Note:**
> 
> Use a virtual environment — `uv`, `venv` or `pyenv`, whichever your team already
> uses. Installing into the system Python needs root, writes browser binaries into
> a directory you do not own, and is painful to unpick. You will also need to test
> against a second Python version sooner than you expect.

For Node.js on the second route, use a version manager for the same reason: `n`
or `nvm` on Linux and macOS, `nvm-windows` or `nodist` on Windows.

Where the files actually land, and what the two halves do at run time, is
[how Browser works](https://robotframework-browser.org/docs/concepts/architecture).


# Getting started

> Install Browser, write a first test, and run it.

Source: [https://robotframework-browser.org/docs/start/getting-started](https://robotframework-browser.org/docs/start/getting-started)

Install the library and its browser binaries, write one test, run it.

## Before you start

You need **Python 3.10 or newer**, and a virtual environment to put this in —
`uv`, `venv` or `pyenv`, whichever your team uses.

## Install

```bash
$ pip install "robotframework-browser[bb]"
Successfully installed robotframework-browser-21.0.0 robotframework-browser-batteries-21.0.0
$ rfbrowser install
Installing Playwright browser binaries…
✓ chromium   downloaded
✓ firefox    downloaded
✓ webkit     downloaded
```

```powershell
PS> py -m pip install "robotframework-browser[bb]"
Successfully installed robotframework-browser-21.0.0 robotframework-browser-batteries-21.0.0
PS> py -m Browser.entry install
Installing Playwright browser binaries…
✓ chromium   downloaded
✓ firefox    downloaded
✓ webkit     downloaded
```

That is the route that needs no Node.js: the `[bb]` extra brings a Node.js
runtime along in the wheel. `rfbrowser install` then downloads three browser
engines, so it is the slow part and it needs a few hundred megabytes — once per
environment.

If you would rather provide Node.js yourself — because your platform has no
wheel, or because a JavaScript extension needs npm packages Browser does not
ship — the commands are `pip install robotframework-browser` and `rfbrowser init` instead. Both routes, in full, are on
[Installation](https://robotframework-browser.org/docs/start/installation).

## Your first test

The assertion is part of the keyword — `Get Title` both reads and checks.

The browser runs **headless** by default, so this prints a result without
anything appearing on screen. To watch it, open the browser yourself above
`New Page`:

```robot-repl
New Browser    chromium    headless=False
```

```robot [first.robot]
*** Settings ***
Library    Browser

*** Test Cases ***
Open The Keyword Reference
    New Page     https://robotframework-browser.org
    Get Title    *=    Robot Framework Browser
    Click        nav[aria-label="Main"] >> text="Keywords"
    Get Title    *=    Keyword reference
```

It drives this site, so you can run it right now without an application of your
own — and the pages it touches are the ones you are reading.

Two things are doing work in that selector, and both are worth copying.

`>>` chains: everything left of it narrows the search, so `text="Keywords"` is
looked for only inside the main navigation. The page has a second link with that
exact text — in the row of figures on the landing page — and Playwright is
strict: a selector matching more than one element is an error, not a silent
first-match.

The quotes make it an *exact* match. Without them, `text=Keywords` is a
case-insensitive substring, which would also find "keywords" inside a sentence.
See [selectors](https://robotframework-browser.org/docs/concepts/selectors).

## Run it

```bash
$ robot first.robot
Open The Keyword Reference                                            | PASS |
1 test, 1 passed, 0 failed
```

Robot Framework writes `log.html` into the directory you ran `robot` from — not
next to the test file — unless you pass `--outputdir`. Open it — every keyword,
its arguments and its result are in there, and it is the first place to look
when something fails.

## What is not in that test

No `Sleep`, and no wait keyword before anything. Two different mechanisms are
doing that work:

- **Action keywords** like `Click` wait for the element to be actionable —
attached, visible, stable and able to receive the click — before acting.
- **Assertions** like the `Get Title` line above re-read the value until it
matches or the retry window expires.

So a keyword with an assertion operator is itself the wait. A getter *without*
one reads once and returns. That distinction is the whole of
[assertions](https://robotframework-browser.org/docs/concepts/assertions).


# Browser, context and page

> The three layers Playwright is built on — and why a new context is the cheapest clean slate you will ever get.

Source: [https://robotframework-browser.org/docs/concepts/browser-context-page](https://robotframework-browser.org/docs/concepts/browser-context-page)

Browser works in three layers. Almost every question about isolation, speed, or
"why is this test seeing the previous test's login" is answered by knowing which
layer you are on.

```text
Browser · chromium
│
├── Context 1 · alice
│   ├── Page · tab
│   └── Page · tab
│
└── Context 2 · bob
    └── Page · tab
```

One browser process, two signed-in users, three tabs. The two contexts share
nothing — separate cookies, separate storage, separate permissions — which is
the whole reason the layers are worth learning.

| Layer | Is | Costs | Opened with |
| --- | --- | --- | --- |
| **Browser** | A Chromium, Firefox or WebKit process | Slowest | `New Browser` |
| **Context** | An isolated session inside it | Cheapest | `New Context` |
| **Page** | A tab, with its own history | Cheap | `New Page` |

## The browser

One process, one engine. Three are available, and between them they cover what
people actually use:

| Engine | Ships in |
| --- | --- |
| `chromium` | Google Chrome, Microsoft Edge, Opera |
| `firefox` | Mozilla Firefox |
| `webkit` | Safari on macOS and iOS |

Playwright brings its own binaries, so there is no geckodriver, no chromedriver,
and no driver version to keep in step with a browser version. The same three
engines run on Windows, Linux and macOS.

`New Browser` starts headless unless you say otherwise — `Open Browser`, being a
debugging tool, starts headful:

```robot-repl
New Browser    chromium    headless=False
```

The browser layer is where the *environment* is decided: which engine, headless
or not, a proxy, a slow-motion delay, the browser's own timeout, extra launch
arguments.

### Browsers are reused

`New Browser` with the same arguments as an earlier `New Browser` call does not
start a second process — it switches to that one. That is what makes it safe to
call in a suite setup that runs many times. A browser that `New Page` or
`New Context` created implicitly is not a reuse candidate, so an explicit
`New Browser` after them does start a second process. To force a new one
deliberately:

```robot-repl
New Browser    chromium    reuse_existing=False
```

## The context

A context is an independent session inside an already-running browser: its own
cookies, its own storage, its own permissions. Two contexts share nothing. The
closest everyday equivalent is a fresh incognito window.

This is the layer worth understanding, because it is where Browser is
structurally faster than the older tools. With tools that give you one session per browser process, an isolated session
costs a process start. Here it is one call inside a process that is already
warm:

```robot-repl
New Context    # a clean slate, in a few milliseconds
```

So "log in as a different user" costs a few milliseconds of context creation
rather than a browser start, and so does "start this test from a known-clean
state". You do not clear cookies; you throw the context away and open another.

The context is also where the interesting configuration lives:

```robot-repl
New Context    viewport={'width': 1920, 'height': 1080}
New Context    locale=de-DE    timezoneId=Europe/Berlin
New Context    geolocation={'latitude': 48.86, 'longitude': 2.35}
New Context    httpCredentials={'username': '$user', 'password': '$pwd'}
New Context    acceptDownloads=True
New Context    colorScheme=dark
```

Downloads are accepted by default. Pass `acceptDownloads=False` if you want the
browser to refuse them.

The `$user` and `$pwd` above are not a typo. `httpCredentials` refuses a plain
value — it takes the `$name` placeholder form, and resolves the names from
variables, so the password never reaches the log.

Tracing and video recording are context-level too, which is why a trace covers
exactly one session:

```robot-repl
New Context    tracing=True
New Context    recordVideo={'dir': '${OUTPUT_DIR}/video'}
```

### Logging in once, and reusing it

A context starts empty: no cookies, no `localStorage`, nobody logged in. Doing
the login again in every test is the slowest thing most suites do, and the least
interesting to debug when it breaks.

`Save Storage State` takes what the *active context* has accumulated and writes
it to a file; `New Context` takes that file back:

```robot
*** Test Cases ***
Log In Once
    New Context
    New Page       ${LOGIN_URL}
    Fill Secret    id=username    $USERNAME
    Fill Secret    id=password    $PASSWORD
    Click          id=submit
    Get Text       id=header    ==    Signed in

    ${state} =    Save Storage State

    # A second session, already authenticated.
    New Context    storageState=${state}
    New Page       ${APP_URL}
    Get Text       id=header    ==    Signed in
```

#### What actually travels

Less than you might expect, and this is the part worth knowing before you rely
on it. Playwright's snapshot *can* carry cookies, `localStorage`, IndexedDB and
virtual WebAuthn credentials — but the last two only when asked for, and Browser
does not ask. It calls `storageState` with a path and nothing else, so you get
the defaults:

| State | Restored |  |
| --- | --- | --- |
| Cookies | **yes** | Session cookies included, subject to their own expiry |
| `localStorage` | **yes** | Per origin, exactly as saved |
| `sessionStorage` | no | By definition tied to one tab; it is not in the file at all |
| IndexedDB | no | Playwright offers it as an option; Browser does not pass it |
| WebAuthn credentials | no | Same reason |

So a login that keeps its token in a cookie or in `localStorage` restores
cleanly. One that keeps it in `sessionStorage` does not, and no amount of saving
will change that — you have to log in per context.

#### Three things that catch people

**The file does not survive the run.** It is written to
`${OUTPUT_DIR}/browser/state/`, and that whole directory is deleted at the start
of every execution. Reuse within a run is what this is for; to carry a session
between runs, copy the file somewhere the next run will not wipe.

**The path must exist.** Anything else fails immediately and by name:

```text
ValueError: storageState argument value 'does-not-exist.json' is not file,
but it should be.
```

It is checked before the context is created, so a typo costs no browser time.

**The file is a credential.** It contains live session cookies and whatever the
app put in `localStorage`. Anyone holding it is logged in as that user. Keep it
out of version control and out of build artefacts you publish.

### Persistent contexts

`New Persistent Context` is the exception to the shape: it takes a user data
directory and creates its own browser, so state *survives* between runs. Useful
when a real profile is the thing under test, and the wrong tool for isolation —
a browser opened this way cannot host additional contexts.

## The page

A page is a tab. It holds the document and its own history, and it is where every
selector resolves.

```robot
*** Test Cases ***
Starting A Browser With A Page
    New Browser    chromium    headless=False
    New Context    viewport={'width': 1920, 'height': 1080}
    New Page       https://robotframework-browser.org
    Get Title      *=    Robot Framework Browser
```

A popup, a target-blank link or a second tab is another page in the same
context, so it shares the login. It does **not** become the active page on its
own — reach it with `Switch Page`, given `NEW`, which returns the id of the page
you came from:

```robot-repl
Click          text=Open report
${previous} =    Switch Page    NEW
Get Title      *=    Report
Switch Page    ${previous}
```

## You rarely open all three

The layers fill themselves in downwards. `New Page` with nothing open starts a
browser and a context first, using defaults:

```robot-repl
New Page    https://robotframework-browser.org
```

`Open Browser` does all three in one call. It is built for experiments and
debugging; when you care about the context, open the three yourself.

## What is open right now

Every browser, context and page has an id, and `Get Browser Catalog` returns the
whole tree:

```text
chromium  browser=94c1…
├── context=7f2a…
│   ├── page=3dce…  /login
│   └── page=8b17…  /cart
└── context=b3d9…
    └── page=1f60…  /admin

firefox  browser=1ae8…
└── context=5c04…
    └── page=42aa…  about:blank
```

Drawn as a tree here for readability; the keyword returns a list of
dictionaries, one per browser, each carrying its contexts and their pages.

What the tree does not show is which branch the next keyword will act on. That
lives in three fields, and they are not the same kind of thing.

`activeBrowser` is a **boolean**, one per browser, and exactly one is true —
here it is `chromium`. `activeContext` and `activePage` hold **ids**, and
*every* browser and context carries them whether or not it is the active
branch: `context=b3d9…` above is idle, and still names the page it would use if
you switched to it.

So in this catalog the next `Click` lands on `page=3dce…` at `/login`: chromium
is the true `activeBrowser`, its `activeContext` is `context=7f2a…`, and that
context's `activePage` is `page=3dce…`. Read the three in that order and you
always know where you are.

This is the fastest way to answer "what does the library think is running" when
a suite has drifted from what you expected. `Get Browser Ids`, `Get Context Ids`
and `Get Page Ids` return the pieces individually.

Keywords act on the *active* browser, context and page unless you say otherwise,
and `Switch Browser`, `Switch Context` and `Switch Page` move that pointer.

## When things close

By default, the **contexts and pages** a test opened are closed when the test
ends. Browsers are not: no auto-closing level closes a browser per test or per
suite, so a browser lives until execution ends or you call `Close Browser`. The
exceptions are a browser opened by `New Persistent Context` and one that a
JavaScript extension
[handed over with `adoptContext`](https://robotframework-browser.org/docs/extending/javascript-extensions#handing-over-a-context-you-created)
— each is closed together with its context.

That setting is `auto_closing_level`, and it has four values:

| Level | Contexts and pages are closed |
| --- | --- |
| `TEST` | At the end of the test that created them (the default). Anything created in suite setup lives until suite teardown. |
| `SUITE` | At the end of the suite that created them |
| `MANUAL` | Never during the run — everything closes when execution ends |
| `KEEP` | Never, not even at the end. The node process stays alive too. |

```robot
*** Settings ***
Library    Browser    auto_closing_level=SUITE
```

`KEEP` leaves processes running on purpose — it exists so you can poke at a page
after a failing test while writing it. **Never set it in CI**, or runs will leak
browser processes until the machine gives up.

## Which layer for which job

| You want | Open |
| --- | --- |
| A second user session | A new **context** |
| A popup or a second tab in the same session | A new **page** |
| A clean slate between tests | A new **context** — not a new browser |
| A different engine, or a GUI | A new **browser** |
| A proxy | Either — `proxy` is an argument on **both** `New Browser` and `New Context` |
| A profile that survives the run | `New Persistent Context` |
| A mobile device profile | A new **context** from `Get Device` |

The third row is the one that decides how long your suite takes. Reaching for a
new browser where a new context would do is the single most common reason a
Browser suite runs slower than it needs to.

## In short

- Browser = process, context = session, page = tab.
- Contexts are the cheap unit of isolation. Use them freely.
- `New Page` opens whatever is missing underneath it.
- Cookies, storage, permissions, viewport, locale, tracing and video all belong
to the **context**.
- `auto_closing_level=KEEP` is for writing tests, never for running them.


# Finding elements

> Which selector strategy to reach for, why the order matters, and how to chain across iframes and shadow DOM.

Source: [https://robotframework-browser.org/docs/concepts/selectors](https://robotframework-browser.org/docs/concepts/selectors)

Every keyword that touches the page takes a `selector`. Which strategy you choose
decides how often your suite breaks for reasons that have nothing to do with the
software under test.

This page covers the strategies, the order I would reach for them in, and the
syntax for chaining, iframes and shadow DOM.

## Pick a strategy

> **Note:**
> 
> **The ranking below is opinionated!**
> 
> It optimises for one thing: *a selector that keeps working when the page is redesigned but the feature is unchanged.*
> 
> Every project is different, and you should base your selector strategy on other criteria as well. For example, prior knowledge, GUI framework, or other factors.

|  | Strategy | Reach for it when |
| --- | --- | --- |
| 1 | role= | The element has a proper accessible role and name. This is the default choice. |
| 2 | data-testid= | Stability matters more than testing the interface as a user meets it. |
| 3 | text= | The visible text is the thing you actually mean, and the app is single-language. |
| 4 | label= | A form field, or a widget with an `aria-label`, has no role and name to reach it by, but a label the user reads. |
| 5 | id= | You know the id is contractual, not incidental. |
| 6 | css= | None of the above identify the element. |
| 7 | xpath= | Genuinely nothing else can select it. |

### Example: Our Landing Page

On our landing page, we have some buttons and links.

One of them is a colour theme toggle, which is a button with a visible label and aria-label. It is the only button with that aria-label, so it is a perfect candidate for a `role=` selector. However, it also has a `data-testid` attribute, which is a good candidate for a `data-testid=` selector. The visible text is "DARK", which is a good candidate for a `text=` selector.

![A toggle button labelled DARK in the top-right corner](https://robotframework-browser.org/images/color-toggle.png)

Color toggle at top right

See the following HTML DOM snippet for the button:

```html [Color Theme Toggle]
<button 
  type="button"
  class="toggle"
  data-testid="theme-toggle"
  aria-label="DARK-Mode colour theme. Activate to change."
>
  <span class="dot" aria-hidden="true" />
  DARK
</button>
```

### 1. `role=` — how the user finds it

```robot-repl
Click    role=button[name="DARK-Mode colour theme. Activate to change."]
# ^ matches the aria-label as exact match

Click    role=button[name*="colour theme"]
# ^ matches the aria-label which contains (*=) the substring "colour theme"

# other examples:
Click    role=link[name="Get started"]
Fill Text    role=textbox[name="Email"]    admin@example.com
```

A role selector matches on what the element *is* and what it is *called* —
the same two things a screen-reader user navigates by. It is semantic rather
than structural, so it survives a redesign that moves the button, restyles it,
or rebuilds the surrounding markup.

The name here is the **accessible name**, which the browser computes in this
order:

1. `aria-labelledby`
2. `aria-label`
3. An associated `<label>`
4. Visible text content
5. `title`

There is a bonus that is easy to miss. If you cannot write a role selector
because the element has no proper role or no accessible name, **you have found
an accessibility bug**. A screen-reader user cannot identify that control
either. That is worth an issue, not a workaround.

When accessible names are long and complex, `role=` selectors can be brittle if the name changes in a redesign.
In that case, matching by substring or regex is a good compromise, e.g. `role=button[name*="colour theme"]` matches the aria-label by substring.

The following operators are available for matching the name:

<table>
<thead>
  <tr>
    <th>
      Operator
    </th>
    
    <th>
      Meaning
    </th>
    
    <th>
      Example
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        =
      </code>
    </td>
    
    <td>
      exact match
    </td>
    
    <td>
      <code>
        role=button[name="DARK-Mode colour theme. Activate to change."]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        *=
      </code>
    </td>
    
    <td>
      contains substring
    </td>
    
    <td>
      <code>
        role=button[name*="Activ"]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ^=
      </code>
    </td>
    
    <td>
      starts with string
    </td>
    
    <td>
      <code>
        role=button[name^="DARK"]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        $=
      </code>
    </td>
    
    <td>
      ends with string
    </td>
    
    <td>
      <code>
        role=button[name$="Activate to change."]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ~=
      </code>
    </td>
    
    <td>
      contains one whole word
    </td>
    
    <td>
      <code>
        role=button[name~="Activate"]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        |=
      </code>
    </td>
    
    <td>
      contains hyphenated word
    </td>
    
    <td>
      <code>
        role=button[name|="DARK"]
      </code>
    </td>
  </tr>
</tbody>
</table>

Regex is also supported when the expected text is surrounded by slashes,
e.g. `role=button[name=/^(DARK|LIGHT|CONTRAST|AUTO)-Mode colour theme/]` matches the aria-label as a regex, case-sensitively.
Regex flags can be added after the closing slash, e.g. `i` for case-insensitive matching.

### 2. `data-testid=` — the one attribute that belongs to us

```robot-repl
Click   data-testid=theme-toggle
```

Every other attribute on the page belongs to someone else. Classes belong to the
designers, ids to the developers, text to the copywriters — and all three of
them are entitled to change their minds without telling you.

A dedicated test id is the only hook that exists for testing, and the only one
nobody will change by accident. If long-term stability is what you are buying,
buy this one.

Be clear-eyed about what it costs, though. A test id is invisible to the user,
so a suite built on test ids is **using the interface to test the functionality
behind it**, not testing the interface. That is often exactly the right trade —
just make it deliberately rather than by default.

### 3. `text=` — what is written on it

```robot-repl
Click    text=DARK            # contains match
Click    "DARK"               # exact match

# if the aria-label would be the text:
Click    text=/^(DARK|LIGHT|CONTRAST|AUTO)-Mode colour theme/i    # regex match
```

Text selectors use a user-facing property, like `role=`, which is why they rank
above anything structural. They are one step behind `role=` because text alone
does not say what the element *is*, and because text is language-dependent: the
moment the app is localised, every text selector is a translation away from
failing.

`text=Sign in` matches by substring, case-insensitively. Quoting the value —
`"Sign in"` — makes it a whole-string, case-sensitive match. Both **normalise
whitespace**: edges trimmed and internal runs collapsed, so `"Sign in"` still
matches `<p> Sign in </p>`. The regex form is the exception — it runs
against the raw text, so `text=/^Sign in$/i` will not match a padded node.

### 4. `label=` — the label a user reads

Form fields are usually found by their label, and so can a selector be. `label=`
does what Playwright's `getByLabel` does: it finds the element a label belongs
to.

```robot-repl
Fill Text    label=Email address    jane@example.com
Fill Text    label=Customer's name    Jane
Check Checkbox    label="I agree"
```

An element counts as labelled by:

- a `<label for="…">` pointing at it, or a `<label>` wrapping it;
- the elements named in its `aria-labelledby`;
- its `aria-label`, which also labels elements that are no form field, such as
a `<div aria-label="Map">` widget.

The value is matched like `text=`:

| Selector | Matches a label |
| --- | --- |
| `label=Email` | containing `email`, in any case |
| `label="Email"i` | the same, written quoted |
| `label="Email"` | exactly `Email`, case and all |
| `label=/^e-?mail/i` | matching the regular expression |

Whitespace is normalised in every form but the regular expression. An unquoted
value may contain quotes — `label=Customer's name` — just like an unquoted
`text=`. `label=` is a step of its own in a chain, `css=form >> label=Email`;
it is not understood inside Playwright's nested selectors such as
`internal:has="…"`.

`label=` ranks right after `text=`: like it, it is what the user reads, and like
it, it is a translation away from failing once the app is localised. Where an
element has both a role and a label, `role=textbox[name="Email"]` says more about
what it is; where it has no role, `label=` is the readable way to reach it.

### 5. `id=` — less stable than it looks

```robot-repl
Click    id=submit-button
Click    \#submit-button
```

An id feels like a stable, unique handle, and sometimes it is. But ids belong to
the developers, they are frequently generated by a framework, and nothing stops
them changing in a refactor that nobody thought was user-visible. The stability
is a **false sense of safety** unless you have agreed with the developers that
these particular ids are contractual.

> **Watch out:**
> 
> `#` starts a comment in Robot Framework syntax, so a CSS id selector must be
> escaped as `\#submit-button`, or written as `id=submit-button`.

### 6. `css=` — acceptable, not preferable

```robot-repl
Click    button.toggle:has-text("DARK")   #button with the class "toggle" that contains the text "DARK"

# other examples:
Click    css=button.primary
Click    .checkout > button
```

CSS is web-native and every web developer reads it, which is a real advantage:
a developer looking at your selector understands it immediately and can tell
you when a change will break it.

It ranks below the four above because it selects on *structure and styling* —
exactly the things a redesign changes. A class name is a styling decision, typically not a contract with you.

CSS is the implicit default: a selector that is not obviously something else is treated as CSS.

> **Aside:**
> 
> CSS is way more powerful than many realise. It can select by attribute, by position, by relationship, and even by text content. See [CSS Basics and Advanced](https://robotframework-browser.org/docs/concepts/selectors#css-basics-and-advanced) for a full reference.

### 7. `xpath=` — the last resort

```robot-repl
Click    xpath=//button[contains(@class, "toggle") and contains(text(), 'DARK')]
# ^ the literal same as the CSS above, but in XPath

Click    xpath=//header//button[contains(text(),'DARK')]    # text contains, preceding whitespace ignored
Click    //header//button[text()=' DARK']    # exact match, whitespace matters!
```

XPath is CSS's powerful, unpleasant relative. It is more verbose for the same
result, many web developers do not read it fluently, it is not web-native, and
it invites selecting by document position rather than function — which is the
most brittle thing you can possibly do.

It is partially more powerful, and occasionally something is unselectable
without it. Use it then, and only then. It is the last resort, not a
general-purpose tool. One of the very rare occasions where it is appropriate
to use XPath is when you need to navigate relative to a reliably identified element

And if you are about to paste something like this out of your browser's
devtools:

```robot-repl
Click    //body/div[1]/div/header/span/button
```

**DON'T!** That selector describes where the button sits today, not what it is.
It will break on the next layout change, and the failure will look like a bug in
the software rather than in the test.

A legitimate use for XPath is **relative navigation**: start from an element you can identify reliably, then move through the DOM to an otherwise ambiguous element.

For example, imagine a form with several fields, each with the same info button:

```html [DOM]
...
<div class="field">
    <label for="email">Email</label>
    <div class="control">
        <input id="email" type="text">
        <button type="button" aria-label="More information">ⓘ</button>
    </div>
</div>
<div class="field">
    <label for="phone">Phone</label>
    <div class="control">
        <input id="phone" type="text">
        <button type="button" aria-label="More information">ⓘ</button>
    </div>
</div>
...
```

`role=button[name="More information"]` alone is ambiguous: there are two of them. But the Email textbox is easy to identify. We can anchor there, move up to the common parent, and then find the button within it:

```robot-repl [Bad Example]
Click    xpath=//label[text()="Email"]/..//button[@aria-label="More information"]
```

The above example solves the problem but just because you need one functionality of XPath, does not mean you have to use it all the way. See [Cascading Selectors](https://robotframework-browser.org/docs/concepts/selectors#chaining-with)

```robot-repl [Good Example]
Click    role=textbox[name="Email"] >> xpath=.. >> role=button[name="More information"]
```

Here XPath is doing something useful and narrowly scoped: **navigating relative to a reliably identified element**. We are not describing where the element happens to sit in the entire document; we are expressing a local relationship between two elements.

That is a good use of XPath.

### Also available: the `data-testid` aliases

`data-testid=` has two siblings that do exactly the same job against a different
attribute. Which one you use is decided by what your developers already put in
the markup, not by preference:

| Prefix | Matches |
| --- | --- |
| `data-testid=` | `data-testid` — Playwright's own default, and the most common in the wild |
| `data-test-id=` | `data-test-id` |
| `data-test=` | `data-test` |

All three behave identically. Pick the one your application emits and stay with
it.

## How a strategy is used

You can always be explicit with a `strategy=value` prefix. Spaces around the
separator are ignored by `css=`, `xpath=`, `text=` and `label=`, so `css=foo`,
`css= foo` and `css = foo` are equivalent. They are **not** ignored by `id=` or the
test-id engines: the space becomes part of the value, so `id = save` silently
matches nothing.

Without a prefix, the strategy is inferred:

| Selector looks like | Treated as |
| --- | --- |
| Starts with `//` or `..` | XPath |
| Starts and ends with a quote | Text |
| Anything else | CSS |

```robot-repl [Implicit Selector Strategies]
Get Element    //html/body/div      # xpath
Get Element    "foo"                # text exact match
Get Element    div                  # css
```

## Cascading Selectors with `>>`

This is the part that makes Browser's selectors worth learning. Strategies
combine in a single string, left to right, with `>>`. Each step searches inside
the result of the previous one.

```robot-repl
# Find the element with text "Login", then the input beside it
Click    "Login" >> xpath=../input

# Find a css element, then a button inside it by text
Click    css=.checkout >> text=Confirm

# Start with a role, narrow with css
Get Text    role=listitem >> css=.price
```

That means you rarely need one clever selector. You need two obvious ones.

### When the chain returns the wrong element

By default a chain returns what the *last* step matched. Prefix a step with `*`
to return that step's element instead, while still requiring the rest of the
chain to match:

```robot-repl
# The article that contains "Hello" — not the text node inside it
Get Element    *css=article >> text=Hello
```

### When `>>` appears in the text you are matching

Escape it by quoting the value, or the chain splits in the wrong place:

```robot-repl
Get Text    text="some >> text"
```

## Filter selectors

Some prefixes do not find elements at all. They take what the previous step
found and **narrow it**, which is why they are only *useful* as a step in a
chain. Used alone they apply to the whole document rather than being rejected.

It is worth holding the two kinds apart in your head:

| Kind | Does | Examples |
| --- | --- | --- |
| Strategy | Finds elements in the page | `css=`, `xpath=`, `text=`, `role=`, `id=` |
| Filter | Narrows what the step before it found | `nth=`, `visible=` |

### `nth=` — pick one out of many

Zero-based, and `-1` is the last one:

```robot-repl
Click    css=.result >> nth=0     # the first result
Click    css=.result >> nth=2     # the third
Click    css=.result >> nth=-1    # the last
```

This is the honest escape hatch from [strict mode](https://robotframework-browser.org/docs/concepts/selectors#strict-mode): when a
selector legitimately matches several elements and you want a specific one,
say so. It is still positional, so prefer narrowing by something meaningful
first — `css=.result >> text=Helsinki` beats `nth=3` whenever it is available.

### `visible=` — keep only what can be seen

```robot-repl
Click    css=button.save >> visible=true
Get Element Count    css=.row >> visible=false    ==    2
```

Useful when a page keeps hidden copies of things in the DOM — a mobile menu
next to a desktop one, a template, a collapsed panel.

> **Watch out:**
> 
> **The order of filters changes the answer.** These two are not the same
> selector:
> 
> ```robot-repl
> # Third input among the visible ones
> Click    //input >> visible=true >> nth=2
> 
> # Third input in the DOM, then check it happens to be visible
> Click    //input >> nth=2 >> visible=true
> ```
> 
> Each step operates on the result of the one before it. Reading a chain left to
> right tells you exactly what it does, and reading it in any other order tells
> you something false.

## CSS Basics and Advanced

### CSS Basics

<table>
<thead>
  <tr>
    <th>
      Syntax
    </th>
    
    <th>
      Meaning
    </th>
    
    <th>
      Example
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        tag
      </code>
    </td>
    
    <td>
      Element type
    </td>
    
    <td>
      <code>
        button
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .class
      </code>
    </td>
    
    <td>
      Class
    </td>
    
    <td>
      <code>
        .submit-button
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        #id
      </code>
    </td>
    
    <td>
      ID
    </td>
    
    <td>
      <code>
        #email
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        [attr]
      </code>
    </td>
    
    <td>
      Has attribute
    </td>
    
    <td>
      <code>
        [disabled]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        [attr="value"]
      </code>
    </td>
    
    <td>
      Attribute equals
    </td>
    
    <td>
      <code>
        [type="submit"]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        A B
      </code>
    </td>
    
    <td>
      Descendant
    </td>
    
    <td>
      <code>
        form button
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        A > B
      </code>
    </td>
    
    <td>
      Direct child
    </td>
    
    <td>
      <code>
        form > button
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        A + B
      </code>
    </td>
    
    <td>
      <strong>
        Next sibling
      </strong>
    </td>
    
    <td>
      <code>
        label + input
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        A ~ B
      </code>
    </td>
    
    <td>
      <strong>
        Any following sibling
      </strong>
    </td>
    
    <td>
      <code>
        label ~ button
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        :nth-child(n)
      </code>
    </td>
    
    <td>
      Child by position
    </td>
    
    <td>
      <code>
        li:nth-child(2)
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        :not(...)
      </code>
    </td>
    
    <td>
      Exclude matches
    </td>
    
    <td>
      <code>
        button:not([disabled])
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        :has(...)
      </code>
    </td>
    
    <td>
      Has matching descendant/relative
    </td>
    
    <td>
      <code>
        .field:has(input[name="email"])
      </code>
    </td>
  </tr>
</tbody>
</table>

One useful distinction to xpath: CSS can select **following** siblings with `+` and `~`, but it has no simple equivalent of XPath's `..` for selecting a parent directly.

### Attribute selection with comparison operators

CSS supports a few comparison operators for attributes similar to the ones used in `role=` selectors.

So the same operators are available: `=`, `*=`, `^=`, `$=`, `~=`, and `|=`.
[See role table above](https://robotframework-browser.org/docs/concepts/selectors#_1-role-how-the-user-finds-it) for explanation.
However RegEx selection is not possible.

### Filtering inside a CSS selector

Playwright adds pseudo-classes to CSS that stay inside one step, rather than
becoming another link in the chain. These are strategies-with-conditions, not
filters, because they still describe *which* element you want:

| Pseudo-class | Matches |
| --- | --- |
| `:has(sel)` | An element that contains something matching `sel` |
| `:has-text("x")` | An element containing that text anywhere inside it, case-insensitive |
| `:text("x")` | The *smallest* element containing that text |
| `:text-is("x")` | The smallest element whose text is exactly that |
| `:text-matches("re")` | Text matching a regular expression |
| `:visible` | Only elements that are visible |
| `:is(a, b)` | An element matching *any* of the listed selectors |
| `:nth-match(sel, n)` | The n-th match, one-based, across the whole query |

```robot-repl
# The row that contains the name, then the button inside that row
Click    css=tr:has-text("Ada Lovelace") >> role=button[name="Edit"]

# A card that contains an image, rather than a card whose text mentions one
Get Text    css=.card:has(img) >> css=.title
```

`:has-text()` is the one you will reach for most. Note the difference from
`:text()`: `tr:has-text("Ada")` is the whole row, while `tr :text("Ada")` is the
cell.

### Layout selectors

Playwright can also select by where an element sits relative to another:
`:right-of()`, `:left-of()`, `:above()`, `:below()` and `:near()`.

They return **every** element in that direction, sorted by distance — not the
nearest one — so under strict mode you need a `nth=0` to say you meant the
closest.

```robot-repl
Fill Text    css=input:right-of(:text("Postcode")) >> nth=0    00100
```

> **Watch out:**
> 
> These match on rendered geometry, so they break when the layout changes — the
> same objection as selecting by document position with XPath, and for the same
> reason. A form field is nearly always reachable through its `<label>`, which is
> what `role=textbox[name="Postcode"]` uses and what a screen reader uses too.
> 
> Reach for a layout selector when the markup genuinely offers nothing else, and
> treat it as a note that the page has an accessibility problem worth reporting.

## XPath Basics

XPath has tons of features and was generally designed to navigate in XML trees.
Here are some of the more common used ones.

As you can see, unlike in CSS, `class` and `id` attributes are not treated specially. To identify an element whose `class` attribute contains `error`, you need to use the `contains()` function.

<table>
<thead>
  <tr>
    <th>
      Syntax
    </th>
    
    <th>
      Meaning
    </th>
    
    <th>
      Example
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        //
      </code>
    </td>
    
    <td>
      Descendant anywhere below
    </td>
    
    <td>
      <code>
        //button
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /
      </code>
    </td>
    
    <td>
      Direct child
    </td>
    
    <td>
      <code>
        //form/button
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ..
      </code>
    </td>
    
    <td>
      Parent
    </td>
    
    <td>
      <code>
        //input/..
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @
      </code>
    </td>
    
    <td>
      Attribute
    </td>
    
    <td>
      <code>
        //input[@name="email"]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        [...]
      </code>
    </td>
    
    <td>
      Filter / condition
    </td>
    
    <td>
      <code>
        //button[@type="submit"]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        *
      </code>
    </td>
    
    <td>
      Any element
    </td>
    
    <td>
      <code>
        //*[@data-id="123"]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        text()
      </code>
    </td>
    
    <td>
      Element text
    </td>
    
    <td>
      <code>
        //button[text()="Save"]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contains()
      </code>
    </td>
    
    <td>
      Partial match
    </td>
    
    <td>
      <code>
        //div[contains(@class,"error")]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        [1]
      </code>
      
      , <code>
        [2]
      </code>
    </td>
    
    <td>
      Positional match
    </td>
    
    <td>
      <code>
        (//button)[1]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ancestor::
      </code>
    </td>
    
    <td>
      Navigate upward
    </td>
    
    <td>
      <code>
        //input/ancestor::form
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        following-sibling::
      </code>
    </td>
    
    <td>
      Following sibling
    </td>
    
    <td>
      <code>
        //label/following-sibling::input
      </code>
    </td>
  </tr>
</tbody>
</table>

There are way more functionalities supported by XPath that you may learn somewhere else.

## Crossing into iframes with `>>>`

Selector chains stop at frame boundaries by default. To cross one, use `>>>`:

```robot-repl
Get Text    iframe#preview >>> h1
Click       iframe[name="editor"] >>> role=button[name="Bold"]
```

No context switching, and no switching back afterwards — the frame boundary is
just another step in the chain.

Two rules it is easy to trip over. `>>>` must have **spaces around it**: written
as `a>>>b` it is read as `a >> >b`, an ordinary chain with a child combinator,
and you get a timeout with no explanation. And the clause immediately before it
must select the `<iframe>` element itself — under strict mode, exactly one of
them. A `>>>` inside quoted text, `text="Next >>> page"`, is text.

### Any frame: a leading `>>>`

When the element sits in some frame and naming every frame around it adds
nothing, start the selector with `>>>`. Browser then searches every frame of the
page, the main frame included:

```robot-repl
Click       >>> role=button[name="Save"]        # a button in any frame
Get Text    >>> iframe#preview >>> h1          # the frame preview, wherever it is
```

The rest of the selector must match inside a single frame. If it matches
elements in several frames, the keyword fails — also with strict mode off, and
also in keywords that count or list, such as `Get Element Count`. With a selector
prefix set, the prefix comes first and `>>>` enters the frame it selects; a
prefix of only `>>>` makes every following selector search all frames.

## Shadow DOM

Browser pierces open shadow roots automatically, so a normal chain reaches into
a web component without any special syntax:

```robot-repl
Get Text    css=my-widget >> css=button
```

This is one of the places Browser is genuinely ahead of older tools: automatic
piercing means a component-based frontend does not need a different approach
from any other page.

Closed shadow roots cannot be pierced by anything, by design — if you hit one,
that is a conversation with the developers rather than a selector problem.

Piercing is what most engines do — `css`, `text`, `role` and the attribute
engines all cross open shadow roots. `xpath` does not. Every descendant
combinator, including the implicit one at the start of a selector, crosses any
number of open roots. Elements are searched in the light DOM first, then inside
open shadow roots, in document order. No engine enters an iframe — that needs
`>>>`.

### Turning piercing off

One engine stops at the shadow boundary: `css:light=`, which behaves like
`document.querySelector` and follows the CSS spec exactly.

```robot-repl
# Matches .label inside the component's shadow root
Get Text    css=my-widget .label

# Matches only if .label is in the light DOM
Get Text    css:light=my-widget .label
```

Reach for `css:light=` when you specifically need to assert that something is
*not* inside a shadow root. The rest of the time the piercing default is what
you want.

> **Watch out:**
> 
> The other `:light` engines are deprecated. `text:light=`, `id:light=`,
> `xpath:light=`, `data-testid:light=`, `data-testid:light=` and `data-test:light=`
> do not work anymore.

## Strict mode

By default, a selector that matches more than one element is an error rather
than a silent pick of the first one.

```robot
*** Settings ***
Library    Browser    strict=False    # opt out globally
```

Leave it on. A selector matching three elements when you meant one is a bug in
the selector, and strict mode tells you immediately instead of at some later
point when the order changes.

## Element references

`Get Element` returns a reference you can pass to other keywords, so an
expensive lookup is done once:

```robot-repl
${button} =    Get Element    role=button[name="Save"]
Get Element States    ${button}    contains    enabled
Click    ${button}
```

What you get back is a **selector string** — the selector Playwright resolved for
that element — not a snapshot of the DOM node. `Get Elements` returns a list of
them.

That distinction matters in both directions. It re-resolves on every use, so it
survives a re-render that would invalidate a stored node. But it is only a
selector, so it goes in the *first* clause of a chain and nothing more:

```robot-repl
${row} =    Get Element    css=tr.selected
Click       ${row} >> css=button.delete    # relative to the row
```

A reference works like any other first clause, `>>>` included: if it points at
an iframe, `${frame} >>> h1` crosses into it. And there is no `element=` prefix —
the value is already an ordinary selector, so it needs no strategy in front of it.

## In short

- Reach for `role=` first. If you cannot, you may have found an accessibility bug.
- Use `data-testid=` when stability is the priority, knowing what it trades away.
- `text=` is fine until you localise.
- `css=` is acceptable; `id=` is less stable than it looks.
- `xpath=` last, and never by document position.
- `label=` reaches form fields the way a user does.
- Two obvious selectors chained with `>>` beat one clever one.
- `>>>` crosses into a frame; a leading `>>>` searches all of them.
- `nth=` and `visible=` are filters, not strategies: they narrow the step
before them, and their order in a chain changes the answer.


# Assertions

> Almost every getter can assert, every assertion retries, and each return type allows different operators. The complete AssertionEngine reference.

Source: [https://robotframework-browser.org/docs/concepts/assertions](https://robotframework-browser.org/docs/concepts/assertions)

Almost every keyword that gets something can also check it. There is no separate
assertion library, and — this is the part that matters — **the check retries**.

```robot-repl
Get Text    h1    ==    Welcome
```

Three things happen in that one line: the text is read, compared, and if it does
not match yet, read again until it does or the retry window expires. The value is
returned either way, so you can assert and capture at once:

```robot-repl
${title} =    Get Text    h1    ==    Welcome
```

## Why this replaces the waiting code

The classic flaky test looks once, too early:

```robot
# The old shape: look, then hope
Wait Until Element Is Visible    h1
${text} =    Get Text    h1
Should Be Equal    ${text}    Welcome
```

Three keywords, and still a race — the element became visible, then the text
arrived a moment later. The retrying form has no gap between the look and the
check, because they are one operation.

### Two timeouts, and they are not the same

| Setting | Governs | Default |
| --- | --- | --- |
| `timeout` | How long Playwright waits for the **element** to exist | 10s |
| `retry_assertions_for` | How long the **value** is re-read while the assertion fails — never past `timeout` | 1s |

```robot
*** Settings ***
Library    Browser    timeout=15s    retry_assertions_for=5s
```

Element never appears → `timeout`. Element is there but the text is still
`Loading…` → `retry_assertions_for`. Raising the wrong one is the most common
reason a fix does not help — and note that `timeout` bounds the whole keyword,
so `retry_assertions_for=30s` against the default `timeout=10s` still gives you
ten seconds of retrying.

## The operators

### Comparison

| Operator | Also written | True when |
| --- | --- | --- |
| `==` | `equal`, `equals`, `should be` | `value == expected` |
| `!=` | `inequal`, `should not be` | `value != expected` |
| `>` | `greater than` | `value > expected` |
| `>=` | — none — | `value >= expected` |
| `<` | `less than` | `value < expected` |
| `<=` | — none — | `value <= expected` |

```robot-repl
Get Text             h1        ==    Welcome
Get Element Count    .row      >     ${5}
Get Style            body      width    !=    0px
```

### Substring and edges

| Operator | Also written | True when |
| --- | --- | --- |
| `*=` | `contains` | `expected in value` |
| `not contains` | — none — | `expected not in value` |
| `^=` | `starts`, `should start with` | Value starts with expected — a literal, not a pattern |
| `$=` | `ends`, `should end with` | Value ends with expected — literal too |

```robot-repl
Get Text    .banner    *=              Welcome
Get Text    .banner    not contains    Error
Get Url     ^=         https://
Get Url     $=         /checkout
```

`^=` and `$=` escape what you give them, so `$=` with `.html` matches a literal
dot, not any character.

### `matches` — regular expressions

`matches` runs `re.search` over the value. It is spelled `matches` and nothing
else — it has no symbolic alias, as `validate`, `then` and `not contains` also
do not. In particular it is
**not** `$`: that character is the operator's internal value, Robot Framework
rejects it as input, and `$=` is a different operator entirely (*ends with*).

What `matches` *returns* depends on the groups in your pattern, and this catches
people out:

| Pattern has | Returns |
| --- | --- |
| No groups | The whole value, as a string |
| Unnamed groups | A **tuple** of the groups |
| All groups named | A **dictionary** of the groups |

```robot-repl
# No groups — returns the whole string
Get Text    .id    matches    ^ORDER-\\d+$

# Unnamed groups — returns a tuple
${parts} =    Get Text    .date    matches    (\\d+)-(\\d+)-(\\d+)
Should Be Equal    ${parts}[0]    2026

# Named groups — returns a dict
${d} =    Get Text    .date    matches    (?P<year>\\d+)-(?P<month>\\d+)-(?P<day>\\d+)
Should Be Equal    ${d}[year]    2026
```

So `matches` is both an assertion and an extractor. Use `re.search` semantics:
it is not anchored unless you anchor it.

### `validate` — any Python expression

When no operator says it, `validate` gives you one expression with the result
bound to `value`:

```robot-repl
Get Text             h1       validate    value.startswith("Welcome")
Get Element Count    .row     validate    value % 2 == 0
Get Text             .price   validate    float(value.strip("€")) < 100
Get BoundingBox      #card    ALL         validate    value['width'] > 40
```

Getters that return a dictionary — `Get BoundingBox` with `ALL`, `Get Viewport Size`
— are usually asserted this way, indexing into `value` directly. So is
`Get Browser Catalog`, which returns a list of dictionaries and is not restricted
to the list operators — though the string ones (`^=`, `$=`, `matches`) raise a
`TypeError` on a list, so `validate` and `then` are what you actually use.

### `then` — derive instead of check

`then` (also `evaluate`) asserts nothing. It evaluates an expression and returns
the result, so a getter hands back exactly the piece you want:

```robot-repl
${id} =       Get Property    a#link    href     then    value.split("/")[-1]
${count} =    Get Text        .total            then    int(value.strip(" items"))
${upper} =    Get Text        h1                then    value.upper()
```

`then` never asserts, so it never retries — if the expression raises, the
keyword fails immediately. Use `validate` when you need the retry and `then`
only to reshape a value that is already there.

## Which operators a keyword allows

Not every operator works everywhere. The engine picks a rule set from the type
the keyword returns, and using the wrong one is an error, not a failed assertion.

Not every getter asserts, either. `Get Element`, `Get Elements`, `Get Cookie`,
`Get Cookies`, `Get Device`, `Get Devices` and a few others take no assertion
arguments at all — they only return.

| Return type | Allowed | Example keyword |
| --- | --- | --- |
| **String** | All of them | `Get Text`, `Get Url`, `Get Property` |
| **Number** | `==` `!=` `>` `>=` `<` `<=` `validate` `then` | `Get Element Count` |
| **List** | `==` `!=` `contains` `validate` `then` | `Get Classes`, `Get Selected Options`, `Get Attribute Names` |
| **Dictionary** (numeric) | The list set, plus `>` `>=` `<` `<=` per key — those need a real dictionary, `${{ {...} }}`, not a string | `Get BoundingBox`, `Get Viewport Size` |
| **Dictionary** (strict) | `==` `!=` `contains` `validate` `then` | `Get Style` with `ALL` |
| **Boolean** | `==` `!=` only | `Get Checkbox State` |
| **Element states** | Set operators, including `not contains` | `Get Element States` |

Two consequences worth knowing:

**Lists are compared unordered.** With `==` and `!=` the engine sorts both sides
first, so this passes:

```robot-repl
Get Classes    .btn    ==    primary    large    # matches "large primary" too
```

**not contains does not work on lists** — it is absent from the sequence
operators. Use `validate` instead:

```robot-repl
Get Classes    .btn    validate    "disabled" not in value
```

**Booleans use AssertionEngine's own truthiness**, which is not quite Robot's.
Everything is true except `FALSE`, `NO`, `OFF`, `0`, `UNCHECKED`, `NONE` and the
empty string, case-insensitively. So `checked`, `yes` and `true` are True;
`unchecked`, `no` and `false` are False. (`unchecked` is the one that differs
from Robot Framework's own `is_truthy`.)

## Types must match

The expected value is used exactly as written — the library does not convert it.
So it has to already be the type the keyword returns.

```robot-repl
# Get Text returns a string, even when it looks like a number
Get Text             #price    ==    ${99}    # fails: int vs str
Get Text             #price    ==    99       # passes

# Get Element Count returns an integer
Get Element Count    .row      ==    ${3}     # passes
```

Keywords returning numbers *do* convert the expected value for you. Keywords
returning strings do not, and `Get Text` is the one everybody trips over.

Numbers also refuse the text operators outright — `Get Element Count    .row *=    2` raises `ValueError: Operator 'contains' is not allowed.` rather than
failing the assertion. When a
failure shows two values that look identical, print the types — see
[messages](https://robotframework-browser.org/docs/concepts/assertions#custom-messages) below.

### Comparing strings with `<` and `>`

Character by character, by code point, stopping at the first difference. Length
never enters into it:

```text
A < Z        Z < a        ac < dc
'abcde' < 'abd'           '100.000' < '2'
```

Both of the last two surprise people. `'abcde' < 'abd'` because `c` precedes `d`
at the third character and the comparison stops there. `'100.000' < '2'` because
these are strings and `'1'` precedes `'2'` — nothing numeric is involved. You
cannot compare a number with a string in Python, and so not here either.

## Formatters

A formatter normalises the value *before* it is compared, so a test does not fail
on whitespace nobody can see. Ordinary source indentation is not the problem —
`Get Text` reads rendered text, so the browser has already collapsed that. What
survives rendering is what bites: non-breaking spaces (`&nbsp;&nbsp;two spaces&nbsp;&nbsp;`), `<pre>` blocks, and text assembled from several inline
elements.

| Formatter | Does |
| --- | --- |
| `strip` | Removes leading and trailing whitespace |
| `normalize spaces` | Collapses every run of whitespace to one space |
| `case insensitive` | Lower-cases the value |
| `apply to expected` | Not a transform — makes all the others apply to your expected value too |

Set them per keyword:

```robot
*** Test Cases ***
Whitespace Does Not Matter
    Set Assertion Formatters    {"Get Text": ["strip", "normalize spaces"]}
    Get Text    .greeting    ==    Hello World
```

That works on markup like `<p>Hello&nbsp;&nbsp;World</p>`. Without the
formatters the comparison sees `"Hello\xa0\xa0World"` — the browser collapses
ordinary whitespace but not non-breaking spaces — and fails.

They apply **in the order given**, and only to the value:

```robot-repl
# value "  HELLO  " becomes "hello", expected stays "  Hello  " -> fails
Set Assertion Formatters    {"Get Text": ["strip", "case insensitive"]}
Get Text    h1    ==    ${SPACE}${SPACE}Hello${SPACE}${SPACE}
```

Add `apply to expected` and both sides get the same treatment, which is usually
what you meant:

```robot-repl
Set Assertion Formatters    {"Get Text": ["strip", "case insensitive", "apply to expected"]}
Get Text    h1    ==    ${SPACE}${SPACE}Hello${SPACE}${SPACE}    # passes
```

Several keywords at once, and a scope:

```robot
Set Assertion Formatters
...    {"Get Text": ["strip", "normalize spaces"], "Get Property": ["case insensitive"]}
...    scope=Suite
```

The keyword returns the formatters that were set before, so a test can put them
back — normalised to a canonical order rather than the order you supplied. A
formatter written as a lambda is not included at all; only the named rules
survive the round trip.

## Custom messages

A failed assertion has a readable default. To replace it, `message` accepts four
placeholders:

| Placeholder | Is |
| --- | --- |
| `{value}` | What the keyword returned |
| `{expected}` | What you asserted |
| `{value_type}` | The type of the returned value |
| `{expected_type}` | The type of the expected value |

```robot-repl
Get Text    h1    ==    Welcome
...    message=Landing headline was "{value}", expected "{expected}"
```

The two type placeholders exist precisely for the mismatch above — when both
sides look the same and it still fails, printing the types shows why:

```robot-repl
Get Text    #price    ==    ${99}
...    message=Got {value} ({value_type}), expected {expected} ({expected_type})
# Got '99' (str), expected 99 (int)
```

## Common mistakes

| Symptom | Cause |
| --- | --- |
| `... got value 'Welcome' that cannot be converted to AssertionOperator` | An expected value written where the operator belongs |
| `Assertion operator is mandatory when specifying expected value` | `assertion_expected=` passed by name, with no operator |
| Two identical-looking values, still fails | String against number. Print `{value_type}` |
| `Operator ... is not allowed in this Keyword` | A list or dict getter given something outside `==` `!=` `contains` `validate` `then` |
| Fails on invisible whitespace | No formatter. Add `strip` and `normalize spaces` |
| Passes when it should not, on a list | `==` sorts both sides — order is not checked |
| Assertion never retries long enough | Raised `timeout` instead of `retry_assertions_for` |

## In short

- Assert inside the getter, not after it — the retry is the whole point.
- Match the operator to the return type: numbers refuse `contains` and `matches`,
lists refuse `not contains`, booleans take only `==` and `!=`.
- `retry_assertions_for` is for values, `timeout` is for elements.
- Match the type. `Get Text` returns a string.
- Lists take `==` `!=` `contains` `validate` `then`, and `==` ignores order.
Dictionaries take the same set; the numeric ones also take `>` `>=` `<` `<=`,
applied per key against a real dictionary.
- `validate` for whatever the operators do not cover, `then` when you want a
value rather than a check, `matches` when you want both — and it is only ever
spelled `matches`.
- Reach for formatters before you reach for a regular expression.


# Waiting and promises

> Most waiting is already done for you. This is the rest of it — Wait For Condition, and how to run keywords in parallel with Promise To.

Source: [https://robotframework-browser.org/docs/concepts/waiting](https://robotframework-browser.org/docs/concepts/waiting)

Most of the waiting you would write by hand is already happening. This page is
about the part that is not, and about the opposite problem: when you need two
things to happen *at the same time*.

## What waits for you already

Three separate mechanisms, and it is worth knowing which is which, because when
a test is flaky the fix depends on it.

| Mechanism | Waits for | Governed by |
| --- | --- | --- |
| **Actionability** | An element to be attached, visible, stable and able to receive the event — before `Click`, `Fill Text` and friends act | `timeout` |
| **Assertion retry** | A *value* to become what you asserted, re-reading it as often as needed | `retry_assertions_for`, capped by `timeout` |
| **Navigation** | `New Page` and `Go To` to reach their load state before returning | `timeout` |

So this is already a wait, and the most common one you will write:

```robot-repl
Get Text    .status    ==    Done
```

And this is not — no operator, so it reads once and returns whatever is there:

```robot-repl
${status} =    Get Text    .status
```

That difference is the single most useful thing to know about waiting in this
library. A getter *with* an assertion retries; a getter *without* one does not.

Both settings can be changed at import, and at runtime with `Set Browser Timeout`
and `Set Retry Assertions For` — each of which takes a scope, so you can widen
them for one test without widening them for the suite.

## When that is not enough

The built-in waiting covers the element you are about to touch and the value you
are about to check. What it does not cover is everything else the page might be
doing: a spinner that has to *disappear*, an animation that has to finish, a
framework that has to declare itself ready.

Two keywords do that job, and they are siblings. The difference is which side of
the wire the condition lives on.

| Keyword | Evaluates | Reach for it when |
| --- | --- | --- |
| `Wait For Condition` | A Browser **getter**, in Robot Framework | The thing you are waiting for is something a Browser keyword can already read |
| `Wait For Function` | **JavaScript**, inside the page | The thing you are waiting for is only visible to the page itself |

If you can already write a `Get …` assertion for it, use the first. If you would
have to open devtools to see it, use the second.

## `Wait For Condition`

The rule is simple enough that you do not have to learn anything new. Write the
assertion as an ordinary getter first, get it passing, and then take the `Get`
off the front:

```robot-repl
Get Text              id=status_bar    contains    Done
Wait For Condition    Text    id=status_bar    contains    Done
```

Everything after the condition name is that getter's own arguments, so anything
you already know how to assert, you already know how to wait for.

```robot-repl
# The upload finished
Wait For Condition    Text            .progress     ==    100%

# The table filled in
Wait For Condition    Element Count   tbody tr       ==    ${25}

# The single-page app actually navigated
Wait For Condition    Url             should end with    /checkout

# A CSS class arrived
Wait For Condition    Classes         .modal    contains    is-open
```

Most getters that take an assertion can be used, but not all — the id getters,
the storage getters, `Console Log`, `Page Errors` and `Aria Snapshot` are not
among them, and passing one fails with a conversion error rather than waiting.
The keyword documentation lists the exact set.

> **Note:**
> 
> `timeout` here governs how long the **assertion** is retried, not how long an
> element is looked for. It temporarily *sets* `retry_assertions_for` to that
> value — so a short one shortens the retry window just as a long one lengthens it
> — and additionally raises the browser `timeout` if that would otherwise be the
> shorter of the two. Both are restored afterwards.

### The pairing that does most of the work

`Get Element States` returns the *set* of states an element is in right now, and
that is what makes it the most useful condition of the lot: one keyword covers
every "wait until this element is…" case, including the ones no dedicated
keyword exists for.

The states come in opposites, which is the part worth internalising:

| If you are waiting for | Wait for the state |
| --- | --- |
| The element to exist / be gone | `attached` / `detached` |
| It to be shown / not shown | `visible` / `hidden` |
| A control to become usable / unusable | `enabled` / `disabled` |
| A field to accept typing / not | `editable` / `readonly` |
| A box to be ticked / cleared | `checked` / `unchecked` |
| An option to be picked / dropped | `selected` / `deselected` |
| The cursor to land / leave | `focused` / `defocused` |

So the four cases you will actually hit:

```robot-repl
# The overlay is gone from the DOM entirely — not merely invisible
Wait For Condition    Element States    id=cdk-overlay-0    ==    detached

# The submit button became usable after validation
Wait For Condition    Element States    button#submit    contains    enabled

# The field is ready to type into: there, shown, and not read-only
Wait For Condition    Element States    input#search    contains    visible    editable

# Focus moved away, so the blur handler has run
Wait For Condition    Element States    input#amount    contains    defocused
```

`contains` means *all of these are true*, so you can list as many as you need.
`==` means the set is *exactly* that, which is why `== detached` is the honest
way to wait for something to disappear: an element that is gone reports
`detached` and nothing else.

> **Watch out:**
> 
> `stable` is the exception. It is a valid state for `Wait For Elements State`, but
> `Get Element States` never reports it — so `Wait For Condition … contains stable`
> polls until the timeout and fails, always. Wait for `visible` instead, or use
> `Wait For Elements State` with `stable`.

## `Wait For Function`

The other half of the pair. Where `Wait For Condition` asks a Browser getter,
this one runs JavaScript **inside the page** and keeps running it until it
returns something truthy.

Reach for it when the thing you are waiting for is not in the DOM in any way a
selector can express — it is in the application's own state:

```robot-repl
# The framework says it has finished booting
Wait For Function    () => window.myApp.ready === true

# The client-side store has data in it
Wait For Function    () => window.__STORE__.getState().cart.items.length > 0

# A third-party widget has attached itself
Wait For Function    () => typeof window.Intercom === 'function'

# Every image has finished loading — successfully or not
Wait For Function    () => [...document.images].every(i => i.complete)
```

That last one is the flavour of problem this keyword exists for: nothing about
"every image has settled" is expressible as a selector, and no getter returns
it. Note what `complete` actually means — loading *finished*, including having
failed. If you need them to have loaded successfully, add
`&& i.naturalWidth > 0`.

### Waiting on one element

Pass a `selector` and it is resolved and handed to your function as its **first
argument**. The condition then becomes a question about that element, evaluated
in the page where the real computed values live:

```robot-repl
# The app has written an inline width of 100% onto the bar
Wait For Function    element => element.style.width === '100%'    selector=#progress_bar

# The sticky header has settled at the top of the viewport
Wait For Function    el => el.getBoundingClientRect().top === 0    selector=.sticky-header

# Something has actually been drawn into the canvas
Wait For Function    c => c.getContext('2d').getImageData(0,0,1,1).data[3] > 0    selector=canvas#chart
```

Two things to know about that first one. `element.style` is the *inline* style
attribute, not the computed value — it only sees a width the application wrote
onto the element itself, never one that came from a stylesheet. And computed
values are not out of reach for the sibling keyword either: `Wait For Condition`
with `Style` reads `getComputedStyle`, and with `BoundingBox` it reads geometry.
Canvas pixels are the genuine case where only JavaScript will do.

> **Watch out:**
> 
> The selector is resolved in **strict mode**, so it has to match exactly one
> element — which is why the canvas example says `canvas#chart` rather than
> `canvas`. It is also resolved **once**, before polling starts, and the same
> element is handed to every poll. If the application re-renders and replaces the
> node, the function keeps testing the old one.

### Polling

By default it polls on `requestAnimationFrame` — once per frame, which is the
right choice for anything visual, because it re-checks exactly when the browser
repaints. Give `polling` a time instead when you are waiting on something slow
and want to stop burning frames on it:

```robot-repl
Wait For Function    () => window.jobStatus === 'done'    polling=2s    timeout=2min
```

### Two things that catch people

**Truthy is JavaScript's truthy.** `0`, `''`, `null` and `undefined` all read as
"not yet", so `element => element.children.length` waits for a *non-empty* list
without you writing the comparison, and `() => document.querySelector('.x')`
waits for the element to exist, because a missing one is `null`. If your function
takes the element, declare the parameter — a bare `element` inside a zero-argument
arrow is not defined and, thanks to the next paragraph, costs you the whole
timeout before it says so.

**Any error is treated as "not yet"**, for the length of the timeout. That is
what makes `() => window.myApp.ready` safe to run before `myApp` exists — but it
applies to every error, not only the one you were expecting. A typo in your
JavaScript, or a selector that matches two elements, is retried silently for the
full timeout and only then surfaces.

## Choosing between them

| You are waiting for | Use |
| --- | --- |
| Text, a count, a class, an attribute, a URL | `Wait For Condition` |
| An element to appear, vanish, or become usable | `Wait For Condition` with `Element States` |
| A framework or widget to be ready | `Wait For Function` |
| An animation or transition to finish | `Wait For Function` |
| Application state that never reaches the DOM | `Wait For Function` |
| The page to finish loading | `Wait For Load State` |
| A request or response to happen | `Wait For Response` / `Wait For Request` — and promise it, see below |
| A navigation caused by a click | `Wait For Navigation` — promise it too |

Prefer the first wherever it fits. A condition written against a getter fails
with a message naming what the value actually was; a JavaScript one that simply
stayed false fails with a timeout and leaves you to work out why.

## Promises

Everything above waits for something to *become* true. Promises are the
opposite: they let a keyword run while your test carries on doing something
else.

### The idea, if it is new

A promise is a placeholder for a result that does not exist yet.

Normally a keyword blocks: the test stops until it finishes, then continues with
the answer. `Promise To` breaks that in half. It **starts** the keyword and
hands you back a token immediately. The keyword goes on running in the
background while your test does the next thing. Later you present the token and
collect the result — waiting at that point only if it has not finished yet.

```text
ordinary:   ────[ Wait For Response ]────▶ result, then the next keyword

promised:   ──┬─[ Wait For Response ]──┐
              └─[ Click ]──────────────┴──▶ collect the result
```

The reason this matters is that some things can only be observed *while*
something else happens. To catch a network response you have to be listening
before the click that triggers it — but if you start listening with an ordinary
keyword, the test never reaches the click. The listening and the clicking have
to overlap, and that is what a promise is for.

### The call order

Always three steps, in this order:

```robot
*** Test Cases ***
Catch The Response Of A Delayed Request
    ${promise} =    Promise To    Wait For Response    matcher=    timeout=3s
    Click           \#delayed_request
    ${body} =       Wait For      ${promise}
```

1. **Promise To** starts the keyword and returns the promise. It waits until
the promised keyword's thread is actually running before returning, which
removes the worst of the race — though it does not wait for the browser-side
listener itself to be registered.
2. **The thing that triggers it** — a click, a navigation, whatever.
3. **Wait For** collects the result, blocking only if it is not ready.

Getting the order wrong is the usual mistake: click first and the response has
come and gone before anything was listening.

### Collecting several

`Wait For` takes any number of promises and returns their results **in the order
you passed them**, not the order they finished:

```robot-repl
${a} =    Promise To    Wait For Response    matcher=**/api/user
${b} =    Promise To    Wait For Response    matcher=**/api/cart
Click     text=Refresh
${results} =    Wait For    ${a}    ${b}
```

With one promise you get the result itself; with several you get a list.

`Wait For All Promises` waits for everything created and not yet collected,
which is what you want when you do not need the results:

```robot-repl
Promise To    Wait For Response    matcher=**/api/log
Click         text=Save
Wait For All Promises
```

> **Note:**
> 
> A promise you never wait for is not lost. At the end of the test the library
> waits for it anyway and logs a warning that it had to. If you see that warning,
> you have either forgotten a `Wait For` or you did not need the promise.

### Any Browser keyword can be promised

This is the part people miss. `Promise To` is not limited to a handful of
"async" keywords — it takes **any keyword in this library**, with its normal
arguments:

```robot-repl
${title} =      Promise To    Get Title
${clicked} =    Promise To    Click    text=Submit
${count} =      Promise To    Get Element Count    .row    ==    ${10}
```

Which means two slow waits can overlap instead of queueing:

```robot
*** Test Cases ***
Two Slow Panels At Once
    ${left} =     Promise To    Get Text    .left-panel     contains    Loaded
    ${right} =    Promise To    Get Text    .right-panel    contains    Loaded
    Wait For    ${left}    ${right}
```

Both getters retry independently, so the test waits about as long as the slower
one rather than the sum of the two. Promises run on a thread pool — up to 256 at
once — so they really are in flight together rather than taking turns.

> **Watch out:**
> 
> Promise assertion getters like `Get Text`, not `Wait For Condition`.
> `Wait For Condition` works by temporarily rewriting the library's
> `retry_assertions_for` and `timeout` and restoring them when it finishes — so
> two of them running concurrently overwrite each other's settings, and which
> value survives is a matter of timing.

> **Watch out:**
> 
> Only Browser library keywords can be promised. Anything else — a BuiltIn
> keyword, one of your own — fails with *"Unknown keyword … 'Promise To' can only
> be used with Browser keywords."*
> 
> And keep in mind what you are parallelising. Two promises that both act on the
> same page are two things competing for one page; the parallelism is real and so
> are the races. Promises are for *waiting* concurrently far more often than for
> *acting* concurrently.

### The two purpose-built promises

Downloads and uploads both need something in place before the click that starts
them, so they have dedicated keywords rather than being wrapped by hand:

```robot-repl
${dl} =      Promise To Wait For Download    saveAs=${OUTPUT_DIR}/report.pdf
Click        text=Export
${info} =    Wait For    ${dl}

${up} =      Promise To Upload File    ${CURDIR}/avatar.png
Click        text=Choose file
Wait For     ${up}
```

`Promise To Upload File` waits for the *file chooser dialog* to appear, so the
click that opens it has to come after the promise — the same order as everything
else on this page. It fails immediately if the path is not an existing file.

If you can set the file directly, `Upload File By Selector` does it in one
keyword and avoids the ordering question entirely.

## In short

- A getter with an assertion operator is a wait. Without one, it reads once.
- Two keywords cover the rest, and they are siblings: `Wait For Condition` asks a
Browser getter, `Wait For Function` asks the page. If you can write the
`Get …` assertion, use the first.
- `Wait For Condition` needs no new syntax — write the getter assertion, then
drop the `Get`.
- `Wait For Condition` + `Element States` is the one that handles most cases;
the states come in opposites, and `== detached` is how you wait for something
to be gone.
- `Wait For Function` is for what only the page knows: readiness flags,
animations, computed geometry, application state that never reaches the DOM.
A throw counts as "not yet", so it is safe to poll for something that does not
exist yet.
- Promises are start-now, collect-later. The order is always
**Promise To → trigger → Wait For**.
- Any Browser keyword can be promised, and promises really do run in parallel —
promise the getters rather than `Wait For Condition`.


# How Browser works

> Python, a Node process and Playwright — what runs where, and where the files land.

Source: [https://robotframework-browser.org/docs/concepts/architecture](https://robotframework-browser.org/docs/concepts/architecture)

Browser is a Python library that drives [Playwright](https://playwright.dev/)
running in Node.js. The two halves talk over gRPC.

That one sentence explains most of the library's behaviour: why installation has
two moving parts, why there is a second log file, and why a keyword can be fast
even though it crosses a process boundary.

```text
Robot Framework  →  Browser (Python)  →  gRPC  →  Node.js + Playwright  →  browser
```

One Node process drives Chromium, Firefox and WebKit. There is no driver binary
per browser and no driver version to keep in step with a browser update.

## Where the Node.js comes from

The *Node.js + Playwright* box is the one you make a decision about at install
time, and there are two ways to fill it. Either a wheel supplies the Node.js —
`pip install robotframework-browser[bb]`, then `rfbrowser install` — or you
install Node.js yourself and `rfbrowser init` builds against it.

Which to pick, what each needs and how to upgrade either is
[Installation](https://robotframework-browser.org/docs/start/installation). What follows here is what the choice
changes afterwards, which is less than you might expect: the same wrapper, the
same Playwright, the same keywords. It changes where the files sit.

## Where things end up

Everything installs into the Python environment, for example
`.venv/lib/python3.14/site-packages/Browser/`. Node dependencies go to
`Browser/wrapper/node_modules` with `rfbrowser init`, or ship inside
`BrowserBatteries/bin/wrapper/node_modules` with batteries.

Browser binaries are Playwright's, but the location is not Playwright's default:
when `PLAYWRIGHT_BROWSERS_PATH` is unset, Browser sets it to `0`, which puts
them in `Browser/wrapper/node_modules/playwright-core/.local-browsers` — inside
the Python environment rather than in Playwright's shared user cache. Setting the
variable yourself moves them.

Installation logs to the console and to `site-packages/Browser/rfbrowser.log`,
which rotates at about 2 MB and keeps ten previous files. If that directory is
not writable, the log goes to the working directory instead.

## Browser binaries in CI

Downloading browser binaries on every CI run is slow and, where several
environments share a machine, wasteful — because the default puts a copy inside
each installation.

On the Node.js route, install them once outside the library. Run `npx` from the
library's own wrapper directory so the pinned Playwright is used — a bare `npx playwright install` fetches whatever npm resolves, and browser builds are
version-specific:

```bash
rfbrowser init --skip-browsers
cd "$(python -c 'import Browser, pathlib; print(pathlib.Path(Browser.__file__).parent / "wrapper")')"
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright install
```

With batteries there is no npm or npx; the equivalent is
`PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers rfbrowser install`.

Then set the same variable before running the tests:

```bash
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers robot tests/
```

> **Watch out:**
> 
> `PLAYWRIGHT_BROWSERS_PATH` must be set for the `robot` command too, not only for
> the install step. If it is set during install and not during the run, Playwright
> looks in the library's own `.local-browsers` directory, finds it empty, and
> reports that the browser executable does not exist.


# Logging and debugging

> Four places Browser tells you what happened — log.html, the Playwright log, traces and coverage.

Source: [https://robotframework-browser.org/docs/concepts/logging](https://robotframework-browser.org/docs/concepts/logging)

Browser writes to more than one place, because it *is* more than one process.
Knowing which file answers which question saves a lot of guessing.

| Where | What it holds | When to open it |
| --- | --- | --- |
| `log.html` | The Python side: keywords, arguments, status | First. Always. |
| `playwright-log.txt` | The Node side of the library | A keyword failed and log.html does not say why |
| `browser/traces/trace_*.zip` | Every Playwright call, with DOM snapshots | Something failed and you need to see the page as it was |
| Coverage report | Which code the run actually exercised | Asking what the suite does not touch |

## log.html

Most Browser keywords log a message produced by the Node side — often
including the selector and the value used. More of them appear at DEBUG level.

When a keyword fails, the info level already shows the error from the Playwright
call. Running at debug level shows a good deal more:

```bash
robot --loglevel debug --outputdir output tests/
```

## playwright-log.txt

`${OUTPUT_DIR}/playwright-log.txt` holds the Node side. It is written by
default, created when the Node process starts, and not written at all if you
import with `enable_playwright_debug=disabled`.
The Robot log level does not affect it.

The argument takes three values: `library` (the default — only Browser's own
Node messages), `playwright` (those plus Playwright's `DEBUG=pw:api` output), and
`disabled` (no file at all). `False` and `True` are older aliases for the first
two. For much more detail:

```robot
*** Settings ***
Library    Browser    enable_playwright_debug=playwright
```

> **Watch out:**
> 
> The file mixes two formats: the library's own Node messages are JSON lines, and
> Playwright's `DEBUG=pw:api` output is plain text.
> 
> That Playwright output includes **the values passed to fill and type, in
> clear text**. `Fill Secret` and `Type Secret` never write the value to
> `log.html` — the response is not logged and error messages are scrubbed — but
> they cannot stop Playwright's own debug log, and the value also lands in
> `trace.zip`. Treat both as secret-bearing. Do not
> enable this on a run that touches real credentials.

Each run replaces the file. If the old one cannot be deleted — still open on
Windows, for instance — the new log is written beside it as
`playwright-log-<nanoseconds>.txt`.

## Traces

A trace records every Playwright call in a context, with a DOM snapshot at each
step. It is the single most useful artefact when a test fails somewhere you
cannot reproduce.

```robot-repl
New Context    tracing=True
```

The zip is written when the **context closes** — automatically at the
auto-closing level, or when you call `Close Context`. Do not go looking for it
while the browser is still open.

To record without passing `tracing=` in every test, set the environment variable
`ROBOT_FRAMEWORK_BROWSER_TRACING=True`. It applies to every `New Context` and
`New Persistent Context` — a context that `New Page` creates implicitly is *not*
traced, so a suite that never calls `New Context` records nothing. And
`auto_delete_passed_tracing=True` at import keeps only the traces of failed
tests, which is what makes this affordable in CI:

```bash
ROBOT_FRAMEWORK_BROWSER_TRACING=True robot --outputdir output tests/
```

Open the result either way:

```bash
rfbrowser show-trace output/browser/traces/trace_context=<id>.zip
```

or drop it on [trace.playwright.dev](https://trace.playwright.dev/), which runs
entirely in your browser.

## Coverage

Browser can collect code coverage from the pages it drives — data from
Playwright, report from
[monocart-coverage-reports](https://www.npmjs.com/package/monocart-coverage-reports).

Coverage is enabled **per page**:

```robot
*** Test Cases ***
Checkout Coverage
    New Page    https://example.com/checkout
    Start Coverage    raw=True
    Take Screenshot
    Stop Coverage
```

Combine the per-page data into one report:

```bash
rfbrowser coverage output/browser/coverage/ output/report
```

Combining needs the raw data, which is why `Start Coverage` above passes
`raw=True`. Note that `raw` is ignored when you also pass `config_file` — then
you have to add `['raw']` to `reports` in the config yourself — without it there is nothing to merge and the command fails with
`No raw reports found`. The same thing is available as the
`Merge Coverage Reports` keyword.

Monocart takes a [config file](https://www.npmjs.com/package/monocart-coverage-reports#config-file)
if you need filtering, which you probably will — third-party bundles otherwise
dominate the numbers.


# Recording keywords

> Click through the page and get a reusable user keyword, written into your suite while you work. Record Keyword and Record Keywords in five minutes.

Source: [https://robotframework-browser.org/docs/recording/record-keywords](https://robotframework-browser.org/docs/recording/record-keywords)

*(since Browser 21.0.0)* You click through the page; Browser writes what you did as a
**user keyword** into your suite file — live, while you click, ready to call from any
test.

**Video**: A browser shows robotframework-browser.org. The recorder toolbar sits in the bottom right corner. The pointer opens Keywords, types Get Text into the search field and opens the Get Text keyword; with every click a new Keyword Call appears in the toolbar. Finally the toolbar's close button ends the recording.

`Record Keyword` with the name `Find The Get Text Keyword` — three clicks and a search become four
Keyword Calls.

## Keywords, not tests

A recorder that writes whole test cases produces long, brittle scripts nobody
wants to maintain. Browser records **one keyword at a time**, from wherever your
test happens to be: after the login, on the right page, with the right data.
You decide what the test does and which keywords it needs; the recorder fills in
the steps of one of them.

That changes how you use it:

- **You name the keyword while you record**, so it reads like your test design —
`Add Product To Cart`, not `Test 17`.
- **It starts where your test stands.** The setup is code you already have; the
recording begins after it.
- **Wrong steps are undone in place.** Click the wrong thing, press *Undo*, carry on.
- **Values become arguments** with a click, so the keyword is reusable from the
first run — see [Keyword arguments](https://robotframework-browser.org/docs/recording/arguments).

## Your first recording

The recorder needs a browser you can see. Put `Record Keyword` where the keyword
should start:

```robot [first-recording.robot]
*** Settings ***
Library    Browser

*** Test Cases ***
Look Up A Keyword
    New Browser    chromium    headless=False
    New Page       https://robotframework-browser.org
    Record Keyword    Find The Get Text Keyword
```

Run it. The page opens with the **recorder toolbar**, already recording. Now do in
the page what the keyword should do. Each action shows up in the toolbar as a
Keyword Call the moment you make it:

| # | You do in the page | Recorded as |
| --- | --- | --- |
| 1 | Click *Keywords* in the header | `Click` on the *Keywords* link |
| 2 | Click the search field | `Click` on the search field |
| 3 | Type `Get Text` | `Fill Text` with `Get Text` |
| 4 | Click *Get Text* in the keyword list | `Click` on that entry |

Then click **✕** in the toolbar's header to end the recording. The test continues
with its next line, and `first-recording.robot` now ends with the four Keyword
Calls:

```robot
*** Keywords ***
Find The Get Text Keyword
    [Tags]    recorded
    Click    role=link[name="Keywords"s]
    Click    role=searchbox[name*="Filter keywords"i]
    Fill Text    role=searchbox[name*="Filter keywords"i]    Get Text
    Click    role=link[name*="Get Text 5"i]
```

The same happens on any page. A login on [car.keyword-driven.de](http://car.keyword-driven.de),
recorded live — every click and every field becomes a Keyword Call the moment it happens:

**Video**: A login form. The pointer types demo as user name and secret as password and clicks login; the recorder toolbar next to the form lists Click, Fill Text, Click, Fill Text and Click as they happen.

Five Keyword Calls in eight seconds: the toolbar shows each one as it is written.

> **Note:**
> 
> Every recorded keyword is tagged `recorded`. It marks the keywords nobody has
> reviewed yet — read them before you commit, as described in
> [Good practice and limits](https://robotframework-browser.org/docs/recording/practice).

## One keyword or a session

| Keyword | Records | Ends with |
| --- | --- | --- |
| `Record Keyword` with a name | Exactly one keyword, named in the call. The toolbar records from the first moment. | ✕ in the toolbar |
| `Record Keywords` | Any number of keywords. Each is named and started in the toolbar, then saved; in between nothing is recorded, so you can move to the next starting point. | ✕ in the toolbar |

`Record Keyword` fits a test that is missing one step. `Record Keywords` fits
building a keyword library: walk through the application once and save a
keyword at every stop. Both block until the recording ends, return the recorded
text, and write into the suite file unless you say otherwise — see
[Where recorded keywords go](https://robotframework-browser.org/docs/recording/files).

```robot-repl
${text} =    Record Keyword    Login As Admin
Record Keyword     Search Product    ${CURDIR}/shop.resource
Record Keywords    ${CURDIR}/shop.resource
```

## In this chapter

**The toolbar**

Starting, saving, undoing and ending; naming rules; moving the toolbar out of the way.

**Arguments**

Turn a typed value, a URL or part of a selector into an argument, with or without default.

**What gets recorded**

Which Browser keyword each action becomes, popups, dialogs, downloads, uploads and assertions.

**Target files**

The suite file, a resource file, or only the log — and what the recorder never touches.

**Practice and limits**

How to get keywords worth keeping, what the recorder cannot do, and what to do when it goes wrong.


# The recorder toolbar

> Name and start keywords, save, undo and discard them, end the session, and keep the toolbar out of the page's way.

Source: [https://robotframework-browser.org/docs/recording/toolbar](https://robotframework-browser.org/docs/recording/toolbar)

The toolbar is how you talk to the recorder: it shows the keyword being recorded
and every Keyword Call in it, and its buttons start, save, correct and end the
recording. It sits on top of every page of the browser context and follows you
through navigation and new tabs.

**Video**: Record Keywords on the Getting started page. The toolbar starts idle; Record keyword opens a dialog where the name Open The Assertions Guide is typed. A click on Assertions is recorded, a click on the page heading is recorded and removed again with Undo, then Save. The toolbar is minimized, its header button Start names a second keyword, Switch The Colour Theme, the theme button is clicked, and the header button Save stores it. The close button ends the session.

`Record Keywords`: two keywords in one session, a mistake undone, and the
minimized toolbar's *Start* and *Save*.

## Reading the toolbar

![The recorder toolbar recording Register At The Shop, with the button Pick in its header: three Keyword Calls with the keywords in teal, values in beige and the argument user in orange, the argument list showing user with its default, and the buttons Discard, Undo and Pause.](https://robotframework-browser.org/images/recorder/toolbar-recording.png)

The header names the keyword being recorded and counts its Keyword Calls.

The list shows each Keyword Call as it is written into the file, coloured like
Robot Framework source: **keywords** in teal, **values** in beige, **variables**
in orange — Keyword Arguments and an assigned `${download}`.
An escaped value stays a value: `\${HOME}` and the escaped spaces in `two \ spaces`
are beige, because Robot reads them as text. Underlined values can become [arguments](https://robotframework-browser.org/docs/recording/arguments); the
arguments of the keyword are listed below the calls.

## A session, step by step

`Record Keywords` opens the toolbar **idle**: nothing you do is recorded. Move to
where the first keyword should begin, then:

![The idle toolbar: no keyword is being recorded, the hint says 0 keywords recorded, and the button Record keyword.](https://robotframework-browser.org/images/recorder/toolbar-idle.png)

Idle: nothing is recorded until *Record keyword*.

1. **Record keyword** asks for the name. Type it and press Enter. The dialog
stays open, dimmed, until the recorder has accepted the name; a name it
rejects is shown in the dialog with the reason, so you can correct it.
2. Work in the page. Every action appears in the toolbar as a Keyword Call and is
written to the file at once.
3. **Save** stores the keyword and returns to idle. Navigate to the next starting
point and begin again with step 1.
4. **✕** in the header ends the session. A keyword still being recorded is saved
first; the test continues with the next line.

`Record Keyword` skips step 1 — the name comes from the call — and records from
the first moment; *Save* or *✕* saves the keyword and ends the session.

## The buttons

| Button | Where | Does |
| --- | --- | --- |
| **Record keyword** | Body, idle | Names and starts the next keyword. `Record Keywords` only. |
| **Save** ✓ | Body, recording | Saves the keyword. `Record Keywords` returns to idle; `Record Keyword` ends the session. |
| **Undo** | Body, recording | Removes the Keyword Calls of the last action — all of them, for an action that produced several, like a download. |
| **⏸** / **▶ Resume** | Body, recording | Pauses the recording: nothing you do is recorded until *Resume*. Use it to set something up by hand in the middle of a keyword. |
| **Discard** | Body, recording | Drops the keyword, also from the file. `Record Keyword` starts it again empty; `Record Keywords` returns to idle. |
| **Pick** | Header, recording | Picks an element on the page and adds its selector to the keyword as a comment — see [Picking a selector](https://robotframework-browser.org/docs/recording/toolbar#picking-a-selector). |
| **–** / **+** | Header | Minimizes the toolbar to its header, or expands it. |
| **Start** / **Save** | Header, minimized | The main action stays one click away while the toolbar is small. *Start* is for `Record Keywords` only. |
| **✕** | Header | Ends the session. The keyword being recorded is saved. |

Every button has a tooltip. After *Save*, *Discard*, *Start*, *Pause* and *Resume* the toolbar waits
a moment before it acts: Playwright reports a click half a second late, and a
click made just before *Save* still belongs to the keyword. If you have not
clicked in the page for a second, there is no wait.

### Pause and Resume

**⏸** stops recording without ending the keyword: nothing you do is recorded
until **▶ Resume**. Use it to set something up by hand — accept a cookie banner,
open a menu, log in with a real account — in the middle of a keyword. The header
says *paused*, and the indicator turns orange.

**Video**: The user name demo is typed and recorded. Pause is pressed; the password typed next is not recorded and the toolbar shows paused. Resume is pressed, and the click on login is recorded again.

Typed while paused, the password never reaches the keyword.

A click made just before *Pause* still belongs to the keyword; one made just
before *Resume* does not.

### Undo and Discard

*Undo* takes back the last action, as often as you like. It removes Keyword Calls;
it does not reverse what the action did to the page. After undoing a click that
navigated, you are still on the new page — continue from there, or go back, and
check that the toolbar lists what you expect before you go on.

*Discard* throws the whole keyword away. In `Record Keywords` the session goes on,
idle, so you can start the keyword again from a better starting point.

### Picking a selector

Some selectors are not for a click: an element the keyword should check or wait
for later. **Pick** gets one without leaving the recording. The Keyword Calls
make way for the panel of [Record Selector](https://robotframework-browser.org/docs/recording/selectors) — Playwright's
or a CSS selector, editable, with its count on the page — and nothing you do is
recorded while it is open.

- **Use** adds the selector to the keyword as a comment, ready for the line you
write by hand later. *Undo* removes it like a Keyword Call.
- **Cancel** returns to recording without it.

```robot
*** Keywords ***
Log In
    Fill Text    role=textbox[name*="username"i]    demo
    # Picked Selector    role=heading[name*="Welcome"i]
```

Recording goes on either way. The pick works in the tab whose toolbar you
pressed it in. Playwright's own *Pick locator* opens the same panel, in the tab
you last clicked in; while the toolbar is idle, it asks you to start a keyword
first.
Minimized, the header offers *Reselect* and *Use* once an element is picked and
*Cancel* throughout; *Save*, *Discard*, *Undo* and *Pause* wait until the pick is
used or cancelled.

## Naming keywords

A name is rejected — in the dialog, with the reason — when it:

- already exists in the target file, or was recorded earlier in the session;
- would **shadow** a keyword the suite can already call, such as `Click` or a
keyword of one of your resources;
- cannot be a single Robot Framework name: two spaces in a row, a leading `#`,
`*` or `|`, variable syntax like `${x}`, line breaks or tabs, or more than 200
characters.

Name keywords after what they do for the test — `Add Product To Cart`,
`Open The Assertions Guide` — not after the page they happen on.

## Ending a session

| What ends it | The keyword being recorded |
| --- | --- |
| **✕** in the toolbar, or *Save* in `Record Keyword` | Saved |
| Playwright's **Record** button (the red circle at the top centre) | Saved |
| No action and no toolbar command for `idle_timeout` (default 5 minutes) | Saved |
| All pages of the context closed, or the context itself | Saved |
| An error | Saved, then the keyword fails |

A keyword without any Keyword Call is never written. The idle timeout keeps a
forgotten recording from blocking a run for good; set it with
`idle_timeout=15 min`, or to `${None}` to wait without limit.

## Keeping it out of the way

- **Move** the toolbar by dragging its header. It stays where you put it, also
across navigation and reloads, and sits flush against any edge you push it to.
- **Resize** it with the grip in its bottom right corner; by default it grows
with the longest Keyword Call.
- **Minimize** it with **–**; the header then offers *Start* or *Save*, so the
main action stays one click away.

![The minimized toolbar: only its header, with the state Idle, the button Start, and the buttons to expand and to close.](https://robotframework-browser.org/images/recorder/toolbar-minimized.png)

Minimized and idle: *Start* names the next keyword.

Typing in the toolbar never reaches the page: its shortcuts and type-ahead do not
fire while you name a keyword. Nor is anything you do in the toolbar recorded — a
resize released over the page, or keys pressed after a click on the toolbar's
text. A modal dialog of the page — one that disables
clicks outside itself, traps the focus or closes on a click outside — does not
block the toolbar either, and using the toolbar does not close it.

> **Watch out:**
> 
> A **native** modal `<dialog>` (opened with `showModal()`) makes everything else on
> the page inert, the toolbar included. Close the dialog to use the toolbar again.

## Next to Playwright's toolbar

During a session you also see **Playwright's own toolbar** at the top centre of
the page. It cannot be hidden, and two of its tools are useful:

- the **assertion tools** (eye, text, value, snapshot) record checks — see
[Assertions](https://robotframework-browser.org/docs/recording/what-gets-recorded#assertions);
- its **Record** button ends the session, like ✕.

Its *Pick locator* opens the toolbar's own picker — see
[Picking a selector](https://robotframework-browser.org/docs/recording/toolbar#picking-a-selector).


# Keyword arguments

> Turn a recorded value, part of it or part of a selector into an argument while you record — with or without a default, and everywhere it occurs.

Source: [https://robotframework-browser.org/docs/recording/arguments](https://robotframework-browser.org/docs/recording/arguments)

A keyword that always creates the account `jane@example.com` is useful once.
Make the name and the password **arguments** while you record, and the same
keyword creates any account. Values in the toolbar that can become an argument
are underlined; click one.

**Video**: A Create account form with the fields Email, Confirm email, Password and Confirm password, and the recorder toolbar beside it with five recorded Keyword Calls. A click on the value jane@example.com opens the argument dialog; jane is marked, the name name is typed and the default checkbox is cleared. The toolbar offers to use the argument in the Confirm email call too, and Replace accepts. The same follows for the password Secret-123 as the argument password. The toolbar lists the arguments name and password.

`jane` becomes `${name}`, `Secret-123` becomes `${password}`, each in both fields.

```robot
*** Keywords ***
Create Account
    [Tags]    recorded
    [Arguments]    ${name}    ${password}
    Fill Text    role=textbox[name="Email"s]    ${name}@example.com
    Fill Text    role=textbox[name*="Confirm email"i]    ${name}@example.com
    Fill Text    role=textbox[name="Password"s]    ${password}
    Fill Text    role=textbox[name*="Confirm password"i]    ${password}
    Click    role=button[name*="Create account"i]
```

```robot-repl
Create Account    jane    Secret-123
Create Account    max    ${NEW_PASSWORD}
```

## The argument dialog

![The argument dialog: the value jane@example.com with jane marked, the argument name name, the cleared box Use the marked value as default, and the buttons Cancel and Make argument.](https://robotframework-browser.org/images/recorder/toolbar-argument-dialog.png)

Only the marked part, `jane`, becomes the argument `${name}`, without a default.

Clicking a value opens a dialog with three things to decide:

1. **Which part.** The value is shown in full. Leave it unmarked to turn the
whole value into the argument, as with the password, or mark a part of it —
only that part becomes the argument, as `jane` in the address. The marked
part stays highlighted when you move on to the name.
2. **The name**, as `name` or as `${name}`.
3. **Whether the recorded value becomes the default.** Checked, callers may leave
the argument out; unchecked, they must pass it. A new account needs a new
name and nobody wants a password built into a keyword, so both are unchecked
here.

*Make argument* applies it. A name the recorder cannot accept is shown in the
dialog, which stays open so you can correct it; *Cancel*, Escape or a click
beside the dialog close it without changes.

Arguments without a default always come first, as Robot Framework requires. Give
a default only to arguments recorded after all those without one, and
`[Arguments]` keeps the order of the recording.

## Part of a value

Marking a part is how addresses, URLs, IDs and composed texts become arguments.
The rest of the value stays as it was — here `@example.com` — escaped where
Robot Framework needs it:

```robot
Fill Text    role=textbox[name="Email"s]    ${name}@example.com
```

A value that already contains an argument cannot get a second one.

## Selectors

Selectors can become arguments too — whole, or in part. That turns one recorded
click into a keyword for a whole family of elements:

**Video**: The Getting started page. A click on Assertions in the side navigation is recorded. In the toolbar the selector of that click is opened in the argument dialog, the word Assertions inside it is marked, and the argument is named chapter.

The chapter name inside the selector becomes `${chapter}`.

```robot
*** Keywords ***
Open A Docs Chapter
    [Tags]    recorded
    [Arguments]    ${chapter}=Assertions
    Click    role=link[name="${chapter}"s]
```

```robot-repl
Open A Docs Chapter    Finding elements
Open A Docs Chapter    chapter=Waiting and promises
```

Mark only the part that varies. The structure around it — `role=link`,
`[name=…]`, the `s` that makes the match exact — is what keeps the selector
precise.

## The same value elsewhere

When the value you made an argument occurs in other Keyword Calls of the same
keyword, the toolbar offers to use the argument there too. Each occurrence is
listed with a checkbox, all checked: *Replace* uses the argument for the checked
ones, *Skip* leaves them as they are.

![The toolbar offers to use the new argument name for jane in the Fill Text call of the Confirm email field, where jane is marked red like in the argument dialog, with a checked box and the buttons Skip and Replace.](https://robotframework-browser.org/images/recorder/toolbar-offer.png)

`jane` also occurs in the confirmed address; the occurrence is offered, already checked, with the part it replaces marked.

That is how both email fields and both password fields of `Create Account` get
the same argument: one argument per value, replaced in every field that repeats it.

## While you keep typing

Make an argument from a field you are still typing into, and the argument
stays: the Keyword Call keeps `${name}`, and its default follows what you type.
*Undo* removes an action together with any argument that only it used — a
recorded keyword never declares an argument it does not use.

## Names

An argument name is plain — `name` — or written as a variable — `${name}`.
It must:

- start with a letter or `_` and contain only letters, digits and `_`;
- not be a Robot Framework built-in variable such as `${TEMPDIR}` or `${SPACE}`;
- not be taken already in the keyword, in any spelling Robot Framework treats as
equal — `Name`, `na_me` and `name` are one name. Variables the recorder
assigns itself, like `${download}` and `${upload}`, count too;
- be at most 200 characters long.

The dialog checks while you type and again when you confirm.


# What gets recorded

> Which Browser keyword each action becomes, how popups, dialogs, downloads and uploads are handled, recording assertions, and the selectors the recorder writes.

Source: [https://robotframework-browser.org/docs/recording/what-gets-recorded](https://robotframework-browser.org/docs/recording/what-gets-recorded)

Playwright watches the page and reports each **action** — a click, a fill, a key
press. The recorder turns each one into a **Keyword Call** to a Browser keyword,
the same keyword you would have written by hand.

## Actions

| You | Recorded as |
| --- | --- |
| Click | `Click` with the selector |
| Double-click, right-click, click with Shift / Ctrl / Alt / Meta | `Click With Options` with the button, the modifiers and `clickCount` |
| Type into a field | `Fill Text` with the text — one call per field, however you typed it |
| Press Enter, Tab, Escape, a shortcut | `Press Keys`, modifiers joined with `+` |
| Tick or untick a checkbox | `Check Checkbox` / `Uncheck Checkbox` |
| Choose in a `<select>` | `Select Options By` with `value` and the chosen options |
| Navigate by URL or bookmark | `Go To` with the URL |
| Close a tab | `Close Page` — see [Working in several tabs](https://robotframework-browser.org/docs/recording/what-gets-recorded#working-in-several-tabs) |

```robot-repl
Click    role=button[name="Save"s]
Click With Options    role=row[name*="Order 4711"i]    right    Shift    clickCount=2
Fill Text    role=textbox[name*="Email"i]    jane@example.com
Press Keys    role=textbox[name*="Search"i]    Enter
Check Checkbox    role=checkbox[name*="Remember me"i]
Select Options By    role=combobox[name*="Country"i]    value    de
Go To    https://shop.example.com/cart
```

A navigation within five seconds of a click, fill or key press belongs to that
action — the click on a link *is* the navigation — so it gets no `Go To` of its
own. A recorded keyword never opens a browser or a page: it runs in whatever page
its caller set up, which is what makes it reusable.

## Popups, dialogs, downloads and uploads

Some actions need Browser keywords **around** them. Playwright reports these after
the action; the recorder puts the calls where Browser needs them. *Undo* removes
them together with the action.

**A new tab or popup** is followed by switching to it:

```robot-repl
Click    role=link[name="Open in new tab"s]
Switch Page    NEW
```

### Working in several tabs

The recorder knows which tab every action happens in. When the next action is in
another tab than the last one, it switches there first. `Switch Page` returns the
id of the tab it leaves, so the keyword can come back to it; the recorder
assigns that id to a variable once an action needs it:

```robot-repl
Click    role=link[name="Open in new tab"s]
${page}=    Switch Page    NEW
Fill Text    role=textbox[name*="Search"i]    shoes
Switch Page    ${page}
Click    role=button[name="Save"s]
```

Closing the active tab becomes `Close Page`; Browser then returns to the tab
before it. Closing another tab closes it by its id: `Close Page` with `${page}`.
A tab that was already open when the recording started, or that you opened by
hand, has no id the keyword knows: an action there is recorded without a switch,
and the toolbar says so.

**An alert, confirm or prompt** gets its handler before the click that opens it.
Playwright does not report whether you accepted it, so the recorder accepts:

```robot-repl
Handle Future Dialogs    action=accept
Click    role=button[name="Delete"s]
```

**A download** is wrapped in a promise:

```robot-repl
${download}=    Promise To Wait For Download
Click    role=link[name="Export as CSV"s]
Wait For    ${download}
```

**An upload** through a file chooser is wrapped the same way. The page never
learns which folder the file came from, so the path starts with a placeholder;
the toolbar reminds you to fill it in:

```robot-repl
${upload}=    Promise To Upload File    <define_path_to_file>/report.zip
Click    role=button[name="Open Report"s]
Wait For    ${upload}
```

Replace `<define_path_to_file>` with the folder — `${CURDIR}/testdata` — or mark
it in the toolbar and make it an [argument](https://robotframework-browser.org/docs/recording/arguments). When no
click opened the chooser, the recorder sets the file on the input directly:

```robot-repl
Upload File By Selector    input[type="file"]    <define_path_to_file>/report.zip
```

## Assertions

A keyword that only clicks proves nothing. **Playwright's toolbar** at the top
centre of the page has four assertion tools: pick one, then click the element to
check.

**Video**: The Assertions page with both toolbars. The eye tool in Playwright's toolbar is chosen and the page heading clicked: a visibility check is recorded. Then the text tool is chosen, the heading clicked, and the proposed text Assertions accepted with the check mark: a text check is recorded.

Assert visibility, then assert text — each a Keyword Call with a retrying
assertion.

| Tool | Recorded as |
| --- | --- |
| Assert visibility (eye) | `Get Element States` with `*=` and `visible` |
| Assert text (ab) | `Get Text` with `contains` and the text — or `==` when you check the whole text |
| Assert value, on a field | `Get Property` with `value`, `==` and the value |
| Assert value, on a checkbox | `Get Checkbox State` with `==` and `checked` or `unchecked` |
| Assert snapshot | `Get Aria Snapshot` with `yaml`, `==` and the element's accessibility tree |

```robot
*** Keywords ***
Check The Assertions Page
    [Tags]    recorded
    Get Element States    role=heading[name*="Assertions"i]    *=    visible
    Get Text    h1    contains    Assertions
```

These are ordinary Browser getters, so they **retry** until the page catches up —
see [Assertions](https://robotframework-browser.org/docs/concepts/assertions). The expected values are arguments
like any other: make `Assertions` an argument and the keyword checks any page.

## Selectors

Playwright picks each selector the way its own code generator does: a test id if
the element has one, then role and accessible name, placeholder, label, alt text,
text and title, and CSS as a last resort — the best of these that finds only
this element. The recorder writes them in Browser's public selector syntax, with
the same meaning:

| Element | Recorded selector |
| --- | --- |
| A link or button found by its name | `role=link[name="Keywords"s]` — exact; `name*="…"i` — contains, any case |
| An element with a test id | `[data-testid="theme-toggle"]` |
| A field found by its placeholder | `[placeholder*="Email"i]` |
| Text without a role | `text=/^\s*Plain\s+text\s*$/` — the whole text, exactly |
| One of several similar elements | `… >> nth=1`, or `div:has-text("Card one")` |
| Inside an iframe | `#frame >>> role=button[name*="Pay"i]` |
| Two or more frames deep | `>>> #inner >>> role=button[name*="Pay"i]` — in whichever frame it is |
| A widget known only by its label | `label="Map"i` — from `aria-label`, `aria-labelledby` or a `<label>` |

Every selector finds exactly the element you clicked when it was recorded; the
library's tests check this for each kind of selector Playwright generates. Whether it
still finds it tomorrow depends on the page: a name with a counter in it, like
`role=link[name*="Get Text 5"i]`, breaks when the count changes. Shorten such a
selector, or make the changing part an [argument](https://robotframework-browser.org/docs/recording/arguments#selectors).

> **Note:**
> 
> Rarely, a selector has no public form — an attribute with an empty value, say. It
> stays in Playwright-internal syntax, which works but may change with a Playwright
> upgrade, and the toolbar says so.

## Values are written exactly

Whatever you typed is what the keyword types, even where it means something to
Robot Framework. Spaces Robot would read as a cell separator or strip at a cell
edge are escaped with a backslash, so no two plain spaces meet:

```robot-repl
Fill Text    id=ref       \#42                      # not a comment
Fill Text    id=name      two \ spaces              # not a cell separator
Fill Text    id=path      \${HOME}/reports          # not a variable
Fill Text    id=note      first line\nsecond line   # a line break
Fill Text    id=code      \ padded \                # edge spaces kept
Fill Text    id=tail      two trailing \ \          # both trailing spaces kept
Fill Text    id=empty     ${EMPTY}                  # the field was cleared
```

Password fields get no special treatment: what you type is recorded as typed.
Make it an argument without a default, so the keyword never holds a secret — see
[Good practice and limits](https://robotframework-browser.org/docs/recording/practice).

## Not recorded

- **Hovering.** Playwright does not report it. Add `Hover` by hand where a menu
needs it.
- **Anything while the toolbar picks a selector** with *Pick* in the toolbar or *Pick
locator* in Playwright's — see [Picking a selector](https://robotframework-browser.org/docs/recording/toolbar#picking-a-selector).
- **Actions a later Playwright version adds.** Every action Playwright reports
today has a Browser keyword. One without names itself in a notice; the keyword
stays as it was.
- **Other browser contexts.** Only the context that was active when the
recording started is recorded.


# Where recorded keywords go

> The suite file, a resource file or only the log; written live after every action; what the recorder changes in a file and what it never touches.

Source: [https://robotframework-browser.org/docs/recording/files](https://robotframework-browser.org/docs/recording/files)

Both recording keywords take a `file` argument. Wherever it points, the keyword
is written **after every action**, not at the end — a crashed browser or a
killed run leaves everything recorded so far behind.

## Choosing the file

| file | Writes to |
| --- | --- |
| *(not given)* | The suite file that is running — `${SUITE_SOURCE}`. The keyword lands next to the test that recorded it. Called from a suite initialisation file, it goes into that `__init__.robot` — and can then only be used in that file. |
| `${CURDIR}/keywords.resource` | A resource file, created if it does not exist. Use `${CURDIR}` for a path next to the suite; a relative path is resolved against the working directory, not the suite. |
| `${None}` | No file at all. The keywords go to the console and the log, at INFO level. |

```robot-repl
Record Keyword     Add Product To Cart
Record Keyword     Add Product To Cart    ${CURDIR}/shop.resource
Record Keywords    ${CURDIR}/shop.resource
Record Keyword     Try Something         file=${None}
```

A resource file is the usual home for a keyword library: import it in the
suites that need it.

```robot
*** Settings ***
Library     Browser
Resource    shop.resource
```

`${None}` is for trying things out — and for pipelines where nothing may write
to the sources. Both keywords also **return** the recorded text, including the
`*** Keywords ***` header, whatever `file` says:

```robot-repl
${keywords} =    Record Keywords    file=${None}
Log    ${keywords}
```

## What the recorder changes in a file

The recorder owns **only the keyword it is recording**. Before every save it
reads the file again and replaces that one block; the rest is left as it is on
disk at that moment. So you can keep the file open in your editor and even
change other parts of it while recording.

- A missing `*** Keywords ***` section is added at the end of the file.
- The file keeps its line endings (LF or CRLF), its byte order mark and whether it
ends with a newline.
- An **existing keyword is never extended or overwritten.** A name that is
already in the file is rejected when you start recording.
- If you edit the block of the keyword *while* it is being recorded, the next
action writes the recorded version again, and the toolbar tells you so.
- A file that is not valid UTF-8 is refused rather than rewritten, with the
reason in the toolbar.
- *Discard* removes the keyword from the file again.

The folder must exist, and an existing file must be writable — a read-only file
is never overwritten. Both are checked **before** recording starts, so a typo in
the path fails at once, not after ten minutes of clicking.

If the file stops being writable during the session — the disk fills up, another
tool locks it — the toolbar shows the error, the keyword stays in memory and the
next action tries again. A keyword that still cannot be written when the session
ends is never lost silently: `Record Keyword` fails, and the recorded text is in
the log as a warning, ready to copy.

## When the new keyword is usable

Robot Framework reads a suite before it runs it, so a keyword recorded into the
running suite exists from the **next** run on. To use it in the same run, record
into a resource file and import it afterwards:

```robot
*** Test Cases ***
Record And Use
    New Browser    chromium    headless=False
    New Page       https://robotframework-browser.org
    Record Keyword    Find The Get Text Keyword    ${CURDIR}/recorded.resource
    Import Resource    ${CURDIR}/recorded.resource
    Go To    https://robotframework-browser.org
    Find The Get Text Keyword
```

## The idle timeout

A recording ends by itself after `idle_timeout` without an action or toolbar
command — 5 minutes by default — so a forgotten recording cannot block a run
forever. The keyword being recorded is saved.

```robot-repl
Record Keywords    ${CURDIR}/shop.resource    idle_timeout=20 min
Record Keywords    ${CURDIR}/shop.resource    idle_timeout=${None}
```

`${None}` waits without limit; use it only where somebody is sure to end the
session.


# Recording selectors

> Pick an element in the live browser and get a selector for it — Playwright's or a CSS one, checked against the page while you edit it.

Source: [https://robotframework-browser.org/docs/recording/selectors](https://robotframework-browser.org/docs/recording/selectors)

Sometimes you need one selector, not a whole keyword. `Record Selector` stops the
test, lets you point at the element in the browser and returns a selector for it:

```robot
*** Test Cases ***
Find The Login Button
    ${selector} =    Record Selector    Login button
    Click    ${selector}
```

**Video**: A login form with the Record Selector toolbar beside it. The pointer moves over the form; Playwright highlights each element under it. A click on the login button picks it: the toolbar shows role=button[name*="login"i] and 1 match. Switching to CSS shows .loginButtonStyle; Use returns it.

Hover, click to pick, switch the generator, use the selector.

## Picking

Move the pointer over the page: Playwright highlights the element under it and
names it in a tooltip. A click picks it — the click does not reach the page, so
nothing is submitted or opened. Elements in frames and in open shadow roots can be
picked too.

The toolbar is the one [Record Keyword](https://robotframework-browser.org/docs/recording/toolbar) uses, with its
header showing the label you passed — `Login button` above — so you know what to pick.

## The selector

![The Record Selector toolbar for Login button: the buttons Playwright and CSS with Playwright chosen, the selector role=button[name*="login"i] in colour, 1 match below it, and the buttons Highlight (an icon, switched on), Reselect and Use.](https://robotframework-browser.org/images/recorder/selector-picked.png)

The picked login button, with Playwright's selector and one match on the page.

After the pick the toolbar shows the selector and counts the elements it finds:

- **Playwright** writes Playwright's own selector, the one `Record Keyword` uses:
role, text, label, placeholder or test id where they identify the element, in
Browser syntax — `role=button[name*="login"i]`. This is the default.
- **CSS** writes a CSS selector from ids, classes, attributes and the element's
position — `.loginButtonStyle`. Frames are joined with `>>>`, open shadow roots
with `>>`.

Switching between them keeps the picked element; start with the other one using
`generator=css`. The selector is editable: shorten it, or drop a part that will
change, and the count below follows as you type — one match is what most keywords
need, several are shown as a warning, none as an error. Playwright highlights the
matches on the page, and follows an edit once you pause typing; the dashed square
before *Reselect* switches that highlight off and on. *Reselect* picks another
element, and *Use* returns what is in the field, whatever it matches. Minimized,
the header offers *Reselect* and *Use* too.

The same panel picks a selector in the middle of a recording: *Pick* in the
toolbar of `Record Keyword` adds it to the keyword as a comment — see
[Picking a selector](https://robotframework-browser.org/docs/recording/toolbar#picking-a-selector).

## Ending

*Use* returns the selector, and it is written to the console and the log as well.
*✕* in the header, or Escape, cancels: then the keyword fails, as it does when the
page is closed or after five minutes without a pick or a click in the toolbar —
change that with `idle_timeout`, or wait without limit with `idle_timeout=${None}`.

```robot
${heading} =    Record Selector    Page heading    generator=css    idle_timeout=1 minute
```

Like `Record Keyword`, `Record Selector` needs a visible browser, and it does not
run while a recording session is open in the same browser context.


# Good practice and limits

> How to record keywords worth keeping, what to check before you commit one, what the recorder cannot do, and what to do when it goes wrong.

Source: [https://robotframework-browser.org/docs/recording/practice](https://robotframework-browser.org/docs/recording/practice)

The recorder gives you a first draft in seconds. Whether it becomes a keyword
your team keeps depends on a few habits.

## Record small keywords

One keyword per step of your test design — `Log In`, `Search Product`,
`Add Product To Cart` — not one keyword for the whole story. Small keywords are
easy to name, easy to review and reusable in other tests. `Record Keywords` makes
this cheap: *Save*, move on, *Record keyword*.

**Start from a known state.** Let the test do the setup — open the page, log in,
load the data — and record from there. A keyword recorded from the middle of a
half-finished manual session depends on whatever you did before.

**Check at the end.** Finish a keyword with an assertion from Playwright's
toolbar, so it proves it worked — see
[Assertions](https://robotframework-browser.org/docs/recording/what-gets-recorded#assertions).

## Before you commit a recorded keyword

Every recorded keyword carries the tag `recorded`. Treat it as "not reviewed
yet", and remove the tag once you have checked:

- **Values from the page.** Everything typed is recorded as typed — passwords
included. Make secrets [arguments](https://robotframework-browser.org/docs/recording/arguments) without a
default, and pass them in as Robot Framework Secrets — see [below](https://robotframework-browser.org/docs/recording/practice#secrets).
- **Selectors that will not last.** A name with a counter, a date or a generated
id in it breaks on the next run. Shorten it, make the changing part an
argument, or ask for a test id in the application.
- **Placeholders.** An upload path starts with `<define_path_to_file>` until you
fill it in.
- **Notices.** A selector in Playwright-internal syntax, an action with no Browser
keyword — the toolbar told you while recording; the file shows the result.
- **The name.** It should say what the keyword does for the test.

Run the keyword once on its own before you rely on it.

## Secrets

Robot Framework 7.4 and newer have a `Secret` type: a value that never shows
up in the log, created from the environment or a variable file. A recorded
`Fill Text` does not accept one, so change the password line to `Fill Secret`
and declare the argument as a Secret:

```robot
*** Keywords ***
Log In As
    [Arguments]    ${username}    ${password: Secret}
    Fill Text      role=textbox[name*="username"i]    ${username}
    Fill Secret    role=textbox[name*="password"i]    ${password}
```

```robot
*** Test Cases ***
Log In
    VAR    ${password: Secret}    %{APP_PASSWORD}
    Log In As    demo    ${password}
```

## Limits

- **A visible browser.** The recorder refuses a headless browser — nobody could
use the toolbar there. A browser attached with `Connect To Browser` counts as
visible.
- **One browser context.** Only the context that was active when the recording
started is recorded.
- **Not everything is an action.** Hovering is not reported by Playwright and is
not recorded; add `Hover` by hand where a menu needs it.
- **Playwright's toolbar stays.** It sits at the top centre of the page during
the session and cannot be hidden.
- **Native modal dialogs** (`showModal()`) make the toolbar inert until they are
closed. Other modals — the usual `div` with a backdrop — do not.
- **Tabs without an id.** A tab that was open before the recording started, or
that you opened by hand, cannot be switched to by the keyword; an action there
is recorded without `Switch Page`.
- **A few pages show no toolbar.** A page whose Content-Security-Policy allows
only the Trusted Types policies it names, and a document without a body, such
as an SVG file. Pages that forbid inline styles or require Trusted Types —
YouTube, Google sign-in — work.
- **The page can see the toolbar.** Scripts on the pages of the context can read
what is recorded and send toolbar commands. Record against applications you
trust, and review the result.
- **Playwright's private recorder API.** Recording uses an interface Playwright
does not publish, so a Playwright upgrade can affect it; Browser's tests check
it with every upgrade.

## When something goes wrong

| You see | Because | Do |
| --- | --- | --- |
| `Recording needs a visible browser, but the active browser runs headless.` | The browser was opened headless, the default. | Open it with `New Browser` and `headless=False` before the page. |
| No toolbar appears | The page belongs to another browser context than the active one. | `Switch Context` to the context you want to record, then start again. |
| No toolbar on one page only | Its Content-Security-Policy allows only the Trusted Types policies it names, or it is no HTML document, such as an SVG file. | Record the steps on another page, or write them by hand. |
| Clicks are not recorded | The toolbar is picking a selector — its panel replaces the Keyword Calls. | *Use* or *Cancel* the pick; recording goes on. |
| A navigation has no `Go To` | It followed a click, fill or key press within five seconds; it belongs to that action. | Nothing — the recorded click navigates when the keyword runs. |
| The name is rejected | It exists in the file, was recorded in this session, shadows a keyword the suite can call, or is not a valid name. | Choose another name; the dialog says which rule it broke. |
| The recording ended by itself | Nothing happened for `idle_timeout`. | Raise `idle_timeout`; what was recorded is saved. |
| `Cannot record into <file>` | The folder does not exist, or the file is read-only — checked before recording starts. | Fix the path or the permission. |
| `Could not write <file>` | The file became read-only or locked during the session, or is not valid UTF-8. | Fix the file; the next action writes again. If it is still not writable at the end, the keyword fails and the recorded text is in the log. |
| A selector with `internal:` in it | The element has no role and is found by its `aria-label`; there is no public selector for that. | It works as recorded. Prefer a test id if you can add one. |


# Testing responsive pages

> Why a browser at a phone-sized viewport tests responsiveness properly, what emulation cannot tell you, and where real devices actually belong.

Source: [https://robotframework-browser.org/docs/mobile/responsive](https://robotframework-browser.org/docs/mobile/responsive)

Your page has to work on a phone. That is not a separate application, it is the
same application at a different width — and a browser at that width is a
faithful test of it.

This chapter is about testing that in automation: viewports, device descriptors,
touch, permissions and location. It starts with the part people get wrong, which
is deciding what needs a real device.

## Emulation is enough, until it is not

A responsive layout is CSS reacting to viewport width, and occasionally to
pointer type and device pixel ratio. All of those are inputs you can set. When
you set them, the browser lays the page out exactly as it would on the device —
because it is the same layout engine doing the same work.

So these are properly testable in automation, and cheaply:

- Does the navigation collapse into a menu below the breakpoint?
- Does the table become cards, or does it scroll sideways off the screen?
- Is the primary action still reachable without scrolling?
- Do tap targets keep a sane size?
- Does anything overflow horizontally? (This one is worth asserting on every
page you have.)

And these are **not** things emulation can tell you:

| Emulation cannot judge | Because |
| --- | --- |
| Whether it feels fast on a four-year-old phone | Your CI machine is not that phone. CPU throttling approximates it; it does not reproduce it. |
| Whether the on-screen keyboard covers the field you just focused | There is no on-screen keyboard. |
| Whether the thumb can actually reach the button | Ergonomics are physical. |
| Whether Safari on iOS 17.2 has a bug | WebKit is the same engine, not the same browser build. |
| Whether the page is legible outdoors | Screens and eyes are involved. |

That list is the case for real devices, and it is a real case. Note what it has
in common: **every item is a human judgement.** Which is exactly why it belongs
in manual exploratory testing on real hardware, done by people, and not in an
automated suite pretending to be a person.

> **Note:**
> 
> Our position, stated plainly: **test responsiveness in automation with
> emulation, and test the experience on real devices with real humans.** A device
> farm running the same assertions your CI already runs is an expensive way to
> learn the same thing twice.

## The viewport is the input

Browser's default viewport is **1280×720**. Every context can have its own, and
it is the main lever — `deviceScaleFactor`, `isMobile` and `hasTouch` sit
alongside it on the same keyword.

```robot
*** Test Cases ***
Navigation Collapses On A Phone
    New Context    viewport={'width': 390, 'height': 844}
    New Page    ${URL}
    Get Element States    id=menu-button    contains    visible
    Get Element States    nav.desktop        contains    hidden    attached
```

Contexts are cheap — a fresh, isolated profile, far cheaper than a new browser — so a viewport
per context is the natural unit. Nothing leaks between them: no cookies, no
storage, no permissions.

To change the size *within* a test, for instance to watch a layout cross a
breakpoint, set it on the page instead:

```robot
Set Viewport Size    1200    800
Get Element States    nav.desktop    contains    visible
Set Viewport Size    380     800
Get Element States    nav.desktop    contains    hidden
```

> **Watch out:**
> 
> `Set Viewport Size` changes the page's viewport, not the emulated device. A page that renders
> differently because of `isMobile` or touch support will not change just because
> you made the viewport narrow. For that you want a device descriptor —
> [Emulating a device](https://robotframework-browser.org/docs/mobile/devices).

## Test the breakpoints, not the phones

The temptation is to write one test per popular handset. Resist it: you end up
with fifteen tests that all exercise the same three CSS rules, and they go stale
every time a manufacturer changes a screen.

Your CSS has breakpoints. Those are the real boundaries, and there are usually
three or four of them. Test **either side of each**, and name the tests after
the layout rather than the hardware:

```robot
*** Variables ***
&{LAYOUTS}
...    phone=380
...    tablet=800
...    desktop=1280

*** Test Cases ***
Primary Action Is Reachable
    [Template]    Check Primary Action
    FOR    ${name}    ${width}    IN    &{LAYOUTS}
        ${name}    ${width}
    END

*** Keywords ***
Check Primary Action
    [Arguments]    ${name}    ${width}
    New Context    viewport={'width': ${width}, 'height': 900}
    New Page    ${URL}
    Get Element States    id=checkout    contains    visible
```

When a test fails, "the checkout button is hidden at tablet width" locates the
bug. "It failed on the Galaxy S21" does not.

## The assertion worth having everywhere

Horizontal overflow is the most common responsive defect, one of the most
annoying, and trivially detectable — an element wider than the viewport makes
the whole page scroll sideways:

```robot
*** Keywords ***
Page Should Not Scroll Sideways
    ${client} =    Get Client Size    key=width
    Get Scroll Size    ${None}    width    ==    ${client}
```

Two keywords, no JavaScript. `Get Client Size` is how much room the page has,
`Get Scroll Size` is how much it wants; when the second is larger, the page
scrolls sideways. Neither needs a selector — left out, both measure the page
itself — and the `${None}` is there only because `selector` comes first in the
signature and the assertion arguments follow it.

Letting the assertion compare, rather than `Should Not Be True`, buys two
things. The failure names the numbers:

```text
Scroll width is '1400' (int) should be '390.0' (float)
```

which is the difference between "something is too wide" and "there is a 1400px
block on this page". And an assertion retries, so a layout still settling — a
webfont, a late image — is not reported as a defect it is not.

Call it after loading each page at your narrowest layout. It costs nothing and
it catches the long unbreakable string, the fixed-width table and the image
without `max-width` — every time, before anyone has to notice it by hand.

## Where to go next

- [Emulating a device](https://robotframework-browser.org/docs/mobile/devices) — descriptors, `isMobile`,
pixel ratio, and what emulation actually changes.
- [Touch, permissions and location](https://robotframework-browser.org/docs/mobile/touch) — `Tap`, granting
camera or notifications, and faking where the user is.


# Emulating a device

> Device descriptors, what the six or seven properties they set actually change, and the one that emulation cannot give you.

Source: [https://robotframework-browser.org/docs/mobile/devices](https://robotframework-browser.org/docs/mobile/devices)

A viewport gets you the layout. A **device descriptor** gets you the rest: the
user agent the page sees, whether it thinks it has a touch screen, and how sharp
the screen is.

Playwright ships descriptors for the common handsets and tablets, plus a few
desktop profiles, and Browser
exposes them as keywords.

## Using one

```robot
*** Test Cases ***
The Product Page On A Phone
    ${device} =    Get Device    iPhone 13
    New Context    &{device}
    New Page    ${URL}
    Get Viewport Size    width    ==    ${390}
```

`Get Device` returns a dictionary, and `&{device}` expands it into `New Context`
as named arguments. That is the whole idiom — nothing to unpack by hand.

To find out what is available:

```robot
${devices} =    Get Devices
Log Dictionary    ${devices}    # needs Library Collections
```

The list is Playwright's, so it grows when Playwright updates. Names are exact
and case-sensitive: `iPhone 13`, `iPhone 13 Pro Max`, `Pixel 7`, `Galaxy S9+`,
`iPad Mini`, and the `landscape` variants such as `iPhone 13 landscape`.

Rather than log all of them to find one, [every device descriptor](https://robotframework-browser.org/docs/mobile/device-list)
lists them with their viewport, pixel ratio and engine, filterable by name.

> **Note:**
> 
> Pin the descriptor name in a variable rather than scattering it through a suite.
> Pin the name in a variable rather than scattering it through a suite — the list
> is Playwright's, and an upgrade is the one thing that can move it under you. One
> variable is a
> one-line fix.

## What a descriptor actually sets

Six or seven properties — most phone and tablet descriptors also carry
`screen`, what `window.screen` reports. On a portrait descriptor it is taller
than the viewport, which excludes browser chrome; a landscape descriptor keeps
the *portrait* screen, so `iPhone 13 landscape` is a 750×342 viewport on a
390×844 screen. It is worth knowing them individually, because each one changes
something different, and you can set any of them yourself without a descriptor.

| Property | What it changes |
| --- | --- |
| `viewport` | The layout size. This is what your CSS media queries react to. |
| `userAgent` | The string the page reads. Anything doing server-side or JavaScript device sniffing branches on this. |
| `deviceScaleFactor` | Device pixel ratio — 2 to 4.5 depending on the handset, 3 on an iPhone 13 and 2.625 on a Pixel 7, down to 1 on older hardware. Decides which image a `srcset` picks, and the resolution of your screenshots. |
| `isMobile` | Sets the meta viewport behaviour, so the page is laid out the way a phone lays it out rather than a shrunken desktop. **Not supported in Firefox.** |
| `hasTouch` | Makes touch events available. Required before `Tap` will work, and it is what `@media (pointer: coarse)` and `'ontouchstart' in window` detect. |
| `defaultBrowserType` | Which engine Playwright would launch for this device — `webkit` for Apple hardware, `chromium` for Android. See the caveat below. |

Setting them directly is perfectly reasonable when you want one property rather
than a whole handset:

```robot
# A touch device, without pretending to be any particular phone.
New Context    viewport={'width': 400, 'height': 900}    hasTouch=True    isMobile=True
```

## The caveat that matters

**A descriptor changes the engine only when nothing is open yet.** Every
descriptor carries `defaultBrowserType`, and `New Context` honours it if there
is no browser running — so `Get Device` for `iPhone 13` followed by `New Context`
does launch WebKit. Applied to an *already running* Chromium it changes nothing
but the emulation: a Chromium reporting an iPhone user agent at an iPhone
viewport. It is not Safari either way.

If iOS is the thing you care about, be explicit about the engine:

```robot
*** Test Cases ***
The Checkout On Something Close To An iPhone
    ${device} =    Get Device    iPhone 13
    New Browser    webkit    headless=True
    New Context    &{device}
    New Page    ${URL}
```

That is as close as automation gets: the same engine family Safari is built on,
at the right size, with touch enabled. It is genuinely useful — WebKit catches
CSS and JavaScript differences that Chromium never will — and it is still not
Safari on an actual iPhone. Keep that last mile for
[real humans on real devices](https://robotframework-browser.org/docs/mobile/responsive).

> **Watch out:**
> 
> Playwright's API documentation still lists `isMobile` as unsupported in Firefox,
> but the version Browser bundles applies it: Firefox honours the meta viewport
> exactly as Chromium does, and raises no error. Treat that note as stale rather
> than as a reason to skip Firefox — but check it against the Playwright you
> ship, since this is undocumented behaviour.

## Orientation

There is no rotate keyword. Landscape is a viewport whose width exceeds its
height, so either use the landscape descriptor:

```robot
${device} =    Get Device    iPhone 13 landscape
```

or set the size yourself:

```robot
Set Viewport Size    750    342
```

Read those numbers off the descriptor rather than transposing the portrait ones
— `iPhone 13` is 390×664 and its landscape descriptor is 750×342, not a swap.
And the two routes are not equivalent: the descriptor also carries `screen`, the
user agent and `isMobile`, while `Set Viewport Size` leaves those alone and
*overwrites* `window.screen` with the new size, so the screen/viewport
distinction disappears.
If your app listens for `orientationchange`, the resize is what fires it.

## A worked example

Putting the chapter together — one device, one context, a real check:

```robot [mobile.robot]
*** Settings ***
Library     Browser

*** Variables ***
${PHONE}        iPhone 13
${URL}          https://www.imbus.de/en/academy/rfcp-robot-framework-certified-professional

*** Test Cases ***
The Certification Page On A Phone
    ${device} =    Get Device    ${PHONE}
    New Browser    webkit    headless=True
    New Context    &{device}
    New Page    ${URL}

    # A real cookie banner, in the way of everything until it is dealt with.
    Tap                        text="allow all cookies"
    Wait For Elements State    button.cc-allow-all    hidden

    Get Text    h1    *=    Certified Professional

    # …and the page never scrolls sideways.
    ${client} =    Get Client Size    key=width
    Get Scroll Size    ${None}    width    ==    ${client}
```

Two details in there are worth more than the example itself.

`hidden`, not `detached`: that banner is still in the document after you accept
it, sized to nothing. Reaching for `detached` — the obvious guess — waits out
the full timeout and fails.

And it is a page you can actually run this against, which is the point. An
example that only works against an app you do not have teaches the syntax and
hides every problem the syntax exists for.

`Tap` rather than `Click` is deliberate, and it only works because the
descriptor set `hasTouch`. That is the subject of
[the next page](https://robotframework-browser.org/docs/mobile/touch).


# Touch, permissions and location

> Tap and why it needs hasTouch, granting camera or notifications without a dialog, faking where the user is, and the gestures Browser has no keyword for.

Source: [https://robotframework-browser.org/docs/mobile/touch](https://robotframework-browser.org/docs/mobile/touch)

A phone is not only a small screen. It is a touch screen that knows where it is
and can be asked for the camera. All three are context options, and all three
are testable without a device.

## Tap

```robot
Tap    id=filter-toggle
```

`Tap` dispatches a real touch event through the browser's touchscreen, rather
than a mouse click. It runs the same actionability checks as `Click` — the
element must be visible, stable, receiving events and enabled — and scrolls it
into view first.

> **Watch out:**
> 
> **Tap requires hasTouch=True on the context.** Without it, Playwright
> refuses. This is the first thing that goes wrong for everybody, and the error is
> clear once you know to look for it. A mobile device descriptor sets `hasTouch` for you — the `Desktop *` ones do not;
> a bare `viewport=` does not.

```robot
# Works.
New Context    viewport={'width': 390, 'height': 844}    hasTouch=True
Tap    text=Menu

# Fails: no touch support on this context.
New Context    viewport={'width': 390, 'height': 844}
Tap    text=Menu
```

### Tap or Click?

Use `Tap` when the touch event itself is the thing under test — a handler bound
to `touchstart`, a control that behaves differently for touch, a tap target you
want to prove is reachable.

Use `Click` for everything else, including on a mobile-sized context. `Click`
works on a touch context and is what most of your suite should say, because most
of your suite is testing the application rather than the input method.

## Gestures beyond a tap

Being straight about a gap: **there is no swipe keyword, and no pinch or
multi-touch.** Playwright's touchscreen API is a single tap.

What you can do instead, in rough order of preference:

| You want | Use |
| --- | --- |
| A carousel moved along | Its next/previous control. It has one, because it needs one for keyboard users too. |
| Scrolling | `Scroll To`, or `Mouse Wheel`. Neither needs touch. |
| Drag-style reordering | `Drag And Drop`, which uses mouse events |
| A swipe-like drag | `Drag And Drop Relative To` — mouse-based, so it fires pointer events, not touch |
| A genuine touch swipe | `Evaluate JavaScript`, dispatching TouchEvents yourself |
| Pinch to zoom | Nothing. This is a real-device test. |

If a feature is *only* reachable by swiping, that is worth raising with the team
regardless of testing: it is unreachable by keyboard too, which is an
accessibility defect rather than a test-automation inconvenience.

## Permissions

Browsers ask the user before handing over the camera, the microphone or the
location. That dialog is browser chrome, not page content, so it is not
something a test can click. Grant it up front instead:

```robot
New Context    permissions=['geolocation', 'notifications']
```

or during the test, when the point is to check the before-and-after:

```robot
Grant Permissions    geolocation
Grant Permissions    camera    microphone    origin=https://example.com
Clear Permissions
```

Available permissions — though only **Chromium accepts all of them**. WebKit
accepts `geolocation`, `notifications`, `camera`, `microphone` and
`clipboard-read`; Firefox accepts `geolocation`, `notifications` and
`local-network-access`. Anything else fails — from `New Context` or
`Grant Permissions` on Chromium and Firefox, but on WebKit not until the next
`New Page`, which makes it look like a navigation problem.

| Group | Values |
| --- | --- |
| Location | `geolocation` |
| Media | `camera`, `microphone` |
| Clipboard | `clipboard-read`, `clipboard-write` |
| Notifications and payments | `notifications`, `payment-handler` |
| Sensors | `accelerometer`, `gyroscope`, `magnetometer`, `ambient-light-sensor` |
| Other | `background-sync`, `midi`, `midi-sysex`, `local-network-access` |

`Clear Permissions` resets every grant on the context — useful for testing the
denied path, which is the one that actually breaks in production:

```robot
*** Test Cases ***
Store Finder Degrades Without Location
    New Context    viewport={'width': 390, 'height': 844}    hasTouch=True
    New Page    ${URL}
    Clear Permissions
    Tap    id=find-near-me
    Get Text    id=message    ==    Enter a postcode instead
```

> **Note:**
> 
> Permissions belong to the context, not the page, so a new context starts with
> nothing granted. That is usually what you want — it is what a first-time visitor
> gets.

## Location

With `geolocation` granted, set the coordinates:

```robot
New Context
...    permissions=['geolocation']
...    geolocation={'latitude': 60.17, 'longitude': 24.94}

# or later, to simulate movement
Set Geolocation    60.17    24.94    accuracy=50
```

`accuracy` is in metres, and it is worth exercising: an app that draws a
confidence circle, or refuses to act on a vague fix, behaves differently at 5 m
and at 5000 m.

> **Watch out:**
> 
> Setting a location without granting `geolocation` gets you a page whose location
> request is denied — which looks exactly like a broken test. If your store finder
> "cannot find you", check the permission before you check the coordinates.

## Locale, timezone and colour scheme

Context options too, and worth pairing with a device when you are testing what a
traveller sees, or what someone with dark mode enabled sees:

```robot
New Context
...    locale=de-DE
...    timezoneId=Europe/Berlin
...    colorScheme=dark
...    reducedMotion=reduce
```

`colorScheme` and `reducedMotion` drive `@media (prefers-color-scheme)` and
`@media (prefers-reduced-motion)`. Both are one line to test and are routinely
shipped broken, because the person who built the feature had the other setting.

## Putting it together

```robot [locate-me.robot]
*** Settings ***
Library     Browser

*** Variables ***
# Robot Framework ry, Kampinkuja 2, 00100 Helsinki.
${LAT}      ${60.16829}
${LON}      ${24.93051}

*** Test Cases ***
The Map Finds The Phone, In Helsinki
    ${device} =    Get Device    iPhone 13
    New Browser    webkit    headless=True
    New Context
    ...    &{device}
    ...    permissions=['geolocation']
    ...    geolocation={'latitude': ${LAT}, 'longitude': ${LON}}
    ...    locale=fi-FI
    ...    timezoneId=Europe/Helsinki
    New Page    https://www.openstreetmap.org

    Tap        role=button[name="Näytä oma sijaintini"]
    Get Url    *=    60.168
```

That runs against the real OpenStreetMap, and the coordinates it proves are the
Foundation's own front door.

The Finnish in that selector is not decoration, and it is the trap in this
chapter: `locale` changes the page, including the accessible names that
`role=…[name=…]` matches on. Set `locale=fi-FI` and "Show My Location" becomes
"Näytä oma sijaintini". A suite that sets a locale and selects by visible name
has to pick one — either select on something the translation does not touch, or
accept that the selector belongs to that locale.

One context, one device, no hardware. Everything a real phone would have told
you about *behaviour* — and none of what it would have told you about how the
thing feels in a hand, which is
[a job for a person](https://robotframework-browser.org/docs/mobile/responsive).


# Every device descriptor

> The full list of names Get Device accepts, with the viewport, pixel ratio, touch and engine each one sets — filterable and sortable.

Source: [https://robotframework-browser.org/docs/mobile/device-list](https://robotframework-browser.org/docs/mobile/device-list)

The names below are the ones `Get Device` accepts, spelled exactly as it wants
them. They are read out of the Playwright that ships with the Browser release
this site documents — the version is named above the table — so this is the same
list your own `Get Devices` returns, rather than Playwright's newest, which
would name devices you cannot use yet.

```robot
${device} =    Get Device    iPhone 13
New Context    &{device}
```

[Emulating a device](https://robotframework-browser.org/docs/mobile/devices) covers what these properties do to a
page, and the one thing a descriptor cannot give you.

| Name | Viewport | DPR | Mobile | Touch | Engine |
| --- | --- | --- | --- | --- | --- |
| `Blackberry PlayBook` | 600×1024 | 1 | yes | yes | webkit |
| `Blackberry PlayBook landscape` | 1024×600 | 1 | yes | yes | webkit |
| `BlackBerry Z30` | 360×640 | 2 | yes | yes | webkit |
| `BlackBerry Z30 landscape` | 640×360 | 2 | yes | yes | webkit |
| `Desktop Chrome` | 1280×720 | 1 | no | no | chromium |
| `Desktop Chrome HiDPI` | 1280×720 | 2 | no | no | chromium |
| `Desktop Edge` | 1280×720 | 1 | no | no | chromium |
| `Desktop Edge HiDPI` | 1280×720 | 2 | no | no | chromium |
| `Desktop Firefox` | 1280×720 | 1 | no | no | firefox |
| `Desktop Firefox HiDPI` | 1280×720 | 2 | no | no | firefox |
| `Desktop Safari` | 1280×720 | 2 | no | no | webkit |
| `Galaxy A55` | 480×1040 | 2.25 | yes | yes | chromium |
| `Galaxy A55 landscape` | 1040×480 | 2.25 | yes | yes | chromium |
| `Galaxy Note 3` | 360×640 | 3 | yes | yes | webkit |
| `Galaxy Note 3 landscape` | 640×360 | 3 | yes | yes | webkit |
| `Galaxy Note II` | 360×640 | 2 | yes | yes | webkit |
| `Galaxy Note II landscape` | 640×360 | 2 | yes | yes | webkit |
| `Galaxy S III` | 360×640 | 2 | yes | yes | webkit |
| `Galaxy S III landscape` | 640×360 | 2 | yes | yes | webkit |
| `Galaxy S24` | 360×780 | 3 | yes | yes | chromium |
| `Galaxy S24 landscape` | 780×360 | 3 | yes | yes | chromium |
| `Galaxy S5` | 360×640 | 3 | yes | yes | chromium |
| `Galaxy S5 landscape` | 640×360 | 3 | yes | yes | chromium |
| `Galaxy S8` | 360×740 | 3 | yes | yes | chromium |
| `Galaxy S8 landscape` | 740×360 | 3 | yes | yes | chromium |
| `Galaxy S9+` | 320×658 | 4.5 | yes | yes | chromium |
| `Galaxy S9+ landscape` | 658×320 | 4.5 | yes | yes | chromium |
| `Galaxy Tab S4` | 712×1138 | 2.25 | yes | yes | chromium |
| `Galaxy Tab S4 landscape` | 1138×712 | 2.25 | yes | yes | chromium |
| `Galaxy Tab S9` | 640×1024 | 2.5 | yes | yes | chromium |
| `Galaxy Tab S9 landscape` | 1024×640 | 2.5 | yes | yes | chromium |
| `Galaxy Z Flip 6` | 360×804 | 3 | yes | yes | chromium |
| `Galaxy Z Flip 6 Cover` | 360×298 | 2 | yes | yes | chromium |
| `Galaxy Z Flip 6 Cover landscape` | 322×308 | 2 | yes | yes | chromium |
| `Galaxy Z Flip 6 landscape` | 828×308 | 3 | yes | yes | chromium |
| `Galaxy Z Flip 7` | 360×764 | 3 | yes | yes | chromium |
| `Galaxy Z Flip 7 Cover` | 474×448 | 2 | yes | yes | chromium |
| `Galaxy Z Flip 7 Cover landscape` | 472×422 | 2 | yes | yes | chromium |
| `Galaxy Z Flip 7 landscape` | 788×308 | 3 | yes | yes | chromium |
| `Galaxy Z Fold 6` | 928×1004 | 2 | yes | yes | chromium |
| `Galaxy Z Fold 6 Cover` | 484×1112 | 2 | yes | yes | chromium |
| `Galaxy Z Fold 6 Cover landscape` | 1136×432 | 2 | yes | yes | chromium |
| `Galaxy Z Fold 6 landscape` | 1028×876 | 2 | yes | yes | chromium |
| `Galaxy Z Fold 7` | 984×1016 | 2 | yes | yes | chromium |
| `Galaxy Z Fold 7 Cover` | 360×764 | 3 | yes | yes | chromium |
| `Galaxy Z Fold 7 Cover landscape` | 788×308 | 3 | yes | yes | chromium |
| `Galaxy Z Fold 7 landscape` | 1040×932 | 2 | yes | yes | chromium |
| `iPad (gen 11)` | 656×944 | 2.5 | yes | yes | webkit |
| `iPad (gen 11) landscape` | 944×656 | 2.5 | yes | yes | webkit |
| `iPad (gen 5)` | 768×1024 | 2 | yes | yes | webkit |
| `iPad (gen 5) landscape` | 1024×768 | 2 | yes | yes | webkit |
| `iPad (gen 6)` | 768×1024 | 2 | yes | yes | webkit |
| `iPad (gen 6) landscape` | 1024×768 | 2 | yes | yes | webkit |
| `iPad (gen 7)` | 810×1080 | 2 | yes | yes | webkit |
| `iPad (gen 7) landscape` | 1080×810 | 2 | yes | yes | webkit |
| `iPad Mini` | 768×1024 | 2 | yes | yes | webkit |
| `iPad Mini landscape` | 1024×768 | 2 | yes | yes | webkit |
| `iPad Pro 11` | 834×1194 | 2 | yes | yes | webkit |
| `iPad Pro 11 landscape` | 1194×834 | 2 | yes | yes | webkit |
| `iPhone 11` | 414×715 | 2 | yes | yes | webkit |
| `iPhone 11 landscape` | 800×364 | 2 | yes | yes | webkit |
| `iPhone 11 Pro` | 375×635 | 3 | yes | yes | webkit |
| `iPhone 11 Pro landscape` | 724×325 | 3 | yes | yes | webkit |
| `iPhone 11 Pro Max` | 414×715 | 3 | yes | yes | webkit |
| `iPhone 11 Pro Max landscape` | 808×364 | 3 | yes | yes | webkit |
| `iPhone 12` | 390×664 | 3 | yes | yes | webkit |
| `iPhone 12 landscape` | 750×340 | 3 | yes | yes | webkit |
| `iPhone 12 Mini` | 375×629 | 3 | yes | yes | webkit |
| `iPhone 12 Mini landscape` | 712×325 | 3 | yes | yes | webkit |
| `iPhone 12 Pro` | 390×664 | 3 | yes | yes | webkit |
| `iPhone 12 Pro landscape` | 750×340 | 3 | yes | yes | webkit |
| `iPhone 12 Pro Max` | 428×746 | 3 | yes | yes | webkit |
| `iPhone 12 Pro Max landscape` | 832×378 | 3 | yes | yes | webkit |
| `iPhone 13` | 390×664 | 3 | yes | yes | webkit |
| `iPhone 13 landscape` | 750×342 | 3 | yes | yes | webkit |
| `iPhone 13 Mini` | 375×629 | 3 | yes | yes | webkit |
| `iPhone 13 Mini landscape` | 712×327 | 3 | yes | yes | webkit |
| `iPhone 13 Pro` | 390×664 | 3 | yes | yes | webkit |
| `iPhone 13 Pro landscape` | 750×342 | 3 | yes | yes | webkit |
| `iPhone 13 Pro Max` | 428×746 | 3 | yes | yes | webkit |
| `iPhone 13 Pro Max landscape` | 832×380 | 3 | yes | yes | webkit |
| `iPhone 14` | 390×664 | 3 | yes | yes | webkit |
| `iPhone 14 landscape` | 750×340 | 3 | yes | yes | webkit |
| `iPhone 14 Plus` | 428×746 | 3 | yes | yes | webkit |
| `iPhone 14 Plus landscape` | 832×378 | 3 | yes | yes | webkit |
| `iPhone 14 Pro` | 393×660 | 3 | yes | yes | webkit |
| `iPhone 14 Pro landscape` | 734×343 | 3 | yes | yes | webkit |
| `iPhone 14 Pro Max` | 430×740 | 3 | yes | yes | webkit |
| `iPhone 14 Pro Max landscape` | 814×380 | 3 | yes | yes | webkit |
| `iPhone 15` | 393×659 | 3 | yes | yes | webkit |
| `iPhone 15 landscape` | 734×343 | 3 | yes | yes | webkit |
| `iPhone 15 Plus` | 430×739 | 3 | yes | yes | webkit |
| `iPhone 15 Plus landscape` | 814×380 | 3 | yes | yes | webkit |
| `iPhone 15 Pro` | 393×659 | 3 | yes | yes | webkit |
| `iPhone 15 Pro landscape` | 734×343 | 3 | yes | yes | webkit |
| `iPhone 15 Pro Max` | 430×739 | 3 | yes | yes | webkit |
| `iPhone 15 Pro Max landscape` | 814×380 | 3 | yes | yes | webkit |
| `iPhone 16` | 393×659 | 3 | yes | yes | webkit |
| `iPhone 16 landscape` | 734×343 | 3 | yes | yes | webkit |
| `iPhone 16 Plus` | 430×739 | 3 | yes | yes | webkit |
| `iPhone 16 Plus landscape` | 814×380 | 3 | yes | yes | webkit |
| `iPhone 16 Pro` | 402×681 | 3 | yes | yes | webkit |
| `iPhone 16 Pro landscape` | 756×352 | 3 | yes | yes | webkit |
| `iPhone 16 Pro Max` | 440×763 | 3 | yes | yes | webkit |
| `iPhone 16 Pro Max landscape` | 838×390 | 3 | yes | yes | webkit |
| `iPhone 16e` | 390×651 | 3 | yes | yes | webkit |
| `iPhone 16e landscape` | 726×340 | 3 | yes | yes | webkit |
| `iPhone 17` | 402×681 | 3 | yes | yes | webkit |
| `iPhone 17 landscape` | 756×352 | 3 | yes | yes | webkit |
| `iPhone 17 Pro` | 402×681 | 3 | yes | yes | webkit |
| `iPhone 17 Pro landscape` | 756×352 | 3 | yes | yes | webkit |
| `iPhone 17 Pro Max` | 440×763 | 3 | yes | yes | webkit |
| `iPhone 17 Pro Max landscape` | 838×390 | 3 | yes | yes | webkit |
| `iPhone 17e` | 390×651 | 3 | yes | yes | webkit |
| `iPhone 17e landscape` | 726×340 | 3 | yes | yes | webkit |
| `iPhone 6` | 375×667 | 2 | yes | yes | webkit |
| `iPhone 6 landscape` | 667×375 | 2 | yes | yes | webkit |
| `iPhone 6 Plus` | 414×736 | 3 | yes | yes | webkit |
| `iPhone 6 Plus landscape` | 736×414 | 3 | yes | yes | webkit |
| `iPhone 7` | 375×667 | 2 | yes | yes | webkit |
| `iPhone 7 landscape` | 667×375 | 2 | yes | yes | webkit |
| `iPhone 7 Plus` | 414×736 | 3 | yes | yes | webkit |
| `iPhone 7 Plus landscape` | 736×414 | 3 | yes | yes | webkit |
| `iPhone 8` | 375×667 | 2 | yes | yes | webkit |
| `iPhone 8 landscape` | 667×375 | 2 | yes | yes | webkit |
| `iPhone 8 Plus` | 414×736 | 3 | yes | yes | webkit |
| `iPhone 8 Plus landscape` | 736×414 | 3 | yes | yes | webkit |
| `iPhone Air` | 420×719 | 3 | yes | yes | webkit |
| `iPhone Air landscape` | 794×370 | 3 | yes | yes | webkit |
| `iPhone SE` | 320×568 | 2 | yes | yes | webkit |
| `iPhone SE (3rd gen)` | 375×667 | 2 | yes | yes | webkit |
| `iPhone SE (3rd gen) landscape` | 667×375 | 2 | yes | yes | webkit |
| `iPhone SE landscape` | 568×320 | 2 | yes | yes | webkit |
| `iPhone X` | 375×812 | 3 | yes | yes | webkit |
| `iPhone X landscape` | 812×375 | 3 | yes | yes | webkit |
| `iPhone XR` | 414×896 | 3 | yes | yes | webkit |
| `iPhone XR landscape` | 896×414 | 3 | yes | yes | webkit |
| `Kindle Fire HDX` | 800×1280 | 2 | yes | yes | webkit |
| `Kindle Fire HDX landscape` | 1280×800 | 2 | yes | yes | webkit |
| `LG Optimus L70` | 384×640 | 1.25 | yes | yes | chromium |
| `LG Optimus L70 landscape` | 640×384 | 1.25 | yes | yes | chromium |
| `Microsoft Lumia 550` | 360×640 | 2 | yes | yes | chromium |
| `Microsoft Lumia 550 landscape` | 640×360 | 2 | yes | yes | chromium |
| `Microsoft Lumia 950` | 360×640 | 4 | yes | yes | chromium |
| `Microsoft Lumia 950 landscape` | 640×360 | 4 | yes | yes | chromium |
| `Moto G4` | 360×640 | 3 | yes | yes | chromium |
| `Moto G4 landscape` | 640×360 | 3 | yes | yes | chromium |
| `Nexus 10` | 800×1280 | 2 | yes | yes | chromium |
| `Nexus 10 landscape` | 1280×800 | 2 | yes | yes | chromium |
| `Nexus 4` | 384×640 | 2 | yes | yes | chromium |
| `Nexus 4 landscape` | 640×384 | 2 | yes | yes | chromium |
| `Nexus 5` | 360×640 | 3 | yes | yes | chromium |
| `Nexus 5 landscape` | 640×360 | 3 | yes | yes | chromium |
| `Nexus 5X` | 412×732 | 2.625 | yes | yes | chromium |
| `Nexus 5X landscape` | 732×412 | 2.625 | yes | yes | chromium |
| `Nexus 6` | 412×732 | 3.5 | yes | yes | chromium |
| `Nexus 6 landscape` | 732×412 | 3.5 | yes | yes | chromium |
| `Nexus 6P` | 412×732 | 3.5 | yes | yes | chromium |
| `Nexus 6P landscape` | 732×412 | 3.5 | yes | yes | chromium |
| `Nexus 7` | 600×960 | 2 | yes | yes | chromium |
| `Nexus 7 landscape` | 960×600 | 2 | yes | yes | chromium |
| `Nokia Lumia 520` | 320×533 | 1.5 | yes | yes | chromium |
| `Nokia Lumia 520 landscape` | 533×320 | 1.5 | yes | yes | chromium |
| `Nokia N9` | 480×854 | 1 | yes | yes | webkit |
| `Nokia N9 landscape` | 854×480 | 1 | yes | yes | webkit |
| `Pixel 10` | 360×732 | 3 | yes | yes | chromium |
| `Pixel 10 landscape` | 756×308 | 3 | yes | yes | chromium |
| `Pixel 10 Pro` | 427×876 | 3 | yes | yes | chromium |
| `Pixel 10 Pro landscape` | 900×375 | 3 | yes | yes | chromium |
| `Pixel 10 Pro XL` | 448×921 | 3 | yes | yes | chromium |
| `Pixel 10 Pro XL landscape` | 945×396 | 3 | yes | yes | chromium |
| `Pixel 2` | 411×731 | 2.625 | yes | yes | chromium |
| `Pixel 2 landscape` | 731×411 | 2.625 | yes | yes | chromium |
| `Pixel 2 XL` | 411×823 | 3.5 | yes | yes | chromium |
| `Pixel 2 XL landscape` | 823×411 | 3.5 | yes | yes | chromium |
| `Pixel 3` | 393×786 | 2.75 | yes | yes | chromium |
| `Pixel 3 landscape` | 786×393 | 2.75 | yes | yes | chromium |
| `Pixel 4` | 353×745 | 3 | yes | yes | chromium |
| `Pixel 4 landscape` | 745×353 | 3 | yes | yes | chromium |
| `Pixel 4a (5G)` | 412×765 | 2.63 | yes | yes | chromium |
| `Pixel 4a (5G) landscape` | 840×312 | 2.63 | yes | yes | chromium |
| `Pixel 5` | 393×727 | 2.75 | yes | yes | chromium |
| `Pixel 5 landscape` | 802×293 | 2.75 | yes | yes | chromium |
| `Pixel 6` | 412×839 | 2.625 | yes | yes | chromium |
| `Pixel 6 landscape` | 863×360 | 2.625 | yes | yes | chromium |
| `Pixel 6 Pro` | 412×816 | 3.5 | yes | yes | chromium |
| `Pixel 6 Pro landscape` | 840×360 | 3.5 | yes | yes | chromium |
| `Pixel 6a` | 412×839 | 2.625 | yes | yes | chromium |
| `Pixel 6a landscape` | 863×360 | 2.625 | yes | yes | chromium |
| `Pixel 7` | 412×839 | 2.625 | yes | yes | chromium |
| `Pixel 7 landscape` | 863×360 | 2.625 | yes | yes | chromium |
| `Pixel 7 Pro` | 412×816 | 3.5 | yes | yes | chromium |
| `Pixel 7 Pro landscape` | 840×360 | 3.5 | yes | yes | chromium |
| `Pixel 7a` | 412×839 | 2.625 | yes | yes | chromium |
| `Pixel 7a landscape` | 863×360 | 2.625 | yes | yes | chromium |
| `Pixel 8` | 412×839 | 2.625 | yes | yes | chromium |
| `Pixel 8 landscape` | 863×360 | 2.625 | yes | yes | chromium |
| `Pixel 8 Pro` | 448×921 | 3 | yes | yes | chromium |
| `Pixel 8 Pro landscape` | 945×396 | 3 | yes | yes | chromium |
| `Pixel 8a` | 412×839 | 2.625 | yes | yes | chromium |
| `Pixel 8a landscape` | 863×360 | 2.625 | yes | yes | chromium |
| `Pixel 9` | 360×732 | 3 | yes | yes | chromium |
| `Pixel 9 landscape` | 756×308 | 3 | yes | yes | chromium |
| `Pixel 9 Pro` | 427×876 | 3 | yes | yes | chromium |
| `Pixel 9 Pro landscape` | 900×375 | 3 | yes | yes | chromium |
| `Pixel 9 Pro XL` | 448×921 | 3 | yes | yes | chromium |
| `Pixel 9 Pro XL landscape` | 945×396 | 3 | yes | yes | chromium |

## Reading the table

**Viewport** is the page area in CSS pixels, which is what your layout and your
media queries see. **DPR** is `deviceScaleFactor` — how many device pixels go
into one CSS pixel, so a 3 means the phone's screen is three times as fine as
the numbers beside it suggest. It changes what a screenshot looks like, not what
a selector finds.

**Touch** is `hasTouch`, and it is the one to check before writing `Tap`: on a
descriptor without it, tapping fails. **Engine** is the browser Playwright would
pick if you let it — the descriptors are not tied to it, but a WebKit profile
driven through Chromium is a combination that exists nowhere.

The **landscape** entries are separate descriptors rather than a rotation of
their portrait namesake, and on the foldables they are not the same numbers
turned around. `Galaxy Z Fold 6` is 928 × 1004 upright and 1028 × 876 on its
side, because the browser's own chrome is a different height each way. Ask for
the one you mean.

The seven `Desktop` entries have `isMobile` false and no touch. They set a user
agent and a viewport and nothing else, which makes them a convenient way to pin
a desktop size without hand-writing a user agent string.

## What is not in here

`screen` — the physical screen size, as opposed to the page area — is set on
about half of the descriptors and shown under the expander when it exists. Where
it is absent, Playwright reports the viewport as the screen.

Everything else a real handset has is not part of a descriptor: no GPU, no
touch hardware, no mobile network, and no platform browser. Chromium pretending
to be Safari on an iPhone is still Chromium. That distinction, and when it
starts to matter, is [on the previous page](https://robotframework-browser.org/docs/mobile/devices).


# Python plugins

> Add or replace keywords from Python, with access to the library's own API and to the Node side.

Source: [https://robotframework-browser.org/docs/extending/python-plugins](https://robotframework-browser.org/docs/extending/python-plugins)

The Python plugin API adds keywords to Browser, or replaces existing ones,
without forking the library. It is provided by
[PythonLibCore](https://github.com/robotframework/PythonLibCore).

> **Note:**
> 
> This is the more capable of the two extension points. A
> [JavaScript module](https://robotframework-browser.org/docs/extending/javascript-extensions) runs only on the Node
> side; a Python plugin can use both, and can use
> [AssertionEngine](https://github.com/MarketSquare/AssertionEngine) directly —
> decorate the keyword with `Browser.assertion_engine.with_assertion_polling` and
> call `verify_assertion` yourself — to give your keywords the same retrying
> assertion arguments the built-in getters have.

## A Python-only plugin

Subclass `LibraryComponent` and decorate with `@keyword`:

```python
import json

from robot.api import logger
from robot.api.deco import keyword

from Browser.base.librarycomponent import LibraryComponent
from Browser.generated.playwright_pb2 import Request

class SimplePythonPlugin(LibraryComponent):

    @keyword
    def cookie_via_public_api(self) -> dict:
        """Uses Browser's own public API."""
        cookies = self.library.get_cookies()
        logger.debug(json.dumps(cookies, indent=4, default=str))
        assert len(cookies) == 1, "Too many cookies."
        return {"name": cookies[0]["name"], "value": cookies[0]["value"]}

    @keyword
    def cookie_via_grpc(self) -> dict:
        """Calls the Node side directly over gRPC."""
        with self.playwright.grpc_channel() as stub:
            response = stub.GetCookies(Request().Empty())
            cookies = json.loads(response.json)
        return {"name": cookies[0]["name"], "value": cookies[0]["value"]}
```

Load it at import:

```robot
*** Settings ***
Library    Browser    plugins=${CURDIR}/SimplePythonPlugin.py

*** Test Cases ***
Read A Cookie
    New Page    https://example.com
    Add Cookie    session    abc123    url=https://example.com
    ${cookie} =    Cookie Via Public Api
    Should Be Equal    ${cookie}[name]    session
```

Two routes are shown above deliberately. `self.library` is the supported public
API and should be your default. Dropping to gRPC gets you at anything the Node
side can do, at the cost of coupling to internals that may change.

> **Aside:**
> 
> When `self.library.new_page(...)` fails, the **failed page** stays open and
> active until your plugin keyword returns, so the failure screenshot shows the
> page that failed. Let the error propagate and there is nothing more to do. If
> you catch it and carry on, the rest of the keyword runs against the failed page
> unless you switch back yourself:
> 
> ```python
> previous = self.library.switch_page("CURRENT")  # id of the active page
> try:
>     self.library.new_page(url)
> except Exception:
>     self.library.switch_page(previous)
> ```

Several plugins can be loaded at once — `plugins=` takes one name, a
comma-separated list, or a real list. Arguments go after the class, separated by
semicolons: `plugins=pkg.Plugin;arg1;kw=val`.

Two rules that fail loudly, and one that does not:

- The class name must match the module or file name, or the import fails with
`DataError`.
- A plugin that does not inherit `LibraryComponent` fails with `PluginError`.
- A plugin keyword whose **method name** matches a built-in silently replaces
it. Plugins load last — library keywords, then JavaScript extensions, then
plugins — so last wins, with no warning. The exception is the handful of
keywords declared with an explicit `@keyword(name=...)`, such as
`Evaluate JavaScript`, `Get BoundingBox` and the storage keywords: matching
their method name creates a duplicate instead, and the suite fails with
*Keyword with same name defined multiple times*. Give your method the same
`@keyword(name=...)` to replace one of those. Every plugin keyword is tagged
`Plugin`, which is how you spot one in Libdoc.

## Selectors inside a plugin

The public keywords resolve the `Set Selector Prefix` value for you, so a
plugin that calls them needs to do nothing:

```python
@keyword
def disable_element(self, selector):
    """Disables an element."""
    self.library.evaluate_javascript(selector, "e => e.disabled = true")
```

Resolve it yourself with `self.resolve_selector(selector)` only when you bypass
the public API — a direct gRPC call, or `call_js_keyword`.

For a keyword that should also honour presenter mode — highlighting the element
and pausing so a human can follow along — use `presenter_mode`, which resolves
the selector as well:

```python
@keyword
def highlight_and_blur(self, selector):
    """Blurs the element, honouring presenter mode."""
    selector = self.presenter_mode(selector, self.strict_mode)
    self.call_js_keyword("myBlur", selector=selector)
```

`call_js_keyword` reaches a keyword from any JavaScript module registered on the
Node side — one this plugin loaded with `initialize_js_extension`, or one loaded
through the library's `jsextension=` argument — it is not a way to call arbitrary Playwright
methods, so `myBlur` has to exist in that module.

## Calling JavaScript from a Python plugin

Load a JS module in the constructor, then call into it:

```python
from pathlib import Path

from robot.api.deco import keyword

from Browser import Browser
from Browser.base.librarycomponent import LibraryComponent

class PythonPlugin(LibraryComponent):
    def __init__(self, library: Browser):
        super().__init__(library)
        self.initialize_js_extension(Path(__file__).parent.resolve() / "JSPlugin.js")

    @keyword
    def my_mouse_wheel(self, x: int, y: int):
        """Calls a custom JavaScript keyword from JSPlugin.js."""
        return self.call_js_keyword("myMouseWheel", x=x, y=y)
```

> **Watch out:**
> 
> Every argument to `call_js_keyword` must be **named** and JSON serialisable —
> passing one positionally raises `TypeError`. The Node side fills in `page`,
> `context`, `browser`, `logger`, `playwright` and `adoptContext` itself, so a
> value you pass for them is ignored. `defaultTimeout` is the library timeout in
> milliseconds unless you pass your own.

This combination is usually the one you want: the keyword signature, type
conversion and documentation are Python, and only the part that genuinely needs
the page is JavaScript.


# Just enough JavaScript

> The JavaScript you need to write extensions and Evaluate JavaScript, for people who write Python.

Source: [https://robotframework-browser.org/docs/extending/javascript-basics](https://robotframework-browser.org/docs/extending/javascript-basics)

You do not need to know JavaScript to use Browser. You need a little to extend
it. This page is the little.

## Two different JavaScripts

The most common confusion, and worth getting straight first:

| Where it runs | What exists there | Reached by |
| --- | --- | --- |
| Node.js | Playwright, `page`, the filesystem | A JS extension module |
| The browser page | `document`, `window`, the DOM | `Evaluate JavaScript`, `page.evaluate` |

Node-side code drives the browser. Page-side code runs *inside* it. `document`
does not exist in Node; Playwright does not exist in the page.

## Variables

```javascript
let count = 2      // block scoped, reassignable
const name = 'x'   // block scoped, not reassignable
var old = 1        // function scoped — avoid
```

Use `const` by default and `let` when you must reassign.

## Strings

`'single'` and `"double"` are the same. Backticks interpolate:

```javascript
const greeting = `Hello ${name}, you have ${count} items`
```

## Equality

The one that catches Python developers:

```javascript
"32" == 32     // true  — coerces types
"32" === 32    // false — compares type as well
```

Use `===`. Always.

## Functions and arrow functions

```javascript
function add(a, b) {
  return a + b
}                                  // can be called before it is defined

const sum = (a, b) => a + b        // must be defined before use
const double = a => a + a          // one expression: no braces, no return
```

Arrow functions are what you will mostly write, because callbacks are
everywhere:

```javascript
const odds = numbers.filter(n => n % 2)
```

## Objects and arrays

A JS object is close to a Python dict, with unquoted keys:

```javascript
const obj = { key: 'test', list: [1, 2, 3], nested: { subKey: 'test' } }
const asText = JSON.stringify(obj)
const back = JSON.parse(asText)
```

Arrays have the methods you want — `map`, `filter`, `forEach`, `find`. But many
DOM results are *iterable* without being arrays, so convert first:

```javascript
const inputs = Array.from(document.querySelectorAll('input'))
const values = inputs.filter(e => e.type === 'text').map(e => e.value)
```

Forgetting `Array.from` is the single most common mistake here:
`document.querySelectorAll(...)` has no `.map`.

## async and await

Almost every Playwright call is asynchronous:

```javascript
async function getTitle(page) {
  await page.goto('https://example.com')
  return await page.title()
}
```

An `async` function returns a promise. `await` waits for one.

Browser awaits whatever your keyword returns, so a promise returned *directly*
resolves fine. A promise tucked **inside** the returned value does not — it is
serialised as `{}`. If one field of your result comes back empty, a missing
`await` is usually why.

## Evaluate JavaScript

You can run page-side JavaScript from Robot Framework directly, which is often
enough without writing an extension at all.

Three things about its shape, because they are what people get wrong first:

- The **first argument is a selector**, and it cannot be omitted — pass
`${None}` when you do not want one.
- With a selector, the function receives `(element, arg)`; with `all_elements=True`
it receives `(elements, arg)` — that flag is what makes it an array. With no
selector it receives just `(arg)`.
- The return value must be JSON-serialisable. Returning nothing gives you an
empty string, and a DOM node comes back as the useless string `ref: <Node>`.

```robot
*** Test Cases ***
Collect Every Link Text
    ${texts} =    Evaluate JavaScript    a
    ...    elements => elements.map(e => e.innerText).filter(text => text)
    ...    all_elements=True
    Log Many    @{texts}
```

Compare that with doing it keyword by keyword:

```robot-repl
${elements} =    Get Elements    a
${texts} =    Create List
FOR    ${element}    IN    @{elements}
    ${text} =    Get Text    ${element}
    IF    $text    Append To List    ${texts}    ${text}    # needs Library Collections
END
```

Both are correct. The first is one round trip to the browser; the second is one
per element, plus one for `Get Elements`. On a page with a hundred links, that
difference is visible.

Returning an object works too, and arrives in Robot Framework as a dictionary:

```robot-repl
${links} =    Evaluate JavaScript    a
...    elements => {
...        const object = {}
...        elements.filter(e => e.innerText).forEach(e => object[e.innerText] = e.href)
...        return object
...    }
...    all_elements=True
```

> **Note:**
> 
> Practise in your browser's devtools console before writing an extension: both run
> in the page. Browser first tries to turn the string into a function in Node; if
> that throws — as it does for anything touching `document`, `window` or
> `location` — the raw string is passed through and evaluated in the page instead,
> so pasting a bare expression normally just works.
> 
> The exception is an expression Node *can* evaluate. `Object.keys({a: 1})`
> becomes the array `["a"]` in Node, is stringified on the way into the page, and
> fails there with `ReferenceError: a is not defined`. Wrapping what you paste in
> an arrow function, `() => document.querySelectorAll('a').length`, sidesteps the
> question entirely.


# JavaScript extensions

> Add keywords that run on the Node side with full Playwright access — and attach a debugger to them.

Source: [https://robotframework-browser.org/docs/extending/javascript-extensions](https://robotframework-browser.org/docs/extending/javascript-extensions)

A JavaScript module adds keywords that run on the Node side, with the Playwright
`page` object in hand. It is the lighter of the two extension points: no Python,
no class, just exported functions.

Browser loads the module with `require()`. CommonJS is the safe default and what
the library's own tests use, but on the Node versions Browser supports `require()`
also loads ESM, so `export`/`import` works. The one thing it cannot load is an
ESM module using top-level `await`, which fails with `ERR_REQUIRE_ASYNC_MODULE`.

## A module

```javascript
exports.__esModule = true;
exports.getLinks = getLinks;
exports.myMouseWheel = mouseWheel;

getLinks.rfdoc = `Returns every link on the page as a name-to-href mapping.

Implemented in JavaScript.`;
async function getLinks(logger, page) {
  logger('Collecting links');
  return await page.locator('a').evaluateAll(elements => {
    const object = {};
    elements.filter(e => e.innerText).forEach(e => (object[e.innerText] = e.href));
    return object;
  });
}

mouseWheel.rfdoc = 'Scrolls the page by mouse input.';
async function mouseWheel(x, y, logger, page) {
  logger(`Mouse wheel at ${x}, ${y}`);
  await page.mouse.wheel(Number(x), Number(y));
  return await page.evaluate('document.scrollingElement.scrollTop');
}
```

Three conventions carry the whole API:

- **Exported names become keywords** — the *export key*, not the function's own
name. `exports.getLinks = getLinks` gives `Get Links`; the
`exports.myMouseWheel = mouseWheel` below gives `My Mouse Wheel`.
- **Seven argument names are filled in for you**, by name — see below.
- **fn.rfdoc becomes the keyword documentation**, so your keyword shows up in
Libdoc and in editor tooltips like any other.

### The seven names Browser fills in

Name a parameter one of these and the library passes the value in. Everything
else in your signature becomes an ordinary keyword argument.

<table>
<thead>
  <tr>
    <th>
      Name
    </th>
    
    <th>
      You get
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        page
      </code>
    </td>
    
    <td>
      The active <a href="https://playwright.dev/docs/api/class-page" rel="nofollow">
        Page
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        context
      </code>
    </td>
    
    <td>
      The active <a href="https://playwright.dev/docs/api/class-browsercontext" rel="nofollow">
        BrowserContext
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        browser
      </code>
    </td>
    
    <td>
      The active <a href="https://playwright.dev/docs/api/class-browser" rel="nofollow">
        Browser
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        logger
      </code>
    </td>
    
    <td>
      A function that writes to the Robot Framework log
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        playwright
      </code>
    </td>
    
    <td>
      The <a href="https://playwright.dev/docs/api/class-playwright" rel="nofollow">
        <code>
          playwright
        </code>
        
         module
      </a>
      
       itself
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        adoptContext
      </code>
    </td>
    
    <td>
      A function that hands a context you created to Browser — see <a href="https://robotframework-browser.org/docs/extending/javascript-extensions#handing-over-a-context-you-created">
        Handing over a context you created
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        defaultTimeout
      </code>
    </td>
    
    <td>
      The library timeout in milliseconds, as <code>
        Set Browser Timeout
      </code>
      
       sets it
    </td>
  </tr>
</tbody>
</table>

**They are matched by name, not by position.** Browser reads your parameter
names and fills in the ones it recognises, so `mouseWheel(x, y, logger, page)`
and `mouseWheel(logger, x, page, y)` behave identically — and the Robot side
sees the same keyword either way, taking `x` and `y`. Put them wherever reads
best.

These names are reserved: a keyword cannot take an argument called `page` from
Robot Framework, because that name is spoken for. `self` is not usable either.

*(since Browser 20.4.0)* **Only page, context and browser need an open
browser.** A keyword that takes one of them fails with `No Browser is open but needed for this operation.` when none is open. A keyword that takes none of them
runs without one, which is what lets a module
[create the first browser itself](https://robotframework-browser.org/docs/extending/javascript-extensions#handing-over-a-context-you-created).

One further name is special without being filled in. A parameter called `args`
makes the keyword variadic — it receives Robot Framework's `*args`, so it
carries values *to* your function rather than from the library. It cannot have a
default, and anything you declare after it becomes a named-only argument on the
Robot side, so it reads best last.

Whatever you return is JSON-serialised on the way back, so it must be
serialisable — `undefined` arrives in Robot Framework as `${None}`.

`jsextension` takes a single path, a comma-separated list, or a real list of
paths. Load it at import:

```robot
*** Settings ***
Library    Browser    jsextension=${CURDIR}/module.js

*** Test Cases ***
Read The Links
    New Page    https://playwright.dev
    ${links} =    Get Links
    Log Many    &{links}
```

## Custom selector strategies

A module can also register a selector engine, which then works anywhere a
selector is accepted:

```javascript
async function registerMySelector(playwright) {
  await playwright.selectors.register('myselector', () => ({
    query(root, selector) {
      return root.querySelector(`a[data-title="${selector}"]`);
    },
    queryAll(root, selector) {
      return Array.from(root.querySelectorAll(`a[data-title="${selector}"]`));
    },
  }));
}
exports.__esModule = true;
exports.registerMySelector = registerMySelector;
```

```robot
*** Test Cases ***
Use A Custom Engine
    New Browser           chromium
    Register My Selector
    New Page              ${URL}
    Click                 myselector=Some Title
```

> **Watch out:**
> 
> **Register once per run.** `selectors.register` rejects a name that is already
> registered, and because the registration is awaited that rejection fails the
> keyword — unawaited, it takes the whole Node process down instead.

## Handing over a context you created

*(since Browser 20.7.0)* A module can create a browser context itself and hand
it to Browser with `adoptContext`. That is how a library supports a platform
that Browser does not launch, such as an Electron application, without Browser
knowing about it:

```javascript
async function launchElectronApplication(executablePath, playwright, adoptContext) {
  const app = await playwright._electron.launch({ executablePath });
  await app.firstWindow();
  return adoptContext(app.context(), { name: 'electron' });
}
exports.__esModule = true;
exports.launchElectronApplication = launchElectronApplication;
```

```robot
*** Settings ***
Library    Browser    jsextension=${CURDIR}/electron.js

*** Test Cases ***
Read The Title Of An Electron Application
    Launch Electron Application    /path/to/app
    Get Title    ==    My App
    Close Browser
```

The examples on this page are kept short. A real module closes the application
when anything after the launch fails, for example with `try`/`catch` around
`firstWindow` and `adoptContext`, because Browser cannot close a process it has
not taken over.

`adoptContext(context, options)` adds the context as a new browser and makes it
the active one, the same way Browser keeps a persistent context:

- **Its pages become Browser's pages.** The pages the context already has are
indexed and the first one becomes the active page, so `Click`, `Get Text` and
the other keywords work on it right away. Pages it opens later can be selected
with `Switch Page`.
- **activePage picks another page.** Pass a page of the context to make it the
active page instead of the first one, for example the window of an Electron
application when Playwright saw one of its views first. A page of another
context makes `adoptContext` fail without adopting anything.
- **It gets the library timeout,** as the contexts Browser creates have, so the
function does not call `setDefaultTimeout` itself.
- **options describe the browser.** All of them are optional. `name` is what
`Get Browser Catalog` reports as its type, `adopted` by default, and `headless`
says whether it runs headless, `false` by default.
- **tracing records a trace.** Pass the absolute path of a `.zip` trace file
or of a folder, which gets `trace_<context id>.zip`, and Browser starts tracing
the context and saves the trace before it closes the context, as with `tracing`
of `New Context`. A relative path would be relative to Browser's Node process,
not to the output directory. A library written in Python gets the path from
Browser, see [From a library written in Python](https://robotframework-browser.org/docs/extending/javascript-extensions#from-a-library-written-in-python).
- **contextOptions say how the context was created.** Pass the options you
created it with, in the form of Playwright's browser context options. Browser
keywords that depend on them then work on it: `Download` needs
`acceptDownloads`, which an Electron application has by default, so pass
`{ acceptDownloads: true }` for one.
- **Browser registers it like a context of New Context.** As soon as
`adoptContext` resolves, the keyword calls become groups in the trace, if it is
traced, and the log embeds the video of the active page, if it records one, in
the `size` of `recordVideo` in `contextOptions`, else of their `viewport`, else
1280×720.
- **It returns the ids** of the new browser and context, as an object with
`browserId` and `contextId`, plus `pageId` if the context has a page, and
`videoPath`, the video of the active page or `null`. Return it from your
function and the keyword returns it to Robot Framework.
- **Closing the browser closes the context.** `Close Browser` and automatic
closing treat it like any other browser.
- **onClose releases the rest.** The async option `onClose` runs once after the
context is closed, even when closing it failed. Pass it for what the context
does not own. An Electron application quits with its context and needs none; a
connection to an Android device does not close by itself:
`adoptContext(context, { onClose: () => device.close() })`.

### From a library written in Python

A library built on Browser in Python calls the module with `call_js_keyword`
and lets Browser decide where traces, videos and HAR files go, by the same rules
as for `New Context`. Type the keyword's arguments with Browser's types, as the
example does, so that Robot Framework converts `False` or a dictionary as it does
for `New Context`:

```python
from pathlib import Path

from Browser import Browser
from Browser.utils import RecordHar, RecordVideo
from robotlibcore import keyword

class ElectronLibrary(Browser):
    @keyword
    def launch_electron_application(
        self,
        executable_path: str,
        tracing: bool | Path | None = None,
        record_video: RecordVideo | None = None,
        record_har: RecordHar | None = None,
    ):
        options = self.adopted_context_options(tracing=tracing, recordVideo=record_video, recordHar=record_har)
        return self.call_js_keyword(
            "launchElectronApplication",
            executablePath=executable_path,
            **options,
        )
```

```javascript
async function launchElectronApplication(executablePath, tracing, recordVideo, recordHar, tracesDir, playwright, adoptContext) {
  const contextOptions = { acceptDownloads: true };
  if (recordVideo) contextOptions.recordVideo = recordVideo;
  if (recordHar) contextOptions.recordHar = recordHar;
  const app = await playwright._electron.launch({ executablePath, tracesDir, ...contextOptions });
  await app.firstWindow();
  return adoptContext(app.context(), { name: 'electron', tracing: tracing || undefined, contextOptions });
}
exports.__esModule = true;
exports.launchElectronApplication = launchElectronApplication;
```

- **adopted_context_options** returns an `AdoptedContextOptions`, a typed
dictionary with `tracing`, `recordVideo` and `recordHar` as `New Context`
would use them, `None` when off: `tracing=True` and
`ROBOT_FRAMEWORK_BROWSER_TRACING` give Browser's trace folder, a video goes to
Browser's video folder, and relative paths are resolved as for `New Context`.
Its arguments are converted like those of `New Context`, so an unknown key
fails. An empty `recordVideo` records with these defaults. Without a `size`,
the video has the size of the `viewport` argument, the viewport you create the
context with, or 1280×720. `tracesDir` is a new folder for Playwright's
temporary trace files, as Browser gives one to each browser it launches. Name
the function's parameters like the keys and `**options` passes them on. Give
`tracing` to `adoptContext`, `tracesDir` to the launch, and the others to
Playwright when you create the context.
- **Nothing to register afterwards.** `call_js_keyword` registers the context
while the call runs, as soon as `adoptContext` resolves, so the keyword calls
become groups in the trace and the log embeds the video, as described above.
The keyword returns what the function returned, here the ids and `videoPath`.
- **defaultTimeout** is filled in by `call_js_keyword` too, with the library
timeout, and `adoptContext` gives it to the context. Pass your own only when
your library keeps a timeout of its own; it is the one filled-in name you can
override.

> **Aside:**
> 
> Browser does not support Electron or Android itself, and `_electron` and
> `_android` are experimental in Playwright. The module, and keeping it working
> with the platform, are yours. A module that does more than launch belongs in a
> library of its own, built on Browser.

## Debugging

You can attach a Node debugger to the Playwright process — to your own extension
or to the library's internals.

### 1. Start Node with debugging enabled

Set `ROBOT_FRAMEWORK_BROWSER_NODE_DEBUG_OPTIONS`; its value is passed to the
Node process as CLI options.

| Option | Behaviour |
| --- | --- |
| `--inspect` | Debugging on, process starts immediately. Attach whenever. |
| `--inspect-brk` | Process pauses until a debugger attaches. Needed to debug startup. |

Bind it to a specific port so it does not collide with anything else:

```text
--inspect=127.0.0.1:9999
```

Set it for the debug session rather than globally. For RobotCode, in
`launch.json`:

```json
{
  "name": "RobotCode: Default",
  "type": "robotcode",
  "request": "launch",
  "purpose": "default",
  "env": {
    "ROBOT_FRAMEWORK_BROWSER_NODE_DEBUG_OPTIONS": "--inspect=127.0.0.1:9999"
  },
  "pythonConfiguration": "RobotCode: Python"
}
```

> **Watch out:**
> 
> With `--inspect-brk` you have to attach quickly: the Playwright process start
> has a timeout of about **15 seconds**. Miss it and the run fails before you are
> attached. On macOS a failed start is retried once, but the first process is
> killed and a second one started, so you still only get those 15 seconds to
> attach to any one process.

### 2. Attach

```json
{
  "name": "Attach to Node",
  "port": 9999,
  "type": "node",
  "request": "attach",
  "skipFiles": ["<node_internals>/**"]
}
```

### 3. Run

1. Set breakpoints in your extension — or in
`site-packages/Browser/wrapper/index.js` to debug the library itself.
2. Set a breakpoint in the Robot code **early**, after `Library Browser` is
loaded and before your JS runs. This buys you the time to attach.
3. Start the Robot debug session and wait for that breakpoint.
4. Switch to *Run and Debug*, choose *Attach to Node*, and start it.

Step 2 is the one people skip, and then wonder why the JS breakpoint never
fires: without it the extension has already run by the time you attach.

## Which extension point?

Three shapes, not two. A Python plugin and a JavaScript module both extend the
Browser instance Robot Framework loaded, from the inside. The third is not an
extension point at all: **your own Robot Framework library**, which either sits
alongside Browser or owns the instance itself.

| You want | Use |
| --- | --- |
| Playwright APIs Browser does not expose | JavaScript module |
| Assertion arguments like the built-in getters | Python plugin with AssertionEngine |
| To replace an existing keyword | Python plugin |
| A custom selector engine | JavaScript module |
| A platform Browser does not launch, such as Electron | JavaScript module that [hands over its context](https://robotframework-browser.org/docs/extending/javascript-extensions#handing-over-a-context-you-created), usually in a library of its own |
| Both Python and page-side logic in one keyword | Python plugin calling a JS module |
| Business logic in Python — `IF`, `TRY`, parsing — with Browser unchanged | [Your own Python library](https://robotframework-browser.org/docs/extending/python-libraries) |
| Your own keywords and your own failure handling, with Browser underneath | [Browser as a base](https://robotframework-browser.org/docs/extending/browser-as-a-base) |

## Before you write one

Somebody may have already written it.
[robotframework-browser-extensions](https://github.com/MarketSquare/robotframework-browser-extensions)
collects working community extensions — accessibility checks with axe-core,
visual comparison, network throttling, request mocking, element highlighting,
and native Playwright page methods.

Reading one is also the fastest way to see the shape of a finished extension
rather than a snippet. And when yours works, it belongs there too: it is a
monorepo that takes pull requests, so publishing is one PR rather than a
release process.


# Your own Python library

> Move business logic out of Robot Framework and keep Browser exactly as it is.

Source: [https://robotframework-browser.org/docs/extending/python-libraries](https://robotframework-browser.org/docs/extending/python-libraries)

A [plugin](https://robotframework-browser.org/docs/extending/python-plugins) adds keywords *to* Browser. This page
is about the other move: writing **your own Robot Framework library** that uses
Browser — your keywords, your module, your control over what happens in Python.

It is what you want when the logic has outgrown Robot Framework syntax. Logging,
`IF`/`ELSE`, `TRY`/`EXCEPT`, parsing a response, building test data: all of it is
ordinary Python in a file you own, and none of it changes how Browser behaves.

Robot Framework still imports Browser. Your library sits alongside it:

```robot
*** Settings ***
Library    Browser
Library    MyLibraryA.py
```

## Reach the instance, never build one

Your library needs the Browser instance Robot Framework already made. Ask
`BuiltIn` for it:

```python [MyLibraryA.py]
@property
    def browser(self) -> Browser:
        """The Browser instance that Robot Framework imported.

        Looked up on first use rather than in ``__init__``, because Robot
        Framework may not have imported Browser yet when this library is
        constructed.
        """
        if self._browser is None:
            self._browser = BuiltIn().get_library_instance("Browser")
        return self._browser
```

The lazy lookup is not a style preference. Robot Framework may not have imported
Browser yet when your library is constructed, so `get_library_instance` in
`__init__` is a race you lose depending on the order of the `*** Settings ***`
table. Looking it up on first use is always safe.

> **Watch out:**
> 
> **Do not write Browser() in your library here.** It succeeds, and it hands you
> an instance Robot Framework knows nothing about. Robot Framework drives the
> listener of the Browser *it* imported, so the automatic closing and the scope
> settings you still think you have belong to that instance and not to yours — and
> the two are not cleanly separate either, because Browser keeps state at class
> level, shared by every instance in the process.
> 
> Owning the instance on purpose is a different design, and it works. It is
> [Browser as a base](https://robotframework-browser.org/docs/extending/browser-as-a-base).

## Calling Browser from Python

Keywords are methods, named in snake_case. `Click` is `click`, `Get Text` is
`get_text`, `Wait For Elements State` is `wait_for_elements_state`.

*(since Browser 20.4.0)* Arguments are plain Python values — the same strings
you would write in a Robot Framework test, converted the same way.

```python [MyLibraryA.py]
def click_heading_with_middle_mouse_button(self):
        """Call Browser with plain Python values.

        ``"middle"`` becomes a ``MouseButton``, ``"2 seconds"`` becomes a
        ``timedelta``, and the ``None`` stays ``None`` instead of turning into
        the string ``"None"``.
        """
        self.browser.wait_for_elements_state("id=heading1", "visible", "2 seconds")
        self.browser.click("id=heading1", "middle")
        return self.browser.evaluate_javascript(None, "() => 'evaluated'")
```

Four things worth knowing about that, and no more:

- **Values convert exactly as Robot Framework converts them.** `"middle"`
becomes a `MouseButton`, `"2 seconds"` a `timedelta`, `"validate"` an
`AssertionOperator`, `"true"` becomes `True`. It is not a curated subset —
the same converters run, so every type Robot Framework can convert for a
keyword argument converts here too.
- **A Python None stays None.** It is never converted, so it never arrives
as the string `"None"`. From Python, meaning *nothing* is passing the `None`
object — which is what the `evaluate_javascript(None, …)` above depends on.
- **A string "None" is not None.** It still converts by the argument's type
hint, exactly as it would from Robot Framework.
- **Passing an already-typed value is the opt-out.** Conversion is idempotent,
so `browser.click("//button", MouseButton.middle)` keeps working unchanged.

## What stays exactly as it was

Robot Framework imported Browser, so Browser is a fully ordinary library in this
suite. Pages and contexts close automatically at the end of a test, `scope=Test`
settings revert, screenshots and videos and traces land in the run's output
directory, and `Set Browser Timeout` behaves the way its documentation says.

Nothing on this page changes any of that. That is the point of leaving the
instance where it is.

## Two things that do change

### Failure screenshots stop at the Python boundary

Browser takes its `run_on_failure` screenshot from the dynamic library API —
the code path Robot Framework enters when *it* calls a Browser keyword. A
keyword your Python code calls never goes through it, so a failing
`self.browser.click(...)` leaves no screenshot, even though `Click` written in
the suite still does.

The library's own tests pin the difference with two tests that differ only in
who makes the call:

```robot [context_a.robot]
Run On Failure Takes Screenshot
    [Documentation]    Expected to fail. The keyword is called by Robot Framework, so Browser
    ...    runs its `run_on_failure` keyword and leaves a screenshot on disk.
    Open Login Page    ${LOGIN_URL}
    Click    id=this_element_does_not_exist

Python Call Failure Takes No Screenshot
    [Documentation]    Expected to fail. The very same Browser keyword, called from Python by
    ...    MyLibraryA, never enters Browser's `run_on_failure` and leaves no screenshot.
    Open Login Page    ${LOGIN_URL}
    Click Missing Element
```

You lose the screenshot for exactly the calls you moved into Python, and nothing
warns you. For a small library, a decorator gets it back:

```python [MyLibraryA.py]
def screenshot_on_failure(keyword):
    """Take a screenshot when the wrapped keyword fails, then re-raise.

    Browser runs its own ``run_on_failure`` from the Robot Framework dynamic
    library API, which is not entered when a keyword is called from Python.
    A small library can get equivalent behaviour with a decorator like this.
    Larger libraries usually intercept in one place instead, either by being a
    dynamic library themselves or by using PythonLibCore.
    """

    @functools.wraps(keyword)
    def wrapper(self, *args, **kwargs):
        try:
            return keyword(self, *args, **kwargs)
        except Exception:
            self.browser.take_screenshot("my-library-failure-{index}")
            raise

    return wrapper
```

Applied to the keywords you care about:

```python [MyLibraryA.py]
@screenshot_on_failure
    def click_missing_element_with_screenshot(self):
        self.browser.click("id=this_element_does_not_exist")
```

It costs one decorator per keyword, and nothing enforces that you remember it.
A larger library is better served by intercepting in one place — the shapes for
that are on [Browser as a base](https://robotframework-browser.org/docs/extending/browser-as-a-base), and they
apply here unchanged.

### The log gets shallower

A Browser keyword called from Python is not a keyword in `output.xml` — Robot
Framework never saw a keyword call. Everything Browser logs still appears, but
it appears *inside* the keyword of your library that made the call.

That is the trade every one of these libraries makes: a detailed Robot Framework
log, one row per Browser keyword, becomes your own keyword's log. Log the things
that matter to a reader of the report, because the automatic detail is gone.

## Where these examples come from

Every labelled block on this page is quoted from a real file, committed in this
repository under `examples/python-extension/`, and a test fails the build if a
quote stops matching it. `MyLibraryA.py` is a complete worked library for this
page and `context_a.robot` is the suite that exercises it — including the two
failing tests above, which are expected to fail and are the demonstration.

Those files are a copy. They run as acceptance tests in the library itself, in
[`atest/test/13_Python_Extension/`](https://github.com/MarketSquare/robotframework-browser/tree/main/atest/test/13_Python_Extension),
which is where a change to them belongs.


# Browser as a base

> Own the Browser instance in your own library — what you get free, what one line restores, and what you build yourself.

Source: [https://robotframework-browser.org/docs/extending/browser-as-a-base](https://robotframework-browser.org/docs/extending/browser-as-a-base)

On the [previous page](https://robotframework-browser.org/docs/extending/python-libraries) Robot Framework imports
Browser and your library sits alongside it. This page is the other arrangement:
**Robot Framework imports only your library, and your library constructs
Browser.**

People arrive here when they are replacing the `Browser` import and a pile of
resource-file keywords with a library of their own — a domain vocabulary rather
than a browser vocabulary, with failure handling they control.

## One question decides everything

Not how advanced your library is. **Who imports Browser.**

|  | Alongside Browser | Browser as a base |
| --- | --- | --- |
| Robot Framework imports | Browser **and** your library | only your library |
| Who constructs `Browser()` | Robot Framework | your library |
| How your library reaches it | `BuiltIn().get_library_instance("Browser")` | it holds the instance it made |
| Browser's listener is registered | automatically | only if you register it |

Everything below follows from owning the instance, and it is not a list of
losses. It is three tiers.

| Tier | What is in it |
| --- | --- |
| **Free** — because Robot Framework is running | argument conversion, `outputdir`, the `validate` and `then` operators |
| **One line** — register Browser as a listener | automatic closing, scope settings, the Robot Framework context on the Node side |
| **Yours to build** | `run_on_failure`, and a little of the tracing |

> **Watch out:**
> 
> **Importing Browser anywhere in the suite puts you back in the arrangement on
> the previous page** — including from a resource file, and including when your
> library owns an instance too. Robot Framework then has its own Browser, and the
> properties described on this page stop being true of your run without anything
> failing.
> 
> The library's acceptance suite guards this rather than trusting review: it fails
> the run if any keyword owned by `Browser` appears in the child suite's
> `output.xml`.

## Free — because Robot Framework is running

These hang off *a Robot Framework run existing at all*, not off who imported
Browser. They are true in this arrangement whether or not you go on to register
the listener.

*(since Browser 20.4.0)* **Arguments convert from plain Python values.**`browser.click("id=x", "middle")`, `"2 seconds"` into a `timedelta`,
`"validate"` into an `AssertionOperator` — the same converters Robot Framework
uses, and a Python `None` stays `None`. The four rules are on
[the previous page](https://robotframework-browser.org/docs/extending/python-libraries) and they do not change
here.

**browser.outputdir is Robot Framework's ${OUTPUTDIR}.** Screenshots,
videos, traces and the Playwright log land in the run's output directory,
exactly as they do for any other suite.

**The validate and then assertion operators execute.** They need an
execution context, and there is one.

That last pair is worth stating plainly because it has been published wrongly
before: these are properties of a Robot Framework run, not of Browser having
been imported by it.

## One line — registering the listener

Everything in that middle tier is implemented in Browser's listener methods.
Robot Framework only looks for `ROBOT_LIBRARY_LISTENER` on libraries **it**
imported, so when your library owns the instance, nobody tells Browser that a
test started or ended.

Hand it over in your constructor:

```python [MyLibraryB.py]
class MyLibraryB:
    """Browser used as a base, with this library owning the instance."""

    ROBOT_LIBRARY_SCOPE = "GLOBAL"
    # Robot Framework resolves the listener API version of every listener
    # separately. Browser declares version 2, but this library would default to
    # version 3, which has different method signatures.
    ROBOT_LISTENER_API_VERSION = 2

    def __init__(self):
        self._browser = Browser(enable_playwright_debug=True)
        # Robot Framework accepts a list of listeners and calls Browser's
        # listener methods itself. Without this line Browser gets no suite and
        # test events, so automatic closing and scope settings do not work.
        self.ROBOT_LIBRARY_LISTENER = [self, self._browser]
```

**This is a supported public contract of Browser, not a workaround.** Two Robot
Framework behaviours make it work: `ROBOT_LIBRARY_LISTENER` accepts a *list*, so
your library and Browser can both be listeners; and for a library listener Robot
Framework also looks for method names with a leading underscore, which is how it
finds `Browser._start_suite`.

That leading underscore is not a private-API marker. It is the convention that
stops a listener method from also becoming a keyword — Robot Framework's library
API skips names beginning with `_`, and the library-listener lookup puts the
underscore back.

You can write `ROBOT_LIBRARY_LISTENER = self._browser` instead, and Browser
still gets its events. The list form is what lets you be a listener as well.

### What the line buys

The library's tests run the same suite against two libraries that differ only in
whether they hand Browser that registration. The difference is measured, not
argued:

| After three tests that each open a page | With the line | Without it |
| --- | --- | --- |
| Pages still open | 1 | 3 |
| A `scope=Test` browser timeout, in the next test | reverted to `10 seconds` | still `3 seconds` |
| Node-side log records carrying the Robot Framework test name | 73 | 0 |

So the line buys three things: pages and contexts opened in a test are closed at
its end, a scoped setting such as `set_browser_timeout(…, "Test")` reverts when
that test ends, and the Robot Framework suite and test names reach the Node side,
where Playwright's own log and traces carry them.

> **Watch out:**
> 
> **Without the listener, scope=Test fails silently.** It is not an error and
> there is no warning: Browser never learned that a suite started, so it quietly
> downgrades the setting to `Global` and it leaks into every later test. That is
> the second row of the table above — the timeout is still `3 seconds` in the next
> test rather than back at `10`.

### Two traps in the registration

**Declare ROBOT_LISTENER_API_VERSION = 2.** Robot Framework resolves the
listener API version *per listener*, not per registration. In
`[self, self._browser]`, Browser gets version 2 from its own class attribute
while your library defaults to version 3 — a different set of method signatures.
Copy a version-2 signature such as `_end_keyword(self, name, attrs)` into a
library that has not declared the version and you get a `TypeError` at run time
that does not say why.

**Give your library ROBOT_LIBRARY_SCOPE = "GLOBAL".** Browser is `GLOBAL` and
keeps state at class level, shared by every instance in the process. If Robot
Framework constructs your library once per suite or per test, each new
`Browser()` you make joins the state the previous one left behind.

## Yours to build

One code path is not recovered by the listener, in either arrangement:
`Browser.run_keyword`, the dynamic library API method Robot Framework calls to
execute a Browser keyword. Robot Framework calls it only on the library it
imported itself, and registering a listener is not importing a library. In this
arrangement it calls `run_keyword` on *your* library, never on Browser.

What lives in there:

- **run_on_failure** — no screenshot on a failing Browser call, listener or
not. This is the one that matters, and the recipes below are how you get it
back.
- Trace groups in the non-default `TracingGroupMode.Browser`, Browser's
rewriting of error messages, and `pause_on_failure`.

Trace groups in the **default** `TracingGroupMode.Full` are not in that list.
They are opened and closed by listener methods, and a library listener receives
events for every keyword in the run, so registering the listener gets you a
trace group per Robot Framework keyword.

> **Aside:**
> 
> No acceptance test covers that last paragraph, and that is deliberate: the only
> observable is the Playwright trace file's own format, which is internal and not
> something this project should pin a test to. It is stated from the mechanism in
> the library's source, because the opposite — "trace groups never work when you
> own the instance" — has been published before and is wrong.

### Recovering `run_on_failure` yourself

Three shapes, and no single correct one. Pick by the size of the library.

**A decorator**, best for a small library. It wraps the keywords you choose,
takes the screenshot and re-raises. It is the one shape the library's tests
cover, and it is written out in full on
[the previous page](https://robotframework-browser.org/docs/extending/python-libraries).

**Your own _end_keyword**, nearly free here — your library is already a
listener, because that is how you registered Browser. Take a screenshot when
`attrs["status"] == "FAIL"`. Two things to know:

- A library listener is told about **every** keyword in the run, not only its
own library's. Browser's own listener has to check the owning library name to
tell its keywords from everybody else's, and so will yours.
- `_end_keyword(self, name, attrs)` is a listener API version 2 signature, so
this is the same `ROBOT_LISTENER_API_VERSION` trap as above.

The granularity is different from the decorator's: a listener sees *your*
keyword fail, not the individual Browser call inside it. That is usually what
you want in a report.

**A dynamic library**, optionally through
[PythonLibCore](https://github.com/robotframework/PythonLibCore), for a large
one. Implement `run_keyword` yourself and put the failure handling in it: every
keyword is covered by construction and nothing has to be remembered per keyword.
Browser's own `Browser.run_keyword` is the worked reference — try, delegate, and
on failure call the failure keyword before re-raising.

## The log gets shallower here too

A Browser keyword called from Python is not a keyword in `output.xml` — Robot
Framework never saw a keyword call — so everything Browser logs appears inside
the keyword of your library that made the call. That is true of both
arrangements, and here it is true of every Browser call you make, because they
all come from your library.

The detailed Robot Framework log, one row per Browser keyword, becomes your own
keyword's log. Log what a reader of the report needs, because the automatic
detail is gone.

## Cleaning up

Nothing leaks. Browser registers an `atexit` hook when it starts the Node
process, so the process tree goes down when the interpreter exits whether or not
a listener is registered. A suite teardown that closes the browser is not
required for cleanliness — it is worth having only for the case where something
kills the run with a signal and `atexit` never runs.

## Where these examples come from

Every labelled block on this page is quoted from a real file, committed in this
repository under `examples/python-extension/`, and a test fails the build if a
quote stops matching it. `MyLibraryB.py` is a complete worked library for this
page and `context_b.robot` is the suite that exercises it.
`MyLibraryB_no_listener.py` is the same library without that registration, and
the difference between those two runs is the table above.

Those files are a copy. They run as acceptance tests in the library itself, in
[`atest/test/13_Python_Extension/`](https://github.com/MarketSquare/robotframework-browser/tree/main/atest/test/13_Python_Extension),
which is where a change to them belongs.


# Translating keywords

> Using a translation package to get keyword names and documentation in your language, and writing one for a language nobody has covered yet.

Source: [https://robotframework-browser.org/docs/extending/translations](https://robotframework-browser.org/docs/extending/translations)

Browser's keyword names and documentation can be translated. `Click` becomes
`Klikkaa`, and the documentation your IDE shows on hover comes back in the same
language.

This page has two halves: using a translation that already exists, which is two
lines, and writing one, which is a small Python package.

> **Note:**
> 
> Translating is a form of extending — a translation is a Python package that
> Browser discovers through a plugin API — which is why it lives in this chapter
> rather than under [Running it](https://robotframework-browser.org/docs/operations/node-process).

## Using a translation

Install the package and name the language on import:

```robot
*** Settings ***
Library    Browser    language=fi
```

That is the whole thing. From that point the suite is written in translated
keyword names, and Libdoc shows the translated documentation — as do the editors
that read Libdoc output.

## How Browser finds it

There is no registry and no configuration file. Browser searches the
[module search path](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#module-search-path)
for installed Python packages whose name starts with
`robotframework_browser_translation`, using the
[Python plugin API](https://packaging.python.org/en/latest/guides/creating-and-discovering-plugins/).
The naming convention *is* the discovery mechanism, so the prefix is not
optional.

Each package implements exactly one function, `get_language`, taking no
arguments and returning a **list of dicts** — one entry per language the package
declares:

```python
from pathlib import Path

def get_language() -> list:
    here = Path(__file__).parent.absolute()
    return [
        {
            "language": "fi",          # matched case-insensitively against language=
            "path": here / "fi.json",  # the translation data
        },
    ]
```

> **Watch out:**
> 
> It must be a list. Browser iterates the return value and ignores anything that
> is not a list — a bare dict is dropped **silently**, with no warning, and your
> suite runs in English as though the package were not installed. The same is true
> of a misnamed function or a `language=` nobody declares.

`language` is compared against the `language=` import parameter, ignoring case.
`path` may be a string or a `Path`, and a relative one is resolved against the
working directory — so build it from `Path(__file__).parent` rather than writing
it by hand.

## The translation file

JSON. The name and extension do not matter — `path` says where it is.

The keys are **method names, not keyword names**. `Click` is implemented by a
method called `click`, so the key is `click`. This trips people up, and it is
deliberate: a keyword's name is the thing being translated, so it cannot also be
the thing used to look the translation up.

```json [fi.json]
{
  "__intro__": {
    "doc": "Selainkirjasto Robot Frameworkille.",
    "sha256": "b1946ac92492d2347c6235b4d2611184"
  },
  "click": {
    "name": "Klikkaa",
    "doc": "Klikkaa elementtiä, joka vastaa valitsinta.",
    "sha256": "3a7bd3e2360a3d29eea436fcfb7e44c7"
  },
  "fill_text": {
    "name": "Täytä Teksti",
    "doc": "Kirjoittaa tekstin syöttökenttään.",
    "sha256": "9f2feb8255f4b3d1d0f2a4a3b1c7e0d9"
  }
}
```

The `sha256` is written by the generator. It is a checksum of the **English**
documentation the entry was translated from — encoded as UTF-16, which is worth
knowing only if you ever compute one yourself. Leave it alone; it is what
`--compare` uses to tell you which docs have changed since you translated them.

Each entry may carry `name`, `doc`, or both. Providing only one is valid — a
package can translate names without translating documentation — but translating
both is what makes the library actually feel native, so do both if you can.

Two special keys are not keywords:

| Key | Translates |
| --- | --- |
| `__intro__` | The library's own documentation, the introduction shown at the top of the keyword reference. |
| `__init__` | The import parameters — what you see when you look up the `Browser` import. |

> **Note:**
> 
> `__intro__` and `__init__` are not keywords, so only their `doc` is used. The
> generator leaves their `name` as it found it, and so should you — nothing reads
> it as a keyword name.

## Generating the template

Do not type the key list by hand. Browser will produce a complete, correctly
shaped file with the English text in place, ready to translate over:

```bash
rfbrowser translation /path/to/translation.json
```

The command translates nothing — it gives you every keyword, in the right format,
with nothing missing.

After a Browser upgrade, do not diff by hand. Every generated entry carries a
`sha256` of the English documentation it was translated from, and `--compare`
uses it:

```bash
rfbrowser translation --compare /path/to/translation.json
```

It writes nothing. It prints a table of what changed: keywords missing a
translation, entries whose documentation checksum no longer matches, entries
with no checksum at all, and keywords that have left the library. Nothing
validates that checksum at runtime — it exists only for this comparison.

If your suites use plugins or JavaScript extensions, include their keywords too:

```bash
rfbrowser translation --plugings myplugin.SomePlugin \
    --jsextension /path/to/jsplugin.js /path/to/translation.json
```

> **Watch out:**
> 
> The flag really is spelled `--plugings`. It is a typo that shipped and now cannot
> be corrected without breaking everyone using it.

## A worked example

[robotframework-browser-translation-fi](https://github.com/MarketSquare/robotframework-browser-translation-fi)
is a published translation package, small enough to read in one sitting, and a
good model for the packaging and the JSON.

> **Watch out:**
> 
> Do not copy its `get_language` as it stands. It returns a bare dict, which
> current Browser ignores silently — wrap the dict in a list, as above, and it
> works.

If you translate Browser into a language nobody has covered, please publish it
and tell us — [the forum](https://forum.robotframework.org/c/libraries/browser)
is the right place, and we will link it from here.


# The Node process

> Browser starts a Node process to talk to Playwright. What that costs, how to share one across parallel runs, and how to pass it Node flags.

Source: [https://robotframework-browser.org/docs/operations/node-process](https://robotframework-browser.org/docs/operations/node-process)

Browser is two halves. The Python half is the Robot Framework library you import;
the Node half drives Playwright. They talk over gRPC on a local port, and the
Python half starts the Node half for you the first time you call a Browser
keyword.

Most of the time you never think about this. It matters in two situations: when
you run many suites in parallel, and when you need to debug the Node side itself.

> **Note:**
> 
> If none of that applies to you, you can skip this page. The default — one Node
> process per Robot Framework run, started and stopped automatically — is the right
> setting for a normal suite.

## What the startup costs

Starting the Node process is the slowest single step in a run: a process
launch plus a gRPC health handshake, once per Robot Framework execution. It is
paid at the first Browser keyword rather than at import — the library starts the
process lazily — and on a single suite it disappears into the noise.

Under [Pabot](https://github.com/mkorpela/pabot) it stops being noise. Pabot runs
each suite in its own Robot Framework process, so **each one starts its own Node
process**. Twelve parallel suites means twelve Node processes, twelve startups,
and twelve copies of the Playwright runtime resident at once.

## Sharing one Node process

> **Watch out:**
> 
> This is an experimental feature. It works, but it is not covered by the same
> compatibility promise as the keywords, and the trade-offs below are real.

You can start the Node side yourself, once, and point every run at it. Start it
from the directory where the Browser package is installed:

```bash
PLAYWRIGHT_BROWSERS_PATH=0 node Browser/wrapper/index.js 127.0.0.1 12345
```

The two arguments are the host and the port, in that order — both are
required, and with only one the script exits with `No port defined`. Then tell
the runs where to find it:

```bash
ROBOT_FRAMEWORK_BROWSER_NODE_PORT=12345 pabot --processes 12 tests/
```

The same thing can be said at import time instead, which is better when only some
suites should share and the rest should stay independent:

```robot
*** Settings ***
Library    Browser    playwright_process_port=12345
```

There is a matching `playwright_process_host`, which defaults to `127.0.0.1`.
On its own it only changes the address the spawned process binds to; combined
with a port it is the address the library connects to. If both port settings are
set the **import parameter wins**: the
port from `playwright_process_port` is checked first and the variable is only a
fallback. There is no environment variable for the host — that is
`playwright_process_host` only.

The environment variable is the blunt instrument — it
applies to everything in that shell — and the import parameter is the precise one.

### What you give up

Sharing genuinely removes that startup from every run but the first. It also means:

- **One failure domain.** If the shared process dies, every run pointed at it
fails, not just the one that killed it.
- **Teardown is per connection, not global.** A finishing run closes the
browsers *it* opened. The Node side keeps separate state per client
connection, so other runs on the same process are untouched — runs only share
state if they deliberately call `Set Peer Id` with the same value.
- **You own its lifecycle.** Nothing starts it for you and nothing cleans it up.
In CI that means a start step, a wait, and a teardown that runs even when the
suite fails.
- **Debugging gets harder.** Logs from twelve suites interleave in one process.

Measure before you adopt it. If your suite takes four minutes and startup takes
two seconds, this is not your bottleneck — and a shared process is a new thing
that can break in exchange for nothing.

## Passing Node flags

> **Watch out:**
> 
> Also experimental, and a development tool rather than a production one.

`ROBOT_FRAMEWORK_BROWSER_NODE_DEBUG_OPTIONS` is passed through to the Node process
as command-line arguments. Multiple arguments are separated by commas — not
spaces, which is the mistake to expect:

```bash
ROBOT_FRAMEWORK_BROWSER_NODE_DEBUG_OPTIONS=--inspect,--trace-warnings robot tests/
```

`--inspect` opens the Node inspector, so you can attach Chrome DevTools or an IDE
debugger to the Playwright side. That is occasionally the only way to understand
a failure that looks impossible from the Robot Framework log.

Keep it out of production runs. An open inspector port is a debugging affordance,
not something you want on a CI runner.

## Where to look next

- The full list of variables that affect the Node process is on
[Environment variables](https://robotframework-browser.org/docs/operations/environment-variables).
- How the two halves fit together, and why the library is built this way, is on
[How Browser works](https://robotframework-browser.org/docs/concepts/architecture).


# Environment variables

> The variables that change how Browser behaves, which of them are safe in production, and the import parameters that should usually be preferred.

Source: [https://robotframework-browser.org/docs/operations/environment-variables](https://robotframework-browser.org/docs/operations/environment-variables)

Four environment variables change how Browser's Node process behaves. They are
documented here mainly so that nobody discovers them by accident and uses them
without knowing what they cost — **two of them must not be set in production**.

| Variable | Safe in production | What it does |
| --- | --- | --- |
| `ROBOT_FRAMEWORK_BROWSER_NODE_PORT` | Yes | Connect to an existing Node process on this port instead of starting one. The import parameter `playwright_process_port` does the same thing, more precisely. |
| `ROBOT_FRAMEWORK_BROWSER_NODE_COVERAGE` | **No** | Set to exactly the string `1` to collect code coverage for the Node process — `true` and `yes` do nothing. For developing Browser itself. Not supported on Windows. |
| `ROBOT_FRAMEWORK_BROWSER_NODE_DEBUG_OPTIONS` | **No** | Comma-separated Node command-line arguments, for example `--inspect`. A debugging tool; see [The Node process](https://robotframework-browser.org/docs/operations/node-process). |
| `ROBOT_FRAMEWORK_BROWSER_PINO_LOG_LEVEL` | Yes | Log level of the Node process's own logger, default `info`. Set it to `debug` for more in `playwright-log.txt`. The `rfbrowser` subcommands that start a browser themselves — `show-trace`, `launch-browser-server` — force it to `error` so their console output stays clean, overriding whatever you set. |

One more is read by the Python side rather than by Node:
`ROBOT_FRAMEWORK_BROWSER_TRACING`. Any truthy value — `true`, `1`, `yes` — is
equivalent to passing `tracing=True` to `New Context`, which is the way to record
traces for a whole run without editing the tests. A Robot Framework variable of
the same name works too, and is checked first.

It only reaches contexts you create yourself. `New Page` and `Open Browser`
against no open browser create their context on the Node side, which never
consults the variable — so those contexts are not traced. If you want a trace,
open the context explicitly.

## Prefer the import parameter

Where a variable and an import parameter do the same job, reach for the
parameter:

```robot
*** Settings ***
Library    Browser    playwright_process_port=12345
```

An environment variable applies to every Robot Framework process in that shell,
including the suites you did not mean to change, and it lives outside the files
you version. An import parameter is scoped to the suite that declares it, and it
is visible in the same file as the rest of that suite's configuration.

The variable is still the right tool when the setting belongs to the *machine*
rather than the suite — a CI runner that must always talk to a shared process,
for instance.

Note the precedence, because it runs the other way from what the wording
suggests: an explicit `playwright_process_port` import parameter is checked
first and **wins**, so the variable only reaches suites that do not set the
parameter themselves.

## BrowserBatteries

These variables behave identically whether the Node process comes from a Node.js
you installed yourself or from the one bundled in
[robotframework-browser-batteries](https://pypi.org/project/robotframework-browser-batteries/)
— the two [installation routes](https://robotframework-browser.org/docs/start/installation).

> **Note:**
> 
> That was not always true. In older releases these two were silently ignored when
> BrowserBatteries was installed, because its bundled Node.js was a packaged binary
> that could not accept Node arguments. If a debug flag appears to do nothing,
> check whether you are on a current release before looking anywhere else.

One difference is still real. Where the plain library defaults
`PLAYWRIGHT_BROWSERS_PATH` to `0`, BrowserBatteries defaults it to the resolved
path of its own browser directory. Both put the binaries somewhere Browser owns,
and setting the variable yourself wins in either case — but the value you see if
you print it differs.

## What is not here

Playwright reads environment variables of its own, and they mostly reach it
unchanged because Browser runs Playwright. Two exceptions, both set by Browser
before it starts Node: `DEBUG` is forced to `pw:api` when Playwright debug
logging is enabled, and `PLAYWRIGHT_BROWSERS_PATH` defaults to `0` when you have
not set it — which puts the binaries inside the library's own `node_modules`
rather than in Playwright's shared cache. Setting it yourself is honoured
everywhere.

`PLAYWRIGHT_BROWSERS_PATH` is the one you are most likely to want — it decides where `rfbrowser init` puts the browser
binaries, and it is how you share one download between users or bake browsers
into a container image. Those are documented by
[Playwright](https://playwright.dev/docs/browsers), not by us, and we deliberately
do not copy the list here: a copy would be wrong the day Playwright changes it.


# Running in Docker

> The published Browser image, the four docker run flags that matter, and why running as root breaks Chromium.

Source: [https://robotframework-browser.org/docs/operations/docker](https://robotframework-browser.org/docs/operations/docker)

Browser needs a browser, and a browser needs a long list of system libraries that
differ between distributions. On a laptop `rfbrowser init` handles it. On a CI
runner, a colleague's machine, or a distribution nobody tested, it is the part
that goes wrong.

The published image removes that problem: Python, Node, Robot Framework, Browser
and the browser binaries that ship in Playwright's base image, in versions
known to work together.

## Pull it

The same image is published to two registries. Pick whichever your infrastructure
already authenticates against — the same recipe, built from one
Dockerfile in the same release job.

```bash
docker pull marketsquare/robotframework-browser:21.0.0
docker pull ghcr.io/marketsquare/robotframework-browser/rfbrowser-stable:21.0.0
```

| Tag | Points at |
| --- | --- |
| `21.0.0` | That exact release. **Use this in CI.** |
| `21.0` | Latest patch of that minor. Picks up fixes, not features. |
| `21` | Latest release of that major. |
| `latest` | Whatever released most recently. Fine for a local experiment; a moving target in a pipeline. |

Both `linux/amd64` and `linux/arm64/v8` are built, so it runs natively on an
Apple Silicon machine as well as on an x86 runner.

## Run your suite

```bash
docker run --rm \
  -v "$(pwd)/tests:/test" \
  --ipc=host \
  --user pwuser \
  --security-opt seccomp=seccomp_profile.json \
  marketsquare/robotframework-browser:21.0.0 \
  bash -c "robot --outputdir /test/output /test"
```

Your suite is mounted in rather than copied, and the output directory is inside
that same mount — which is what gets `log.html` back onto your machine after the
container exits. A container writing its report to its own filesystem and then
being removed is the classic first mistake.

The container writes as `pwuser`, not as your user, so the mounted directory has
to be writable by that account. If it is not, the run dies trying to create
`output/`. Create it up front and open it up — this project's own CI does
`mkdir output && chmod -R 777 output` — or skip the mount and `docker cp` the
results out afterwards.

## The flags, and why each one is there

None of these are ceremony. Each fixes a specific, confusing failure.

### `--user pwuser`

**Insurance, not a requirement.** The image already ends on `USER pwuser`, so it
runs as that user by default and this flag changes nothing — keep it only if
your platform is liable to force root. What matters is not overriding it with
`--user root`: everything is installed for `pwuser`, from the virtualenv at
`/home/pwuser/.venv` to the caches and file permissions, and running as root
causes failures that look like browser crashes.

> **Watch out:**
> 
> Running as root, or as any user other than `pwuser`, is unsupported and causes
> problems that look like Browser bugs. If a derived image needs root for a build
> step, switch back with `USER pwuser` before the image is used.

### `--ipc=host`

`--ipc=host` is what this project recommends for Chromium, and it is what its
own container tests use. The reason comes from
[Playwright's Docker guide](https://playwright.dev/docs/docker) rather than from
Browser: Chromium allocates shared memory through `/dev/shm`, Docker's default is 64 MB,
which a real page will exhaust — and Chromium's response to running out is to
crash a renderer, mid-test, non-deterministically. It presents as flakiness, and
you will look for it in your test before you look for it in your container
runtime.

`--ipc=host` gives the container the host's IPC namespace and the problem
disappears. If your platform will not allow it, `--shm-size=2gb` is the
second-best answer.

### `--security-opt seccomp=seccomp_profile.json`

Chromium's sandbox needs syscalls that Docker's default seccomp profile
blocks. Playwright publishes a profile that permits exactly those:

```bash
wget https://raw.githubusercontent.com/microsoft/playwright/master/utils/docker/seccomp_profile.json
```

The alternative you will find on the internet is `--cap-add=SYS_ADMIN` or
`--no-sandbox`. Both work by turning the sandbox off. The seccomp profile keeps
it on, which for a container that loads arbitrary web pages is the difference
that matters.

> **Note:**
> 
> The profile is Playwright's, not ours, and Playwright's
> [Docker documentation](https://playwright.dev/docs/docker) is the place to check
> if it stops matching a newer Chromium.

### `--rm`

Housekeeping. Test containers are disposable, and without it a CI runner
accumulates them until the disk fills.

## Headless and headful

The image is built on Microsoft's Playwright image, which includes the
dependencies for **headful** runs as well as headless. `New Browser` is headless
by default and that is what you want in CI — note that `Open Browser` defaults
the other way.

Headful needs a display, and the image already carries Xvfb: prefix the command
with `xvfb-run`, which is exactly what this project's own headful container
tests do. A VNC sidecar is only needed if you want to *watch* the run.

## What is actually in the image

Worth knowing, because it explains the constraints in
[Building your own image](https://robotframework-browser.org/docs/operations/docker-images):

| Layer | What it provides |
| --- | --- |
| `mcr.microsoft.com/playwright:v1.64.1-noble` | Ubuntu Noble, Node.js, the browser binaries and every system library they need. Its Playwright is whatever the Dockerfile's `FROM` line pins, and that can lag the one the release was built against. |
| Python 3.14 in a virtualenv | `/home/pwuser/.venv`, already on `PATH`. `pip` inside the container installs into it. |
| Robot Framework and Browser | Browser is installed from PyPI at an exact pin. Robot Framework is not pinned — the image gets whatever was current when it was built. |
| `init --skip-browsers` | Browser's Node dependencies, **without** downloading browser binaries — the base image already has them. |

That last row is the non-obvious one. The browsers in this image come from the
Playwright base image, not from `rfbrowser init`. It is why the image is far
smaller than an install that downloads its own browser binaries on top of the
base image's — and also why the base image's Playwright can differ from the one
Browser was built against, since nothing in the image re-downloads browsers to
match.

## Checking what you got

```bash
docker run --rm marketsquare/robotframework-browser:21.0.0 rfbrowser --version
```

Prints the Browser library version, the Robot Framework version and the
Playwright version in one go. When something behaves differently in the container
than on your machine, run it in both places first — the answer is usually in the
diff.

## Next

- Adding your own dependencies, and pinning safely:
[Building your own image](https://robotframework-browser.org/docs/operations/docker-images).
- If you run suites in parallel, read
[The Node process](https://robotframework-browser.org/docs/operations/node-process) first: each Robot Framework
process starts its own Node process, inside a container as much as outside it.


# Building your own image

> Extending the published image with your dependencies, the version lock between Browser and Playwright, and using it as a CI job container.

Source: [https://robotframework-browser.org/docs/operations/docker-images](https://robotframework-browser.org/docs/operations/docker-images)

The published image runs a plain Robot Framework suite. As soon as your suite
imports another library, needs a driver, or wants a specific Python version, you
need an image of your own.

The good news is that it is a handful of lines — the published image already
runs as `pwuser`, so the `USER` line below is only insurance. The thing to be careful
about is the version lock described further down — it is the one way to build an
image that looks fine and fails at runtime.

## Add your dependencies

```dockerfile [Dockerfile]
FROM marketsquare/robotframework-browser:21.0.0

USER pwuser
COPY --chown=pwuser requirements.txt /home/pwuser/
RUN pip install --no-cache-dir -r /home/pwuser/requirements.txt
```

`pip` resolves to the virtualenv at `/home/pwuser/.venv`, which is already on
`PATH`, so there is no activation step.

Pin the base image to an exact release, not `latest`. A pipeline that rebuilds
weekly against `latest` will one day upgrade Browser under you, and the failure
will arrive on a day when nothing in your repository changed.

> **Watch out:**
> 
> If a step needs root — installing a system package, say — switch back
> afterwards:
> 
> ```dockerfile
> USER root
> RUN apt-get update && apt-get install -y --no-install-recommends your-package \
>     && rm -rf /var/lib/apt/lists/*
> USER pwuser
> ```
> 
> Keep `pwuser` as the final `USER`. The image's dependencies and caches are set
> up for that user, and running as root or any other user causes problems. See
> [Running in Docker](https://robotframework-browser.org/docs/operations/docker).

## Bake your suite in, or mount it?

Both are legitimate and they answer different questions.

|  | Mount at run time | `COPY` into the image |
| --- | --- | --- |
| How | `-v $(pwd)/tests:/test` | `COPY tests /home/pwuser/tests` |
| Edit-run cycle | Instant — no rebuild | Rebuild per change |
| What the image is | A runtime | A versioned artifact of *this* suite |
| Best for | Local development, and CI that checks the repo out anyway | Shipping a suite to somewhere that does not have your repository |

Mounting is the right default. Reach for `COPY` when the image itself has to be
the deliverable — a smoke test handed to an ops team, for instance.

## The version lock

This is the part that bites.

Browser is built against **one specific Playwright version**, and the browser
binaries in the base image are the ones that Playwright version ships. Three
things must agree:

1. the Browser library,
2. the Playwright npm package Browser installs,
3. the browser binaries baked into the image.

The published image gets this right by construction: it starts from
`mcr.microsoft.com/playwright:v1.64.1-noble`, and the Browser release it installs is
built against Playwright `1.64.1`. Those two can differ by
a patch — the
`FROM` line is bumped by hand — so if you are chasing a binary-level mismatch,
compare them rather than assuming they agree.

**Upgrading Browser inside a derived image breaks that.** This looks harmless and
is not:

```dockerfile
FROM marketsquare/robotframework-browser:21.0.0
RUN pip install --upgrade robotframework-browser   # don't
```

You now have a newer Browser expecting a newer Playwright, driving the browser
binaries of the older one. What happens next depends on how far apart they are —
which is worse than failing outright, because it can work for months and then
not.

To move to a newer Browser, **change the base image tag**. That is the entire
upgrade procedure, and it is the reason the tag exists.

If you genuinely must install a different Browser version in the same image, you
own the whole chain: reinstall the Node side and let it fetch matching binaries
(`rfbrowser clean-node && rfbrowser init`, which downloads a second, matching browser set — into the library's
`node_modules` when `PLAYWRIGHT_BROWSERS_PATH` is unset, otherwise wherever it
points, which in this base image is Playwright's own directory — while the base
image's binaries stay on disk, so you pay for both), or install browsers separately and
point `PLAYWRIGHT_BROWSERS_PATH` at them. Both give up what the image was for.

> **Note:**
> 
> Verify with `rfbrowser --version`: it prints the Browser library, Robot Framework
> and Playwright npm versions. It does **not** report the browser binaries, so it
> cannot detect a base-image mismatch on its own, and it always exits 0 — running
> it as a build step records the versions in the log rather than catching
> anything.

## As a CI job container

Most CI systems can run a job *inside* an image, which removes the `docker run`
line entirely — your steps execute in the container, and the checkout is already
there.

```yaml [.github/workflows/tests.yml]
jobs:
  robot:
    runs-on: ubuntu-latest
    container:
      image: marketsquare/robotframework-browser:21.0.0
      options: --ipc=host --user pwuser
    steps:
      - uses: actions/checkout@v7
      - run: robot --outputdir output tests/
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: robot-results
          path: output/
```

Two details are load-bearing. `--ipc=host` and `--user pwuser` still apply — a job
container gets no flags you do not give it. And `if: always()` on the upload:
without it the results are discarded on exactly the runs where you needed them.

## Building the official image yourself

The Dockerfiles live in
[`docker/`](https://github.com/MarketSquare/robotframework-browser/tree/main/docker)
in the library repository, and the same directory's README documents the local
build and the pull-request image. Reach for it if you need to reproduce the
official image with a change — a different Python version, a different base — or
if you are contributing to Browser itself.

```bash
cd docker
docker build --no-cache -t my-rfbrowser --file Dockerfile.latest_release .
```

For anything short of that, extending the published image is less work and stays
correct through upgrades.


# Browser vs Cypress

> A JavaScript end-to-end runner that lives inside the browser it tests.

Source: [https://robotframework-browser.org/why/vs-cypress](https://robotframework-browser.org/why/vs-cypress)

Cypress made end-to-end testing pleasant when it was not, and a lot of people
learned that tests can be fast and debuggable because Cypress showed them. Credit
where it is due.

The argument below is not that Cypress is bad. It is that Cypress bought its
developer experience by moving the test *into* the browser, and most of what is
awkward about it follows from that one decision.

## 1. We are built on Playwright, so there is nothing to work around

Cypress runs your test code inside the browser, in the same event loop as the
application under test. That is where the live-reloading runner comes from. It
is also where the constraints come from, and you tend to meet those later.

Browser drives the browser from outside, over Playwright. There is no
same-origin boundary to work around, no `cy.origin()` wrapper for visiting a
second domain, no special case for a login flow that redirects through an
identity provider. Multiple tabs are multiple pages. Multiple browsers in one
test are multiple browsers.

The case that decides it for a lot of applications is **two users at once**.
Chat, a shared document, a seller and a bidder, an approval queue, a support
agent and the customer they are helping — one test, two logged-in sessions,
each seeing what the other does:

```robot
*** Test Cases ***
The Buyer Sees The Seller's Price Change
    New Browser    chromium
    ${seller} =    New Context
    ${buyer} =     New Context

    Switch Context    ${seller}
    New Page    ${SHOP}/admin
    Log In As    seller@example.com
    Fill Text    id=price    99.00
    Click    text=Publish

    Switch Context    ${buyer}
    New Page    ${SHOP}/item/42
    Get Text    css=.price    ==    99.00
```

Two contexts are two isolated profiles — separate cookies, separate storage,
separate logins — in one browser, each created in a few milliseconds. Cypress has one
browser session per test and no way to run two of them side by side, so this
scenario is not something you write awkwardly there. It is something you do not
write.

|  | Browser | Cypress |
| --- | --- | --- |
| Runs | Outside the browser, over Playwright | Inside the browser, in the app's event loop |
| Engines | Chromium, Firefox and WebKit | Chromium family, Firefox, WebKit (experimental) |
| Second origin in one test | Just navigate | `cy.origin()` |
| Multiple tabs | `New Page` again | Not supported |
| Two browsers at once | `New Browser` twice | Not supported |
| Two logged-in users interacting | Two contexts, switched between | Not supported |

> **Note:**
> 
> WebKit matters more than the row suggests. It is the engine behind Safari, and
> therefore every browser on iOS.

## 2. Robot Framework tests everything, not only the web

This is the one that decides most real projects, and it has nothing to do with
browsers.

Your system is not a web page. It is a web page **and** a REST API, a database,
a message queue, an SFTP drop, a PDF, a mainframe screen, a Windows desktop
client, a mobile app, a piece of hardware on a serial port. A test that logs in
through the UI and verifies the result in the database is an ordinary
requirement, not an exotic one.

Robot Framework has libraries for all of that, and they compose in the same
test, in the same syntax, in the same report.

If a library does not exist for your particular thing, you write one, and the
bar is far lower than people expect. No class, no packaging, no publishing: a
Python file next to your tests, with a function in it, is a library. Every
function becomes a keyword.

```python [my_stuff.py]
def the_invoice_total_in_the_database(order_id):
    ...
    return total
```

```robot
*** Settings ***
Library     my_stuff.py

*** Test Cases ***
Example
    ${total} =    The Invoice Total In The Database    ${order_id}
```

That is the entire mechanism. Publish it to PyPI later if other teams want it —
or never, because most of these are three functions that only make sense in one
company.

Cypress tests web pages, which is what it is for. When your test needs to check
the database, you write a task in Node and call it through `cy.task` — at which
point you are maintaining a small integration framework of your own, and it
reports nothing to the log.

## 3. Keyword-driven, logged, parallel, and open source in the whole

Four things, all of which follow from Robot Framework being a test automation
framework rather than a web-test runner.

**Compound keywords are real abstractions.** You write `Given the user has an overdrawn account`, and it appears in the log **as a step**, with everything it
did nested underneath it, collapsible. A JavaScript helper function is a
function: it runs, and the log shows whatever the commands inside it happened to
print, flat. This is the difference between a report a business analyst can read
and a report only its author can.

**Parallelism.** [Pabot](https://github.com/mkorpela/pabot) splits a suite across
processes, on your laptop or on one CI runner, and merges the results. It is
free and it is local. Cypress parallelisation is a feature of Cypress Cloud —
a paid, hosted service. You can hand-roll it with your own CI matrix, and many
teams do, but the batteries are not included.

**Open source through and through.** Robot Framework, Browser library, Pabot and
the report at the end are all Apache 2.0, and there is no tier above them.
Cypress the runner is MIT; the dashboard, the parallelisation and the flake
analytics are the product. That is a legitimate business model. It is worth
knowing which parts of your workflow you own and which you rent.

**Made for end-to-end testing.** Robot Framework has been running acceptance
tests since 2005, when it was built at Nokia; it was open-sourced in 2008. Two
decades of people meaning *acceptance* in the contractual sense.

And end-to-end means end to end. A real one crosses systems — the web shop, the
payment provider's API, the warehouse database, the confirmation email — and
often crosses users and pages as well. Cypress describes itself as an
end-to-end testing tool, and within one browser session on one origin it is a
very good one. But an end that stops at the edge of the browser tab is not the
end of anything: the moment a scenario needs a second user, a second origin or
a system that is not a web page, the tool is not able to express it. Robot
Framework treats all of those as ordinary.

## 4. The test reads like the thing it tests

Look at both files. Not at the line count — at what you have to know to read
them.

```robotframework [test.robot]
*** Settings ***
Library     Browser

*** Test Cases ***
My First Test
    [Documentation]    Gets, types and asserts
    New Page    https://example.cypress.io
    Click    "type"
    Get Url    *=    /commands/actions
    Type Text    .action-email    fake@email.com
    Get Text     .action-email    ==    fake@email.com
```

```javascript [test.cy.js]
describe('My First Test', () => {
    it('Gets, types and asserts', () => {
      cy.visit('https://example.cypress.io')
      cy.contains('type').click()
      cy.url().should('include', '/commands/actions')
      cy.get('.action-email').type('fake@email.com')
      cy.get('.action-email').should('have.value', 'fake@email.com')
    })
  })
```

- Both wait automatically; neither needs an explicit sleep.
- Browser puts the assertion inside the keyword — Get Text reads and checks in one line.
- Cypress chains commands that are queued rather than executed where they appear, which is why `await` does not work as you expect in a Cypress test.

The Robot Framework file is readable by someone who has never used Robot
Framework. The JavaScript file is readable by someone who knows JavaScript,
knows that `cy` commands enqueue rather than execute, knows why you cannot
`await` them, and knows what `should('contain', ...)` does differently from
`should('have.text', ...)`.

That difference compounds. Tests are read far more often than they are written,
and usually by more people than wrote them.

## When Cypress is the right answer

Plainly: your team is front-end developers, the tests live beside the components
they cover, nobody outside the team reads the results, and the system under test
is a web application and nothing else. The Cypress runner is genuinely good to
develop against, and picking the tool your team already speaks is a real
argument.

> **Aside:**
> 
> **PS.** Even then, have a look at [Playwright Test](https://robotframework-browser.org/why/vs-playwright) before
> you commit. It is also JavaScript, also lives next to your components, and it
> is free of the architectural constraints described above — no `cy.origin()`, no
> one-session-per-test, three real engines. If the answer to "which JavaScript
> runner?" is being decided today, it deserves to be in the comparison.

Outside those conditions — more than one technology, more than one audience for
the report, testers who are not JavaScript developers — the constraints start to
cost you, and Robot Framework was built for the job you actually have.

> **Note:**
> 
> Facts on this page are checked against Cypress 15 and Browser `21.0.0`. If
> something here has become wrong,
> [tell us](https://github.com/MarketSquare/robotframework-browser/issues) —
> a comparison page that quietly rots is worse than none.


# Browser vs Playwright Test

> Microsoft's browser automation framework, and its TypeScript test runner.

Source: [https://robotframework-browser.org/why/vs-playwright](https://robotframework-browser.org/why/vs-playwright)

This is not really a competition, because **Browser library is built on
Playwright**. Every keyword here ends up as a Playwright call. When Playwright
gets faster, we get faster. When it gains an API, we can expose it.

So the honest comparison is not Browser against Playwright. It is Robot
Framework against **Playwright Test**, the TypeScript test runner — two
different answers to *how do you write and organise tests*, over the same
automation engine.

## What we do not have

First, because a comparison page that lists only its own strengths is marketing.

We have the Playwright **API**. We do not have Playwright **Test**. Concretely,
`expect()` and its web-first assertions do not map to Browser keywords 1:1.
Playwright's assertion library is large, specific and very well made; Browser's
getters cover the same ground for the things people actually assert, but they
are not a drop-in translation.

Nor do we have the Playwright Test runner's fixtures, projects, sharded
parallelism or HTML report. Robot Framework has its own answers to all of those
— but they are Robot Framework's answers, so porting a Playwright Test suite is
a rewrite rather than a translation.

> **Note:**
> 
> If your test looks like `await expect(locator).toHaveText('x')` and that is
> exactly how you want it to look, you are already using the right tool. This page
> is for people choosing, not for people migrating away from something that works.

## What we offer instead

Four things, all of which come from Robot Framework rather than from us.

### 1. Readability

The same test, written both ways:

```robotframework [test.robot]
*** Settings ***
Library    Browser

*** Test Cases ***
Has Title
    New Page    https://playwright.dev/
    Get Title    contains    Playwright

Get Started Link
    New Page    https://playwright.dev/
    ${element}=    Get Element By Role    LINK    name=Get started
    Click    ${element}
    ${heading}=    Get Element By Role    HEADING    name=Installation
    Get Element States    ${heading}    contains    visible

Get Started Link [Alternative]
    New Page    https://playwright.dev/
    Click    a >> "Get started"
    Get Element States    h1 >> "Installation"    contains    visible

Playwright Test
    New Page    https://playwright.dev/
    Get Title    matches   Playwright
    Get Attribute    "Get started"    href    ==    /docs/intro
    Click    "Get started"
    Get Url    matches    .*intro
```

```typescript [test.spec.ts]
import { test, expect } from '@playwright/test';

test('has title', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.getByRole('link', { name: 'Get started' }).click();
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

test('Playwright Test', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await expect(page).toHaveTitle(/Playwright/);
  const getStarted = page.getByText('Get started');
  await expect(getStarted).toHaveAttribute('href', '/docs/intro');
  await getStarted.click();
  await expect(page).toHaveURL(/.*intro/);
});
```

- Same engine underneath, same auto-waiting, same role selectors.
- The Robot Framework file has no async/await, no braces, no arrow functions and no fixture argument.

The right-hand file is good TypeScript. The point is that it *is* TypeScript: to
read it you need to know what `async` means, why every line needs `await`, what
destructuring `{ page }` does, and what a fixture is. The left-hand file needs
none of that.

### 2. Easier to learn

A tester who has never automated anything can write a useful Robot Framework
test on their first day. The syntax is a keyword, then its arguments, separated
by spaces.

Reaching the same point in Playwright Test means learning JavaScript's
asynchronous model first — not the syntax, the model. A missing `await` is a
test that passes while the application is broken, and it looks nothing like a
mistake.

### 3. Business logic, expressed as business language

Keyword-driven testing is the real feature here, and it is bigger than
readability.

You build vocabulary. `Log in as an approved supplier`, `Submit a claim over the excess`, `The claim should be routed to manual review` — each a keyword,
composed of other keywords, all the way down to `Click`. The test reads as the
business process, and **the log reads the same way**: every compound keyword is
a collapsible step in the report, not a flattened list of clicks.

That is what makes a Robot Framework report something you can hand to a domain
expert. Not the styling — the structure.

### 4. Cross-technology testing

Robot Framework is a general-purpose automation framework that happens to be
very good at web. One suite, one report, one syntax across:

| Also in the same test | With |
| --- | --- |
| REST and GraphQL APIs | RequestsLibrary, and others |
| Databases | DatabaseLibrary |
| Mobile apps | AppiumLibrary |
| Desktop applications | FlaUI, SikuliX, RoboSAPiens for SAP |
| Files, SFTP, SSH, archives | OperatingSystem, SSHLibrary, ArchiveLibrary |
| Anything else | A Python class you write in an afternoon |

Playwright Test tests web applications. You *can* call an API from a Playwright
test — the request fixture is good — but when one scenario spans a web UI, a
message queue and a mainframe, you are assembling a framework. Robot Framework
already is one.

## Our clear recommendation

We mean this, and we are not burying it in small type at the bottom:

> **Aside:**
> 
> **If you are looking for a great TypeScript web automation framework, and you do
> not need to test other technologies, and you have people who read and write
> TypeScript, and you have no requirement for business-readable test reports —
> then our clear recommendation is Playwright Test.**
> 
> It is excellent. Use it.

Those four conditions are the whole decision. Break any one of them — a tester
who is not a developer, a system that is not only a web application, an auditor
who has to read the report — and Robot Framework starts earning its keep. Meet
all four, and Playwright Test is the better fit, and we would rather you were
productive than loyal.

## Thank you

Browser library exists because Playwright exists. The auto-waiting, the role
selectors, the trace viewer, three engines under one API — we did not build any
of that. We made it available to Robot Framework.

Best regards from our side to an awesome open-source project.


# Browser vs SeleniumLibrary

> The long-standing Robot Framework web library, built on Selenium WebDriver.

Source: [https://robotframework-browser.org/why/vs-seleniumlibrary](https://robotframework-browser.org/why/vs-seleniumlibrary)

Some of us maintained SeleniumLibrary for years before starting Browser, and its
current maintainers are our friends. It is a good library, it is actively
maintained, and for a great many projects it is the right answer.

So this page is facts, not persuasion. Two libraries, two underlying
technologies, and what actually differs.

> **Note:**
> 
> Both are Robot Framework libraries, so this really is like for like. The
> differences below come mostly from the layer underneath: **WebDriver** for
> SeleniumLibrary, **Playwright** for Browser.

## The same test, both ways

```robotframework [browser.robot]
*** Settings ***
Library     Browser

*** Test Cases ***
Test Eight Components
    New Browser    chromium    headless=No
    New Page    https://www.selenium.dev/selenium/web/web-form.html
    Get Title    ==    Web form
    Type Text    [name="my-text"]    Selenium
    Click    button
    Get Text    id=message    ==    Received!
```

```robotframework [seleniumlibrary.robot]
*** Settings ***
Library     SeleniumLibrary

*** Test Cases ***
Test Eight Components
    Open Browser    https://www.selenium.dev/selenium/web/web-form.html    chrome
    Title Should Be    Web form
    Input Text    name:my-text    Selenium
    Click Button    css:button
    Wait Until Element Is Visible    id:message
    Element Text Should Be    id:message    Received!
    [Teardown]    Close Browser
```

- Selenium's own "eight components" example, written with each library.
- Browser's getters assert, so Get Text does in one line what Wait Until Element Is Visible plus Element Text Should Be does in two.
- Neither file is unreadable. This is not the interesting difference.

The code is not where the gap is. The gap is underneath.

## How the two talk to the browser

|  | Browser (Playwright) | SeleniumLibrary (WebDriver) |
| --- | --- | --- |
| Protocol | One persistent WebSocket connection to the browser | W3C WebDriver, an HTTP request per command |
| What it launches | Browser builds Playwright downloads and pins | The browser installed on the machine, through a driver |
| Extra binaries | `rfbrowser init` downloads browsers; no per-browser driver | A driver per browser, resolved by Selenium Manager since 4.6 |
| Version coupling | Browsers are pinned to the Playwright version, so they match by construction | Driver and browser must stay in step as the browser auto-updates |

The protocol difference is the origin of most of the rest. A command per HTTP
round trip means every element lookup, every check and every retry is another
request; it also means the browser can change between two of them, which is
where `StaleElementReferenceException` comes from.

## Waiting

This is the single largest practical difference.

**Browser** performs Playwright's actionability checks before every action. For a
click, all five must pass: the element is **visible**, **stable** (unmoved for
two animation frames), **receives events** (nothing is on top of it), **enabled**,
and for typing also **editable**. It retries until they do or the timeout
expires, and the failure names the check that never passed.

**SeleniumLibrary** offers an implicit wait — a global timeout applied to element
lookup, and lookup only — plus explicit `Wait Until ...` keywords you place
yourself. Selenium waits for `document.readyState` on navigation, which, as
[its own documentation notes](https://www.selenium.dev/documentation/webdriver/waits/),
"only concerns itself with loading assets defined in the HTML" — a
JavaScript-rendered page is not covered.

|  | Browser | SeleniumLibrary |
| --- | --- | --- |
| Before an action | Five actionability checks, automatically | Nothing beyond the implicit lookup wait |
| Element under an overlay | Waits for the overlay to go, then clicks | Clicks, and the overlay receives it |
| Element still animating | Waits for it to stop | Clicks mid-animation |
| DOM re-render between lookup and use | Locator re-resolves | `StaleElementReferenceException` |
| Explicit waits in a normal test | Rare | Common |

That last row is the one you feel. `Wait Until Element Is Visible` before a
click is a line SeleniumLibrary suites are full of, and Browser suites do not
have.

## Selectors

| Strategy | Browser | SeleniumLibrary |
| --- | --- | --- |
| CSS, XPath, id, name, class, tag | Yes | Yes |
| Link text | Via `text=` | `link:` and `partial link:` |
| By accessible role and name (`role=`) | Yes | No equivalent |
| Visible text as a first-class engine (`text=`) | Yes, substring or exact | Anchors only |
| Chaining several strategies | `>>` | `>>` |
| Open shadow DOM | Pierced automatically | Not a locator strategy; needs the shadow root through JavaScript |
| Crossing into an iframe | `>>>` inside the same selector | `Select Frame`, then `Unselect Frame` |
| More than one match | Strict mode by default — an error | First match wins |

Role selectors are the substantive addition. `role=button[name="Save"]` matches
what the element *is* and what it is *called* — the two things a screen-reader
user navigates by — so it survives a redesign that moves the button and rewrites
the markup around it. There is no WebDriver equivalent; you approximate it with
XPath over ARIA attributes.

Shadow DOM is the other. Selenium 4 can reach a shadow root via `getShadowRoot()`
per host, so it is possible; it is not a selector, so it does not compose with
the rest of a locator, and it does not nest without work.

## Diagnosing a failure

|  | Browser | SeleniumLibrary |
| --- | --- | --- |
| Screenshot on failure | Yes, in the Robot Framework log | Yes, in the Robot Framework log |
| Video of the run | `New Context` with `recordVideo=…` | Not built in |
| Trace | `New Context` with `tracing=True` — DOM snapshots per action, network, console, timeline | No equivalent |
| Network inspection | Built in, including request interception | Via CDP, Chromium only |

The trace is the part with no counterpart. A Playwright trace is a recording you
open afterwards and step through: for every action, the DOM as it was, with
DevTools over it, plus the network and console at that moment. It is the
difference between "the click failed" and seeing the element you meant to click
sitting behind a cookie banner.

## Browsers and platforms

Where SeleniumLibrary is genuinely ahead — and it is worth being straight about
this, because it decides real projects:

|  | Browser | SeleniumLibrary |
| --- | --- | --- |
| Engines | Chromium, Firefox, WebKit | Chrome, Edge, Firefox, Safari, and more via WebDriver |
| The actual shipped browser | Playwright's builds; real Chrome or Edge via `channel` | Always the real installed browser |
| Safari proper | No — WebKit is the same engine, not the same browser | Yes, safaridriver |
| Internet Explorer, legacy browsers | No | Yes |
| Remote execution | Playwright browser server, or `Connect To Browser` | Selenium Grid, which is mature and widely deployed |
| Mobile | Device emulation | Emulation, and real devices through the Appium ecosystem |

If you must certify against Safari itself rather than WebKit, or you have an
established Selenium Grid, or a stakeholder requires the vendor's own browser
under test, SeleniumLibrary is not the compromise — it is the correct tool.

## Performance

We are not going to publish a benchmark, because a benchmark of two tools on one
suite mostly measures the suite. The structural reasons Browser tends to be
faster are stateable without one:

- **One connection instead of many requests.** Every WebDriver command is an
HTTP round trip; Playwright multiplexes over a single WebSocket.
- **No per-element round trips for waiting.** Actionability is evaluated in the
browser rather than polled from outside.
- **Contexts instead of browsers for isolation.** `New Context` gives a clean,
isolated profile in a few milliseconds; a fresh Selenium session starts a browser.
- **One Node process for all three engines**, rather than a driver process per
browser.

Flakiness follows the same logic. Most of it comes from acting on an element
that was not ready, and the actionability checks remove that category rather
than mitigating it.

## Choosing

| Choose | When |
| --- | --- |
| SeleniumLibrary | You need Safari, IE or another WebDriver-only browser; you have a Selenium Grid; you have a large suite that works, and rewriting it buys nothing; your organisation standardises on WebDriver. |
| Browser | You are starting fresh; your app is a JavaScript-heavy SPA; you keep writing explicit waits; you need shadow DOM, iframes or role selectors; you want traces and video; suite runtime matters. |

There is no obligation to migrate. Both libraries are maintained, both are
Robot Framework libraries, and they can live in the same project — one suite on
each, sharing everything else. Starting Browser has never required abandoning
SeleniumLibrary.

> **Note:**
> 
> Checked against SeleniumLibrary 6.7 on Selenium 4 and Browser `21.0.0`. If
> anything here is wrong or has aged badly,
> [tell us](https://github.com/MarketSquare/robotframework-browser/issues) —
> we would rather fix it than let an unfair comparison stand.