# Browser support

> See which browsers Retest drives, what each one supports, and how to install a pinned build.

Source: https://rehearsal.dev/retest/platforms/browsers

Retest drives each browser through a client of its own. No WebDriver server and no Playwright code runs.

## Browsers

| Browser | In the config | Runs on |
| --- | --- | --- |
| Google Chrome | `chrome({ channel })` | macOS and Linux |
| Microsoft Edge | `edge({ channel })` | macOS and Linux |
| Chromium | `chromium({ executablePath })` | macOS and Linux |
| Firefox 133 | `{ browser: 'firefox' }` | macOS on Apple silicon |
| WebKit, Playwright's build 2359 | `{ browser: 'webkit' }` | macOS |

- Retest finds Chrome and Edge where they install. A browser that is not there fails setup and lists the paths it tried.
- `chromium()` runs the build at `executablePath`, or at the path in `RETEST_CHROMIUM`.
- Retest's own checks ran on Chrome stable, Chrome for Testing and Chromium. Edge and Chrome's beta, dev and canary channels have not been run yet.
- On Linux, Retest has run inside Docker, with the Chromium family. [CI and containers](https://rehearsal.dev/retest/scaling-up/ci-and-containers.md) has the setup.

## What each supports

| Feature | Chromium family | Firefox | WebKit |
| --- | --- | --- | --- |
| A viewport size | Yes | Yes | Yes |
| Phone emulation and touch | Yes | No | No |
| A proxy | Yes | No | No |
| Console and network records | Yes | Requests only | Yes |
| AI checks on screenshots | Yes | Not run yet | Not run yet |

A setting a browser does not take fails by name before the test starts, such as a touch screen on Firefox.

## Firefox

- Retest runs Firefox 133 over WebDriver BiDi. Every test opens in a user context of its own, with its own cookies and storage.
- `fill` types key by key. Text with a character WebDriver keeps for named keys is refused before any key is sent.
- `select` on a `<select multiple>` that needs keys is refused. Run such a test on Chrome or WebKit.
- One wheel event moves Firefox at most one page. To reach the end of a long box, scroll several times.
- A refused connection reads `connectionFailure`, not Chrome's `net::ERR_` names.

## WebKit

- Retest runs Playwright's WebKit build 2359 over its inspector pipe. It checks the build's protocol and refuses any other build.
- `executablePath` names the build's folder. Without it, Retest reads `RETEST_WEBKIT_BUILD` and looks nowhere else.
- `getByRole` with a name is refused for cells, headers and tooltips named by their text. Use `getByText()`, `getByTestId()` or `nth()`.
- A failed navigation is told in WebKit's words, such as "Could not connect to the server."

> [!NOTE]
> WebKit here is the engine, not Safari. No Safari, real phones or real tablets are claimed, and an emulated phone is a desktop browser pretending.

## Install a pinned build

Retest pins the builds it was tested with. `retest install` puts one in Retest's cache, and only the ones you name.

```sh
# what is pinned for this machine and what the cache holds
npx retest install --list
npx retest install chromium
npx retest install firefox webkit
# read every installed file again and compare it with the pin
npx retest install --list --verify
```

| Engine | Pinned build |
| --- | --- |
| `chromium` | Chrome for Testing 153.0.8010.12, for macOS on Apple silicon and Linux x64 |
| `firefox` | Firefox 133.0.3, for macOS on Apple silicon |
| `webkit` | Playwright's WebKit build 2359, for macOS on Apple silicon |
| `electron` | Electron 44.5.1, for macOS on Apple silicon |
| `webdriveragent`, `mac2` | The executors for iOS simulator and macOS apps, built on this Mac |
| `media` | The media process for recordings, built from the source in the package |

- Each download is checked by its size and SHA-256 before anything is unpacked. A download that does not match is deleted.
- The cache is `~/Library/Caches/retest` on macOS, and `$XDG_CACHE_HOME/retest` or `~/.cache/retest` on Linux.
- `retest install` prints the installed browser's path. Give it to `chromium({ executablePath })` or `RETEST_CHROMIUM`. A Firefox target finds its installed build by itself.
- `retest run`, `retest doctor` and `retest install --list` never download anything.
- `RETEST_DOWNLOAD_MIRROR` fetches from a mirror instead, and the checksums still apply.