Vitest · Config reference · all subjects

browser options

12 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

locators.extend API for custom browser locators

Vitest provides a locators.extend API to add custom locators beyond the built-in ones. Custom locators can return a Playwright locator string that will be scoped to the parent locator. The API allows extending locators with methods that can receive context (this: Locator) and enables chaining with other locator methods. This preserves retry-ability protection compared to using raw CSS selectors.

page.mark API for trace annotations

The page.mark API allows adding custom markers to the Playwright Trace Viewer. It can be used with just a marker name (await page.mark('marker name')) or with an async function to group a flow of actions under a named entry.

locator.mark API for trace annotations

The locator.mark API is available on Vitest browser locators for adding custom markers to the Playwright Trace Viewer, similar to page.mark.

Strict mode default for webdriverio and preview

In Vitest 4.1, locating elements is now strict by default in webdriverio and preview, matching Playwright behavior. When a locator resolves to multiple elements, Vitest throws a strict mode violation instead of silently picking one. You can opt out with { strict: false }.

Browser Mode moved to stable

Browser Mode is no longer experimental in Vitest 4. The experimental tag has been removed and public API changes were introduced.

Browser provider packages in Vitest 4

Vitest 4 requires separate browser provider packages to be installed: @vitest/browser-playwright, @vitest/browser-webdriverio, or @vitest/browser-preview. The @vitest/browser package is no longer needed as it is now included in every provider package automatically.

Browser context import path in Vitest 4

The browser context import path changed from @vitest/browser/context to vitest/browser. The old import path will continue to work until the next major version.

Visual regression testing in Vitest 4

Vitest 4 adds support for visual regression testing through the toMatchScreenshot assertion. This assertion captures and compares screenshots of UI components and pages to detect unintended visual changes.

Browser test debugging in Vitest 4

The VSCode extension now supports a Debug Test button when running browser tests. Alternatively, start Vitest with the --inspect flag (available with playwright and webdriverio providers) and connect to DevTools manually. When using --inspect, Vitest automatically disables the trackUnhandledErrors option.

toBeInViewport matcher in Vitest 4

Vitest 4 introduces the toBeInViewport matcher that checks if an element is currently in viewport using the IntersectionObserver API. It supports an optional ratio parameter to specify what percentage of the element should be visible.

page.frameLocator API in Vitest 4

Vitest 4 supports the page.frameLocator API (only with playwright provider) which returns a FrameLocator instance that can be used to find elements inside iframes.

Locator length property in Vitest 4

Every locator in Vitest 4 exposes a length property, allowing them to be used automatically with the toHaveLength matcher.

Give your agent this brain