browser
- Type:
- Default:
Browser Mode configuration. When enabled, tests run in a real browser instead of the Node.js environment.
Options
screenshotFailures
Capture a PNG screenshot for each failed browser test. Defaults to the headless setting. Screenshots are saved under .rstest/screenshots/ in the project root, with the test file and test name in the filename. Set this to false to disable capture.
- Type:
boolean - Default:
browser.headless - CLI:
--browser.screenshotFailures
enabled
- Type:
boolean - Default:
false - CLI:
--browser,--browser.enabled
Enable Browser Mode.
Enabling Browser Mode requires installing the @rstest/browser package and Playwright browsers.
provider
- Type:
'playwright' - Default:
'playwright'
Browser driver provider. Currently only Playwright is supported.
browser (deprecated)
browser.browser is deprecated and will be removed in 1.0. Use instances instead, e.g. instances: [{ browserName: 'firefox' }]. Rstest prints a deprecation warning once per run when this field is set. --browser.name is the deprecated CLI form.
- Type:
'chromium' | 'firefox' | 'webkit' - Default:
'chromium' - CLI:
--browser.name <name>(deprecated)
The single browser type to use for testing. Setting this field is normalized to instances: [{ browserName: browser }].
Setting both browser and instances on a browser project is a config error.
chromium- Google Chrome, Microsoft Edgefirefox- Mozilla Firefoxwebkit- Safari
You need to install the corresponding browser before use:
instances
- Type:
BrowserInstanceConfig[] - Default:
[{ browserName: 'chromium' }] - CLI:
--browser.instances <names>(comma-separated and/or repeatable; filters the configured instances)
Browser instances this project runs on, one per browser. Every instance of a project shares one build and one dev server — multi-browser runs do not multiply build time.
Each item is a BrowserInstanceConfig object: browserName is required, and every other field overrides the project-level value for that browser. A bare browser name such as instances: ['chromium'] is a config error; write { browserName: 'chromium' }:
BrowserInstanceConfig accepts only runtime-effective overrides; build-scoped options (enabled, provider, port, strictPort) stay on the project-level browser config:
Merge rules per instance: an instance field wins, then the project-level browser.* field, then the built-in default. providerOptions merges per top-level key (launch, context) instead of whole-field: an instance launch replaces the project launch key entirely (Playwright options may contain functions and class instances, so sibling keys under it are not merged), while keys the instance does not set keep the project value — in the example above the chromium instance launches with channel: 'chrome' alone, and its context keeps the project-level locale: 'en-US'.
A project runs exactly one browser per instance; two result rows come back for the same file, each reported under its own project name — see Multi-browser reporting.
Validation rules:
- The same
browserNamemay be configured at most once per project (duplicate names are a config error). instancesmust not be empty — remove the option to run the default Chromium instead.- At most one
(project, browser)pair may run headed (headless: false) per run; see Launch rules. coverage.provider: 'v8'requires every selected browser to be Chromium; see Launch rules.
headless
- Type:
boolean - Default:
truein CI environments,falsefor local development - CLI:
--browser.headless
Whether to run the browser in headless mode (without UI). Items in instances can override it per browser, subject to the one headed browser per run rule.
During local development, setting headless: false shows the browser window for easier debugging.
If you want headed mode for local debugging and headless in CI, control it with environment variables:
viewport
- Type:
BrowserViewport - Default:
undefined
Set the default runner iframe viewport for Browser Mode tests. When not specified, the Browser UI fills the preview panel. Items in instances can override the viewport per browser.
Use an explicit size when you want all files in a browser project to run with the same viewport:
You can also use a built-in device preset:
Supported presets:
browser.viewport controls the test runner iframe viewport. If you need Playwright context options such as locale, color scheme, or permissions, configure them through providerOptions.context.
port
- Type:
number - Default:
undefined(automatically selects an available port) - CLI:
--browser.port <port>
The port number for the Browser Mode Dev Server.
If you set port and the port is already in use, the behavior is controlled by strictPort: when strictPort: true, Rstest throws an error and exits; when strictPort: false, it falls back to another available port. If port is not specified, an available port is always selected automatically.
strictPort
- Type:
boolean - Default:
false - CLI:
--browser.strictPort
When port is specified, whether the port must be available:
true: throw an error and exit if the port is in usefalse: fall back to another available port if the port is in use
providerOptions
- Type:
Record<string, unknown> - Default:
{} - CLI:
--browser.providerOptions.*
Playwright options passed through to browser launch and context creation. Rstest does not validate or interpret the contents of this object — it forwards the values as-is to Playwright.
Each BrowserInstanceConfig in instances can carry its own providerOptions: top-level keys (launch, context) set on the instance replace the project-level keys, and keys the instance does not set keep the project-level value.
See Playwright provider options below for the supported fields.
You can also pass nested Playwright options from the CLI:
expect.toMatchScreenshot
- Type:
BrowserScreenshotMatcherConfig - Default:
maxDiffPixelRatio also defaults to 0; configure it instead of maxDiffPixels when you want to set a ratio. style is not injected by default. mask is assertion-only and defaults to no masks.
Configure defaults for toMatchScreenshot() across a Browser Mode project. Put pixel-comparison tolerances under comparatorOptions; capture and path options are siblings of it. Assertion-level values override the corresponding global values. mask remains assertion-specific because it uses browser Locator objects.
The defaults below apply when an option is omitted. Playwright supplies the capture defaults for maskColor, caret, scale, and omitBackground.
Set either comparatorOptions.maxDiffPixels or comparatorOptions.maxDiffPixelRatio, not both. A relative screenshotDirectory is resolved from each test file's directory. If omitted, it defaults to __screenshots__. A shared directory keeps references separate by project name and test file, so paths stay stable across checkouts. When the chosen directory is the test file's own directory, Rstest places references in its __screenshots__ subdirectory.
By default, references are stored in this layout:
The reference name comes from the explicit name or the test name, sanitized for use as a path. Names that could collide after sanitization receive a stable suffix. Every unnamed assertion gets a sequence number starting at 1, including a test's only screenshot (for example, <test-name>-1). Explicitly named assertions do not get this number.
Project names are not part of the default path, so projects using the same test file, screenshot name, browser, and platform share a reference. Use resolveScreenshotPath to isolate project-specific references. Existing references from Rstest's previous hashed layout are not moved automatically; move them to the new paths or regenerate them with --update.
Use resolveScreenshotPath when you need a different layout. It receives the absolute test file path, project and test names, browser, platform, and an optional ordinal for unnamed assertions. The first unnamed assertion receives no ordinal; later ones start at 2. Return an absolute path or a path relative to the project root. When configured, the resolver takes precedence over screenshotDirectory.
Launch rules
Every rstest run launches one browser per (provider, browserName, headless, providerOptions.launch) combination across all Browser Mode projects. Two projects that configure the same browser with the same launch key share one browser instance; different providerOptions.launch values or a different headless setting produce separate launches. Within a project, every browser of the project shares one build and one dev server.
The following rules are validated before any browser launches:
-
One headed browser per run. Browser mode opens a single debug window, so at most one
(project, browser)pair may setheadless: false; every other browser must setheadless: true. The error names the concrete fix:Only one (project, browser) pair can run headed per run: "web" ("chromium"). Browser mode opens one debug window, so every other browser must set headless: true. Most often this comes from
--browser.headless=falseon a multi-browser run: select a single headless pair with--browser.instances <name>or narrow the projects with--project. -
Watch mode does not support mixing headed and headless browsers. A watch session where one browser runs headed and another headless is rejected at validation; every configured browser must set
headless: true, or run without watch. -
Coverage provider
v8requires Chromium. Withcoverage.enabledandcoverage.provider: 'v8', a browser project selecting a non-Chromium browser fails validation. Switch tocoverage.provider: 'istanbul', or select Chromium only (--browser.instances chromium).
For strict browser-per-environment coverage you can still run separate executions (for example, in a CI matrix) with the --browser.instances filter:
CLI browser filters
--browser.instances <names> (repeatable and/or comma-separated) only filters, like --project: it selects the configured instances whose browserName is listed and never creates an instance from a name. The default Chromium instance (when nothing is configured) and the instance of the deprecated browser.browser count as configured instances.
- A browser project where none of its instances match is skipped for the run; node projects are unaffected.
- A listed name that no selected browser project configures is an error naming the name and the configured browsers per project.
- Duplicated names and names other than
chromium,firefoxandwebkitare errors.
--browser.name <name> stays as a deprecated option and emits a deprecation warning once per run. The project runs that single browser: with the configured instance's overrides when one has that browserName, otherwise as a plain instance with project-level defaults. It cannot be combined with --browser.instances.
Multi-browser reporting
Reporters do not see browsers. When a project selects more than one browser, each (project, browser) pair is reported as its own project named <project> (<browserName>), for example web (chromium) and web (firefox). A project that selects a single browser keeps its original name.
- Reporter payloads,
rstest listresults, and blob reports use this name asproject, so the same file run by two browsers yields two distinct results. Built-in reporters show it like any other project name, e.g.✓ [web (chromium)] tests/basic.test.ts. - The pairs are a reporting view only: every browser of a project still shares one build and one dev server, and
--projectfilters by the configured project name. - Two configured project names must not collide with a generated
<project> (<browserName>)name; a collision is a config error.
Multi-project config isolation
When using projects in Browser Mode, each project still compiles and executes with its own build config (for example plugins, include, and framework-specific setup).
Browser build-scoped options stay per project (provider, port, strictPort), while the browser instances, defaults, and per-browser overrides (instances, headless, viewport, providerOptions) are project-owned: two browser projects may run different browsers in one run. When two projects configure the same browser, launch sharing applies.
Mixing with node tests
You can configure both browser tests and Node.js tests together:
Provider options
Playwright
When using provider: 'playwright', the Playwright provider recognizes the following fields in providerOptions:
launch— Passed to Playwright'sbrowserType.launch(). Controls how the browser process is started.context— Passed to Playwright'sbrowser.newContext(). Controls the browser context created for each test file.
Since providerOptions is typed as Record<string, unknown>, you won't get IntelliSense out of the box. To get type checking and autocompletion, import types directly from the playwright package and use TypeScript's satisfies operator:
Related links
- Browser Mode Guide - Introduction and usage guide for Browser Mode
- Getting Started - Configure Browser Mode tests
- User interactions - Write semantic tests with
page+expect.element