Vitest 브라우저 모드 ("Vitest Browser Mode - The Future of Frontend Testing")

— 컴포넌트 테스트와 실제 브라우저의 결합

Vitest Browser Mode는 실제 브라우저에서 컴포넌트 단위 테스트를 실행하는 새로운 테스트 방식이다.
JSDOM 기반의 단위 테스트와 E2E 사이의 공백을 메우는 접근으로, Vitest v4부터 Stable로 제공된다.

---

왜 필요한가

기존 Vitest/Jest 테스트는 대부분 JSDOM에서 실행된다. 이는 빠르고 유용하지만 다음과 같은 한계가 있다.

• localStorage, sessionStorage
• navigator.clipboard
• IntersectionObserver, ResizeObserver
• URL, 쿠키, 실제 CSS 레이아웃

이런 Web API는 모킹이 필요하거나 정확하지 않다.
Vitest Browser Mode는 실제 Chrome/Firefox/WebKit에서 컴포넌트를 렌더링해 이 문제를 제거한다.

---

E2E와의 차이

• E2E (Playwright/Cypress)

  • 전체 페이지 단위
  • 느리고 설정 비용 큼

• Vitest Browser Mode

  • 단일 컴포넌트 단위
  • 실제 브라우저 실행
  • 빠른 실행 속도
  • 테스트 중 UI 미리보기 가능
  • 시각적 회귀 스크린샷 내장

즉, 컴포넌트 테스트의 현실성을 크게 끌어올린 방식이다.

---

테스트 작성 방식의 핵심 변화

1) render()는 async

import { render } from 'vitest-browser-react';

test('render', async () => {
  const screen = await render(<Component />);
});

• React Testing Library와 달리 항상 await
• 반환값은 screen (query 함수 포함)

---

2) Locator 기반 API

getByText, getByRole 등은 HTMLElement가 아닌 Locator를 반환한다.

const heading = screen.getByRole('heading');
expect(heading).toHaveTextContent('Hello');

• 동기 반환
• 내부적으로 lazy evaluation
• 하나 또는 여러 요소 모두 처리 가능

---

3) 비동기 검증: await expect.element()

상태 변화가 있는 경우, Locator를 대상으로 polling 기반 검증을 사용한다.

await expect
  .element(screen.getByRole('heading'))
  .toHaveTextContent('updated');

• 조건이 만족될 때까지 재시도
• RTL의 waitFor 개념에 해당

---

4) 여러 요소 처리

const buttons = screen.getByRole('button');

expect(buttons).toHaveLength(2);
expect(buttons.first()).toHaveTextContent('First');
expect(buttons.last()).toHaveTextContent('Second');

• getAllBy... 없음
• 하나의 Locator로 다수 요소 제어

---

5) 요소 부재 검증

await expect
  .element(screen.getByRole('heading'))
  .not.toBeInTheDocument();

• queryBy... 없음
• not.toBeInTheDocument() 사용

---

6) 사용자 액션

Locator 자체에 인터랙션 메서드가 있다.

await screen.getByRole('button').click();

• .click(), .fill(), .selectOptions() 등
• act() 불필요
• 항상 async

---

Provider 선택

Vitest Browser Mode는 브라우저 실행 방식을 Provider로 분리한다.

• playwright (권장)

  • CI/CD 지원
  • Headless/GUI 모두 가능

• preview

  • 로컬 전용, CI 불가

• webdriverio

  • 기존 WebdriverIO 사용자용

실무에서는 Playwright Provider가 사실상 표준이다.

---

설정 개요 (요지)

• 테스트 파일 분리 권장: *.browser.ts(x)
• browser.enabled = true
• Playwright provider 사용
• CI 환경에서는 headless: true

브라우저 실행 전 1회:

playwright install --with-deps

---

실제 운영 관점 정리

• 기존 Vitest/Jest 테스트 대체 불필요
• 필요한 컴포넌트부터 선별 도입
• Web API 의존 컴포넌트에 특히 효과적
• 실행 속도는 예상보다 빠름
• React 외 Vue, Svelte 등도 지원

---

결론

Vitest Browser Mode는 새로운 테스트 러너가 아니다.
컴포넌트 테스트의 실행 환경을 현실로 끌어오는 방식이다.

• 단위 테스트의 속도
• 실제 브라우저의 정확성
• UI 기반 디버깅
• 시각적 회귀 테스트

이 네 가지를 동시에 요구한다면,
Vitest Browser Mode는 충분히 표준 테스트 도구 후보에 올라와 있다.

---

• 참고: Vitest Browser Mode - The Future of Frontend Testing