Vitest Browser Mode | Real Browser Tests

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

---

자주 묻는 질문 (FAQ)

Q. 이 내용을 실무에서 언제 쓰나요?

A. Run Vitest in real browsers: providers, vitest/browser APIs, Playwright vs WebdriverIO, screenshot tests, CI setup, and … 실무에서는 위 본문의 예제와 선택 가이드를 참고해 적용하면 됩니다.

Q. 선행으로 읽으면 좋은 글은?

A. 각 글 하단의 이전 글 또는 관련 글 링크를 따라가면 순서대로 배울 수 있습니다. C++ 시리즈 목차에서 전체 흐름을 확인할 수 있습니다.

Q. 더 깊이 공부하려면?

A. cppreference와 해당 라이브러리 공식 문서를 참고하세요. 글 말미의 참고 자료 링크도 활용하면 좋습니다.

---

같이 보면 좋은 글 (내부 링크)

이 주제와 연결되는 다른 글입니다.

• Jest Testing Guide | Unit Tests· Mocks
• Playwright Component Testing | React, Vue, Svelte, MSW & CI
• Playwright E2E Testing | Automation· Locators

---

이 글에서 다루는 키워드 (관련 검색어)

Vitest, Testing, Browser, E2E, Playwright, Visual Regression 등으로 검색하시면 이 글이 도움이 됩니다.