Enable new Chromium headless mode
Playwright supports a new headless mode for Chromium that uses the real Chrome browser instead of the dedicated headless shell. To opt in, set channel to 'chromium' in launchOptions.
Vitest · Config reference · all subjects
config/browser
109 notes in this subject, read out of this brain and free to use. This is page 2 of 2.
launchOptions passed to playwright[browser].launch
launchOptions are directly passed down to the playwright[browser].launch command. These options configure how the browser is launched. Vitest will ignore the launch.headless option; instead use test.browser.headless. Vitest will also push debugging flags to launch.args if --inspect is enabled.
Playwright persistent context example configuration
import { playwright } from '@vitest/browser-playwright' import { defineConfig } from 'vitest/config' export default defineConfig({ test: { browser: { provider: playwright({ persistentContext: true, // or specify a custom directory: // persistentContext: './my-browser-data', }), instances: [{ browser: 'chromium' }], }, }, }) This example shows how to enable persistent context for storing browser state between test runs.
persistentContext string value as custom path
When persistentContext is set to a string value, that value is used as the path to the user data directory.
persistentContext true stores data in default location
When persistentContext is set to true, the user data is stored in ./node_modules/.cache/vitest-playwright-user-data.
persistentContext option type and default
persistentContext is a boolean or string option with a default value of false. When enabled, Vitest uses Playwright's persistent context instead of a regular browser context, allowing browser state (cookies, localStorage, DevTools settings, etc.) to persist between test runs. This option is ignored when running tests in parallel.
actionTimeout option
actionTimeout configures the default timeout for Playwright to wait until all accessibility checks pass and the action is actually done. Default: no timeout. You can also configure the action timeout per-action when using browser APIs.
connectOptions for remote Playwright server
connectOptions are directly passed down to the playwright[browser].connect command. Use connectOptions.wsEndpoint to connect to an existing Playwright server instead of launching browsers locally. This is useful for running browsers in Docker, in CI, or on a remote machine. Vitest forwards launchOptions to the Playwright server via the x-playwright-launch-options header when using playwright run-server CLI.
BrowserProvider interface members
The BrowserProvider interface defines the following members: name (string, required), mocker (BrowserModuleMocker, optional), initScripts (readonly string array, optional), supportsParallelism (boolean, required for experimental file parallelisation opt-in), getCommandsContext (function taking sessionId string and returning Record<string, unknown>, required), openPage (function taking sessionId string and url string and returning Promise<void>, required), getCDPSession (optional function taking sessionId string and returning Promise<CDPSession>), and close (function returning Awaitable<void>, required).
custom browser provider advanced API
The custom provider API is experimental and can change between patch versions. It is recommended for advanced use cases only; for typical browser testing scenarios, use the browser.instances configuration option instead.
browser.provider config type and purpose
The browser.provider configuration option accepts a BrowserProviderOption type, which is the return value of a provider factory. Providers can be imported from @vitest/browser-<provider-name> packages such as @vitest/browser-playwright, @vitest/browser-webdriverio, or @vitest/browser-preview, or you can create a custom provider.
browser.provider built-in factories
Vitest provides three built-in browser provider factories: playwright() from @vitest/browser-playwright, webdriverio() from @vitest/browser-webdriverio, and preview() from @vitest/browser-preview. Each factory returns a configured provider instance.
browser.provider shared configuration options
Provider factories accept options for shared configuration between all browser instances. Common options include launchOptions (an object for browser launch settings like slowMo and channel) and actionTimeout (a number in milliseconds for action timeouts). These options are passed as arguments to the provider factory function.
browser.provider instance-specific configuration
Individual browser instances can override provider options by specifying their own provider factory in the instances array configuration. Instance-specific provider options do not merge with parent configuration; they completely replace the parent options for that instance.
browser.screenshotDirectory type and default
The browser.screenshotDirectory configuration option has type string. Its default value is __screenshots__ in the test file directory. It specifies the path to the screenshots directory relative to the root.
browser.screenshotFailures option type and default
The browser.screenshotFailures configuration option is a boolean. Its default value is !browser.ui, which means it defaults to true when browser.ui is false, and defaults to false when browser.ui is true.
browser.screenshotFailures purpose
The browser.screenshotFailures configuration option controls whether Vitest should take screenshots when a test fails.
browser.testerHtmlPath option type and description
The browser.testerHtmlPath configuration option is of type string. It specifies a path to the HTML entry point, which can be relative to the root of the project. This file will be processed with the transformIndexHtml hook.
browser.trace string value meanings
browser.trace supports the following string values: 'on' captures trace for all tests (not recommended for performance), 'off' does not capture traces, 'on-first-retry' captures trace only when retrying the test for the first time, 'on-all-retries' captures trace on every retry of the test, 'retain-on-failure' captures trace only for tests that fail and automatically deletes traces for tests that pass.
browser.trace provider limitation
The browser.trace option is supported only by the playwright provider.
browser.trace option type and default
The browser.trace configuration option has type 'on' | 'off' | 'on-first-retry' | 'on-all-retries' | 'retain-on-failure' | object. Its default value is 'off'.
browser.trace CLI usage
The browser.trace option can be configured via CLI using flags like --browser.trace=on or --browser.trace=retain-on-failure.
browser.trace object configuration interface
When browser.trace is configured as an object, it follows the TraceOptions interface with the following properties: mode (required, type 'on' | 'off' | 'on-first-retry' | 'on-all-retries' | 'retain-on-failure'), tracesDir (optional, string type, specifies the directory where traces are stored; by default Vitest stores traces in __traces__ folder close to the test file), screenshots (optional, boolean type, default true, controls whether to capture screenshots during tracing for timeline preview), snapshots (optional, boolean type, default true, controls whether to capture DOM snapshot on every action and record network activity).
browser.trackUnhandledErrors default value
The default value for browser.trackUnhandledErrors is true.
browser.trackUnhandledErrors type
The browser.trackUnhandledErrors option is of type boolean.
browser.trackUnhandledErrors option
The browser.trackUnhandledErrors configuration option is a boolean that enables tracking of uncaught errors and exceptions so they can be reported by Vitest. When disabled, it removes all Vitest error handlers, which can help with debugging when using the 'Pause on exceptions' checkbox. The default value is true.
browser.ui config option
The browser.ui configuration option controls whether the Vitest UI should be injected into the page. It has type boolean, a default value of !isCI (meaning UI is injected by default during development when not in a CI environment), and can be set via CLI with --browser.ui=false. The UI is injected as an iframe during development.
browser.viewport option type and default
The browser.viewport configuration option has type { width, height } and a default value of 414x896. It sets the default iframe viewport dimensions.
browser.traceView.recordCanvas sub-option type
The browser.traceView.recordCanvas sub-option has type boolean. It captures canvas pixels in snapshots and enables a weaker replay iframe sandbox because rrweb needs scripts to redraw canvas data. The default value is false.
browser.traceView config option type
The browser.traceView configuration option has type boolean | { enabled?: boolean; recordCanvas?: boolean; inlineImages?: boolean }. It accepts either a boolean value to enable or disable trace-view collection, or an object with optional properties to configure additional snapshot fidelity options.
browser.traceView default value
The default value for browser.traceView is false.
browser.traceView.enabled sub-option type
The browser.traceView.enabled sub-option has type boolean. It enables Vitest trace-view artifact collection and has a default value of false.
browser.traceView.enabled CLI flag
The browser.traceView.enabled sub-option can be configured via the CLI flag --browser.traceView.enabled.
browser.traceView.inlineImages sub-option type
The browser.traceView.inlineImages sub-option has type boolean. It inlines loaded <img> pixels into snapshots for more portable replay, useful in the HTML reporter. The default value is false.
browser.traceView.inlineImages CLI flag
The browser.traceView.inlineImages sub-option can be configured via the CLI flag --browser.traceView.inlineImages.
browser.traceView object configuration example
To enable trace-view collection with additional snapshot fidelity options, use: export default defineConfig({ test: { browser: { traceView: { enabled: true, inlineImages: true, recordCanvas: true, }, }, }, })
browser.traceView boolean configuration example
To enable trace-view collection with a boolean value, use: export default defineConfig({ test: { browser: { traceView: true, }, }, })
browser.traceView purpose
browser.traceView enables trace-view collection for browser tests. Vitest captures DOM snapshots for browser interactions and can show them in the browser UI, Vitest UI, or HTML reporter when those surfaces are enabled — no external tools required.
browser.traceView.recordCanvas CLI flag
The browser.traceView.recordCanvas sub-option can be configured via the CLI flag --browser.traceView.recordCanvas.
WebdriverIO provider installation and setup
To run tests using WebdriverIO, install the @vitest/browser-webdriverio npm package and import the webdriverio export to specify in the test.browser.provider property of your Vitest config.
WebdriverIO provider with capabilities and instance-specific configuration
Example showing how to configure shared provider options and override them per instance: ```ts import { webdriverio } from '@vitest/browser-webdriverio' import { defineConfig } from 'vitest/config' export default defineConfig({ test: { browser: { provider: webdriverio({ capabilities: { browserVersion: '82', }, }), instances: [ { browser: 'chrome' }, { browser: 'firefox', provider: webdriverio({ capabilities: { 'moz:firefoxOptions': { args: ['--disable-gpu'], }, }, }) }, ], }, }, }) ``` Instance-specific provider options will NOT merge with parent options; they override them completely.
WebdriverIO remote function parameters
WebdriverIO provider accepts all parameters that the remote function from WebdriverIO accepts. See WebdriverIO documentation for available options.
WebdriverIO capabilities object most useful
Most useful WebdriverIO configuration options are located on the capabilities object. However, Vitest ignores nested capabilities because it relies on a different mechanism to spawn multiple browsers.
WebdriverIO browserName ignored by Vitest
Vitest ignores capabilities.browserName. Use test.browser.instances.browser property instead to specify which browser to use.
WebdriverIO test runner options ignored
Vitest ignores all test runner options from WebdriverIO configuration because it only uses webdriverio's browser capabilities.
WebdriverIO headless mode in CI with Chrome on Linux
Vitest enables browser.headless automatically in CI. If you explicitly set headless: false for Chrome on a Linux CI runner, Chrome still needs a display server. Without one, WebDriverIO or ChromeDriver can fail with errors like 'session not created: probably user data directory is already in use'. Run tests through xvfb-run when you need headful Chrome in CI, or keep browser.headless enabled in CI and use headful mode only for local debugging.
WebdriverIO provider maintenance status
The WebdriverIO provider (@vitest/browser-webdriverio) is community maintained by the Vitest community in the vitest-community organization, separately from core Vitest packages. Provider-specific issues should be reported to the provider repository, not the main Vitest repository.
WebdriverIO provider basic configuration example
Example showing how to configure WebdriverIO provider with instances: ```ts import { webdriverio } from '@vitest/browser-webdriverio' import { defineConfig } from 'vitest/config' export default defineConfig({ test: { browser: { provider: webdriverio(), instances: [{ browser: 'chrome' }] }, }, }) ``` This configures a single Chrome browser instance for testing.
fsModuleCache browser support limitation
The fsModuleCache option does not affect the browser environment in Vitest.