Vitest Browser Mode | Real Browser Tests, Playwright Provider, Visual Regression

What problem Browser Mode solves

Traditional frontend tests run under Node with jsdom or happy-dom. That is fast and sufficient for state and logic, but it diverges from real browsers for:

• Browser-only APIs (ResizeObserver, IntersectionObserver, subtle Canvas behavior).
• Focus, IME, and realistic input pipelines.
• Pixel-perfect layout and font rendering.

Vitest Browser Mode serves the test bundle to a real browser (Chromium, Firefox, WebKit, etc., depending on provider) so assertions execute in an environment close to users.

It is not a full replacement for E2E: it targets component- or page-scoped checks with Vitest’s fast iteration, while multi-page journeys remain better as Playwright/Cypress suites.

---

Architecture: runner, provider, and browser

1. Vitest (Node) coordinates discovery, watch mode, and reporting—same as non-browser Vitest.
2. A browser provider (@vitest/browser-playwright, @vitest/browser-webdriverio, or preview-only packages) launches browser processes and exposes a control channel.
3. Playwright speaks Chrome DevTools Protocol (CDP) to Chromium (and equivalent protocols for Firefox/WebKit). WebdriverIO targets the WebDriver / BiDi ecosystem—useful if you already run Selenium grids.
4. Tests import from vitest/browser (page, userEvent, expect.element) instead of only vitest globals—the bridge serializes locator queries and assertions across the process boundary.

Understanding this split explains failures: native ESM in the browser may reject vi.spyOn patterns that work in Node; Vitest documents vi.mock(..., { spy: true }) as an alternative.

---

Mocking and module graph in the browser

Mocking still uses Vitest’s vi API, but the module graph is evaluated in the browser. Namespace imports can be sealed, so partial mocks may need factory functions or spy: true options. Keep mocks serialization-friendly—heavy Node-only objects cannot cross into the browser test VM the same way as in Node tests.

---

Coverage instrumentation

Coverage in Browser Mode typically relies on V8 or Istanbul instrumentation of the bundled code. The exact setup depends on Vitest version and provider; expect different line mappings than Node-only runs. Many teams:

• Run line/branch coverage primarily on Node + jsdom tests (fast, stable mapping).
• Use Browser Mode for behavioral and visual guarantees, not as the sole coverage source.

If you need unified numbers, configure the coverage provider per Vitest project and merge reports in CI (e.g., lcov merge tools).

---

E2E browser automation overlap

Layer	Typical tool	Scope
Unit / RTL	Vitest + jsdom	Fast, logic-heavy
Browser Mode	Vitest + Playwright provider	Real DOM, components
E2E	Playwright / Cypress	Full app, routing, auth

Use Browser Mode when you want Vite-aligned bundling and Vitest reporters; use standalone Playwright when the spec reads like a user story across URLs.

---

Setup sketch

npm install -D vitest @vitest/browser-playwright playwright
npx playwright install

import { defineConfig } from 'vitest/config';
import { playwright } from '@vitest/browser-playwright';

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: playwright(),
      instances: [{ browser: 'chromium' }],
      headless: true,
    },
  },
});

Use npx vitest init browser when bootstrapping a new repo—the CLI pins compatible versions.

---

Visual regression (toMatchScreenshot)

Screenshots capture rendered output for pixel diffing. Stabilize CI by fixing OS, viewport, fonts (document.fonts.ready), and disabling animations where needed. Split test:visual from test:unit so PR pipelines stay fast; run visual baselines nightly or on demand.

---

CI: install browsers and optional shards

- run: npx playwright install --with-deps
- run: npx vitest run --browser.headless

Large suites benefit from Vitest projects or job sharding—same idea as Playwright E2E parallelization.

---

Production testing patterns

Browser Mode helps pre-release quality. In production, complement it with:

• Synthetic checks (scheduled Playwright scripts against prod or canary URLs).
• Real user monitoring (RUM) and error tracking—orthogonal to Vitest but part of operational testing.

---

References

• Vitest Browser Mode
• Visual regression testing