Browsers
Choose a browser, configure its target and check which features its driver supports.
Start with your installed Chrome for web tests, then add other browsers to check their behaviour. This page covers the setup and feature support you need before choosing a target.
Requirements
Browser tests need Node.js 24.12 or later on macOS or Linux. Retest downloads a browser only when you ask with retest install.
Choose a browser Link to Choose a browser
| Browser | Configuration | Support in this release |
|---|---|---|
| Google Chrome | chrome() | Stable tested on macOS and in Linux containers. Other channels are unverified. |
| Chromium and Chrome for Testing | chromium({ executablePath }) | Checked on macOS; Debian's Chromium checked in Linux containers. |
| Microsoft Edge | edge() | Found in its usual macOS and Linux locations and configured for the Chrome driver. No Edge run was checked. |
| Firefox | { browser: 'firefox' } | Firefox 133.0.3 on macOS on Apple silicon. |
| WebKit | { browser: 'webkit' } | Build 2359 checked on macOS on Apple silicon. |
Retest finds Chrome and Edge in their usual installation folders. Chromium needs an executable path, either in the config or in RETEST_CHROMIUM; on macOS, use the binary inside the app bundle.
import { chrome, defineConfig } from '@rehearsal-labs/retest'export default defineConfig({ apps: { web: chrome({ baseUrl: 'http://127.0.0.1:4173', viewport: { width: 1280, height: 720 }, }), },})This config opens the task app in Chrome at a fixed viewport size. Each test gets a new context and page, so cookies and browser storage are separate between tests.
npx retest doctornpx retest runInstall a pinned build Link to Install a pinned build
Install a pinned build to keep the browser version fixed between machines. The installer verifies the archive against its size and SHA-256 before unpacking it.
npx retest install --listnpx retest install chromiumnpx retest install --list --verifyThe Chromium pin is Chrome for Testing 153.0.8010.12 on macOS arm64 and Linux x64. The Linux archive was inspected, but its installation and execution on Linux were not checked. Give the path printed by the installer to chromium({ executablePath }), or set RETEST_CHROMIUM to it. An installed build alone does not select it for that target.
Configure Firefox or WebKit Link to Configure Firefox or WebKit
Keep the import and default export from the first config, then replace its defineConfig call with the engine you choose below.
npx retest install firefoxdefineConfig({ apps: { web: { browser: 'firefox', baseUrl: 'http://127.0.0.1:4173', viewport: { width: 1280, height: 720 }, }, },})Firefox finds an intact pinned cache build automatically. Without one, the system app must match Firefox 133.0.3 build 20241209150345. An explicit executablePath selects another build, whose version is recorded but is not verified by this release.
Firefox was tested through Launch Services. If the app running Retest cannot read Firefox's application data, set RETEST_FIREFOX_ROUTE=launch-services.
npx retest install webkitdefineConfig({ apps: { web: { browser: 'webkit', baseUrl: 'http://127.0.0.1:4173', viewport: { width: 1280, height: 720 }, }, },})Set RETEST_WEBKIT_BUILD to the unpacked build folder printed by the installer, or add it as executablePath. Retest checks build 2359's protocol and refuses a different build. It uses its own driver; Playwright code does not run.
Check feature support Link to Check feature support
The drivers share the test API, but some features need engine-specific support. The Chrome column records checks on macOS. The guides explain each feature's limits; an unsupported operation fails by name instead of silently changing what the test does.
| Feature | Chrome on macOS | Firefox | WebKit |
|---|---|---|---|
| Viewport size | Yes | Yes | Yes |
| Phone emulation, touch and proxy | Yes | Unsupported | Unsupported |
| Locators inside frames | Yes | Unsupported | Unsupported |
| Uploads and downloads | Yes | Unsupported | Unsupported |
| Dialogs and popups | Yes | Unsupported | Unsupported |
| Drag and drop and Mocking requests | Yes | Unsupported | Unsupported |
| Screenshot comparisons | Page and element | Page only | Page only |
| Layout matchers | Yes | Unsupported | Unsupported |
| Console and network diagnostics | Both | Network only | Both; workers excluded |
On Firefox and WebKit, text, test id, CSS and placeholder locators look through open shadow roots. Role and label lookups refuse a search where a shadow root could hold a match.
Firefox refuses a selection of several options before looking for the element, even if those options are already selected. It also refuses a single-option choice that needs keyboard input in a multiple select; one option already selected alone succeeds without input. WebKit accepts only certain contiguous selections.
WebKit is not Safari, and browser emulation is not a real phone. Safari and real devices are not supported. Headed browser mode exists, but has not been exercised in the recorded checks.