Vitest 컴포넌트 테스트 실전: Browser Mode와 Playwright 통합

솔직히 말하면, 처음 Canvas 컴포넌트를 테스트할 때 꽤 큰 함정에 빠졌습니다.

테스트 리포트에 초록색 PASS가 찍힌 것을 보고 자신 있게 코드를 제출했습니다. 그런데 다음 날, 동료가 실제 브라우저에서 페이지를 열자 Canvas가 전혀 렌더링되지 않았습니다. 테스트는 분명 통과했는데요?!

나중에야 알았습니다. jsdom은 그저 가짜 브라우저에 가깝습니다. DOM API는 흉내 내지만 Canvas의 실제 렌더링 동작, CSS 계산 스타일, Web Components의 생명주기 같은 것들은 테스트하지 못합니다. 반년 동안 사용한 단위 테스트 설정이 사실은 겉부분만 확인하고 있었던 셈입니다.

그래서 Vitest가 3.0 버전에서 Browser Mode를 내놓았습니다. 테스트를 실제 브라우저에서 바로 실행하는 방식입니다. jsdom처럼 Node.js 안에서 DOM을 흉내 내는 것이 아니라, Browser Mode는 Chromium/Firefox/Safari를 띄워 컴포넌트를 실제로 렌더링하고 Playwright API로 상호작용합니다. 테스트가 통과했다면, 실제로 통과한 것입니다.

이 글에서는 Browser Mode를 처음부터 설정하는 방법부터 React/Vue 컴포넌트 실전 테스트, CI 환경의 커버리지 게이트까지 다룹니다. Vitest 테스트 가이드 시리즈의 세 번째 글이며, 앞선 두 글에서 단위 테스트 설정과 TDD 흐름을 다뤘다면 이번에는 컴포넌트 테스트라는 퍼즐 조각을 채워 보겠습니다.

왜 Browser Mode가 필요할까?

이렇게 물을 수 있습니다. jsdom이면 충분하지 않나요?

솔직히 순수 로직 컴포넌트라면, 예를 들어 계산기나 폼 검증기 같은 경우에는 jsdom만으로도 충분합니다. jsdom은 Node.js 환경의 DOM 시뮬레이터라 매우 빠르고 설정도 간단합니다. 앞선 두 글에서 설명한 단위 테스트도 모두 jsdom 환경에서 실행했고, 반응형 데이터나 이벤트 트리거 테스트에는 문제가 없었습니다.

하지만 다음과 같은 상황을 만나면 jsdom은 힘을 잃습니다.

• Canvas 그리기: jsdom에는 Canvas API가 있지만 실제로 그리지는 않습니다. ctx.fillRect()가 몇 번 호출됐는지는 테스트할 수 있습니다. 하지만 그려진 도형이 맞는지는 테스트할 수 없습니다.
• CSS 계산 스타일: jsdom의 getComputedStyle()은 빈 객체를 반환하는 경우가 많습니다. 실제 브라우저에서는 요소 너비가 부모 컨테이너, padding, border의 영향을 받지만 jsdom은 이를 계산하지 못합니다.
• Web Components: 커스텀 요소의 connectedCallback, disconnectedCallback은 jsdom에서도 흉내 내지만, 생명주기가 발생하는 타이밍이 실제 브라우저와 다릅니다.
• 비동기 렌더링: animation frame, requestIdleCallback, IntersectionObserver 같은 API는 jsdom에 없거나 구현이 불완전합니다.

제가 직접 겪은 사례를 하나 들어 보겠습니다. 지난해 프로젝트에서 CSS 애니메이션으로 버튼의 펼침/접힘을 제어하는 컴포넌트를 만들었습니다. jsdom 테스트에서는 transitionend 이벤트가 절대 발생하지 않았습니다. 실제 transition이 없기 때문입니다. 그래서 mock 이벤트로 테스트를 작성했는데, 실제 브라우저에서 애니메이션 시간이 바뀐 뒤에도 테스트는 여전히 통과했습니다. 하지만 컴포넌트는 이미 깨져 있었습니다.

Browser Mode는 바로 이런 문제를 해결하기 위해 등장했습니다. 실제 브라우저에서 컴포넌트를 렌더링하고, 테스트 코드를 실행하면 Chromium(또는 Firefox/Safari)을 띄워 컴포넌트를 페이지에 마운트한 뒤 Playwright API로 클릭하고, 입력하고, 기다립니다. 실제 브라우저에서 일어나는 일을 그대로 테스트합니다.

언급할 만한 데이터도 있습니다. Vitest 3.0의 Browser Mode는 Chromium 컨텍스트를 공유하므로 테스트 시작 시 브라우저를 한 번만 열고 모든 테스트가 같은 인스턴스를 공유합니다. 공식 설명에 따르면 기존 Playwright E2E보다 30% 빠릅니다. 컴포넌트 50개를 테스트하더라도 브라우저를 반복해서 켜고 끄는 시간을 기다릴 필요가 없습니다.

또 한 가지, 테스트 피라미드는 컴포넌트 테스트 영역에서 논쟁이 있습니다. 전통적인 피라미드는 단위 테스트가 가장 많고 E2E가 가장 적습니다. 하지만 Vue 공식 블로그에는 반대 관점도 있습니다. alexop.dev의 테스트 피라미드 반전 모델은 통합 테스트 70%, 단위 테스트 20%, E2E 10%를 제안합니다. 이유는 컴포넌트 자체가 이미 통합 단위이기 때문입니다. 컴포넌트는 템플릿, 스타일, 로직을 조합합니다. jsdom 단위 테스트는 로직 일부만 확인할 수 있지만, 통합 테스트는 전체 동작을 검증할 수 있습니다. Browser Mode는 바로 이 빈틈을 채웁니다. jsdom보다 현실적이고, Playwright E2E보다 가볍습니다.

Browser Mode 설정 실전

Browser Mode 설정은 사실 그렇게 복잡하지 않습니다. 다만 제가 겪었던 몇 가지 함정은 미리 짚고 가겠습니다.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

의존성 설치

먼저 Vitest와 Browser Mode provider를 설치합니다. 공식적으로는 Playwright를 권장합니다.

npm install -D vitest @vitest/browser-playwright

Playwright는 Chromium, Firefox, WebKit 세 브라우저를 함께 설치할 수 있습니다. Chromium만 테스트하고 싶다면, 대부분의 경우 이것으로 충분하므로 설치 시 다음처럼 지정할 수 있습니다.

npx playwright install chromium

이 단계는 조금 느립니다. Chromium 패키지가 대략 170MB 정도 됩니다. 다운로드가 끝나면 기본 준비는 끝난 셈입니다.

vitest.config.ts 설정

설정 파일은 간단하지만 한 가지 세부 사항을 주의해야 합니다.

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

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

여기서 instances 설정은 어떤 브라우저에서 테스트를 실행할지 결정합니다. 여러 브라우저 호환성을 테스트하고 싶다면 Firefox와 WebKit을 추가할 수 있습니다.

instances: [
  { browser: 'chromium' },
  { browser: 'firefox' },
  { browser: 'webkit' },  // Safari
]

하지만 저는 보통 Chromium만 켭니다. 여러 브라우저 테스트는 느리고, 대부분의 프론트엔드 버그는 Chromium에서 발견해도 충분합니다. Safari 호환성 문제는 Playwright E2E로 핵심 경로를 커버합니다.

Headless 모드 vs UI 모드

이 선택은 조금 미묘합니다.

• Headless 모드: 브라우저 창을 열지 않고 백그라운드에서 테스트를 실행합니다. CI 환경에 적합하고 속도도 빠르지만, 컴포넌트 렌더링 과정을 볼 수 없습니다.
• UI 모드: 브라우저 창을 열어 컴포넌트가 렌더링되고, 클릭되고, 입력되는 과정을 볼 수 있습니다. 개발 단계 디버깅에 적합하며 테스트를 작성할 때 유용합니다.

저는 개발할 때 UI 모드를 사용합니다. 명령어는 다음과 같습니다.

npx vitest --browser.ui

Vitest는 테스트 워크벤치를 열어 줍니다. 왼쪽에는 테스트 목록이 있고 오른쪽에는 브라우저 창이 있습니다. 테스트 파일을 클릭하면 브라우저에 컴포넌트가 렌더링되고, 테스트 코드가 실행되는 과정을 직접 볼 수 있습니다. 버튼 클릭이 반응하지 않나요? 브라우저에서 바로 디버깅하면 됩니다.

CI 환경에서는 Headless 모드를 사용하며, 설정에 한 줄을 추가합니다.

browser: {
  provider: playwright(),
  enabled: true,
  headless: true,  // CI에서는 headless 강제
  instances: [{ browser: 'chromium' }],
}

테스트 파일 이름 규칙

공식 문서는 Browser Mode 테스트 파일을 일반 .test.ts와 구분하기 위해 .browser.test.ts로 이름 짓는 것을 권장합니다. 직접 써 보니 장점은 다음과 같습니다.

• jsdom 단위 테스트와 Browser Mode 컴포넌트 테스트를 동시에 실행해도 서로 섞이지 않습니다.
• CI에서 알 수 없는 실패가 발생했을 때 파일명만 봐도 브라우저 테스트라는 것을 알 수 있어 조사 방향이 명확해집니다.

다만 Vitest가 이 이름 규칙을 강제하지는 않습니다. .test.ts를 써도 됩니다. 핵심은 설정에서 Browser Mode 테스트가 있는 디렉터리를 지정하거나, 아예 모든 테스트를 Browser Mode에서 실행하도록 하는 것입니다. 저는 분리하는 편입니다. 단위 테스트는 jsdom, 컴포넌트 테스트는 Browser Mode로 둡니다.

React/Vue 컴포넌트 테스트 실전

이 부분이 Browser Mode의 핵심 사용법입니다. 솔직히 기존 Testing Library 방식과 조금 다르지만, 익숙해지면 꽤 편합니다.

React 컴포넌트 테스트

먼저 React 어댑터를 설치합니다.

npm install -D @vitest/browser-react

그다음 테스트를 작성합니다. 버튼을 클릭하면 카운트가 1 증가하는 Counter 컴포넌트가 있다고 가정해 보겠습니다.

// Counter.browser.test.ts
import { page } from '@vitest/browser/context'
import { userEvent } from '@vitest/browser/context'
import Counter from './Counter'

test('버튼 클릭 카운트', async () => {
  // 컴포넌트를 브라우저에 렌더링
  await page.mount(<Counter />)

  // 버튼 요소 찾기
  const button = page.getByRole('button', { name: 'Count: 0' })

  // 버튼 클릭
  await userEvent.click(button)

  // 텍스트 변경 검증
  await expect.element(button).toHaveTextContent('Count: 1')
})

Testing Library 방식과 비교해 보겠습니다. Testing Library는 render()를 사용하고, Browser Mode는 page.mount()를 사용합니다. Testing Library는 screen.getByRole()을 사용하고, Browser Mode는 page.getByRole()을 사용합니다. API는 꽤 비슷하지만, page 객체가 Vitest Browser Mode의 컨텍스트라는 점이 다릅니다.

세부적으로는 await expect.element(button)에 주목할 필요가 있습니다. 이것은 Vitest의 Web Testing API이며, 요소 상태 변화를 자동으로 기다립니다. 직접 await waitFor()를 작성할 필요가 없습니다. 테스트 프레임워크가 비동기 대기를 처리해 줍니다. 이 부분은 Testing Library보다 간결합니다.

Vue 컴포넌트 테스트

Vue 방식도 비슷하지만 Vue 어댑터가 필요합니다.

npm install -D @vitest/browser-vue

Vue Counter 컴포넌트를 테스트해 보겠습니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

// Counter.browser.test.ts
import { page } from '@vitest/browser/context'
import { userEvent } from '@vitest/browser/context'
import Counter from './Counter.vue'

test('버튼 클릭 카운트', async () => {
  // Vue 컴포넌트 렌더링
  await page.mount(Counter)

  // 버튼 찾기, 클릭, 검증
  const button = page.getByRole('button', { name: 'Count: 0' })
  await userEvent.click(button)
  await expect.element(button).toHaveTextContent('Count: 1')
})

Vue 2는 @vue/test-utils 방식이 필요하며 Browser Mode가 직접 지원하지 않습니다. 하지만 Vue 3 프로젝트라면 @vitest/browser-vue만으로 충분합니다.

실제 사례 하나

제 프로젝트에는 이런 상황이 있었습니다. HTML5 Drag & Drop API로 구현한 드래그 정렬 컴포넌트입니다. jsdom 환경에서는 dragstart, drop 이벤트를 시뮬레이션하기 어렵습니다. 결국 mock을 써야 하고, 테스트로 확인되는 것은 이벤트가 발생했다는 사실뿐입니다. 정렬 로직이 정확한지는 알 수 없습니다.

Browser Mode로 바꾸면 테스트를 다음처럼 바로 작성할 수 있습니다.

test('드래그 정렬', async () => {
  await page.mount(<SortableList items={['A', 'B', 'C']} />)

  const itemA = page.getByText('A')
  const itemC = page.getByText('C')

  // A를 C 뒤로 드래그
  await userEvent.dragTo(itemA, itemC)

  // 순서 변경 검증
  const items = page.getByRole('listitem')
  await expect.element(items.nth(2)).toHaveTextContent('A')
})

실제 브라우저에서는 Drag & Drop API가 실제로 발생하고, 정렬 로직도 실제로 실행되며, 요소 순서도 실제로 바뀝니다. 테스트가 통과했다면 정말 문제가 없는 것입니다.

이것이 Browser Mode의 가치입니다. 시뮬레이션된 동작이 아니라 실제 동작을 테스트합니다.

Playwright vs Browser Mode 선택 가이드

조금 헷갈릴 수 있습니다. Browser Mode와 Playwright 모두 브라우저 테스트 아닌가요? 차이가 무엇일까요?

간단히 말하면 Browser Mode는 컴포넌트를 테스트하고, Playwright는 흐름을 테스트합니다.

핵심 차이

Browser Mode의 포지션은 컴포넌트 테스트입니다. 컴포넌트를 브라우저에 마운트하지만, 그 컴포넌트 자체의 동작만 테스트합니다. Playwright의 포지션은 E2E입니다. 완전한 애플리케이션을 열고, 이동하고, 로그인하고, 폼을 제출하면서 전체 흐름을 테스트합니다.

비유하자면 Browser Mode는 외과 의사가 현미경으로 단일 세포를 보는 것에 가깝고, Playwright는 건강검진 의사가 전체 장기 시스템을 보는 것에 가깝습니다. 서로 용도가 다르며 대체 관계가 아닙니다.

조합 전략

실제 프로젝트에서는 저는 이렇게 사용합니다.

• Browser Mode: 버튼, 폼, 카드, 모달 같은 모든 UI 컴포넌트를 테스트합니다. 개발 중 작성하고 코드와 함께 제출합니다. 테스트가 빠르고 피드백이 즉각적입니다.
• Playwright E2E: 로그인 후 홈 화면 확인, 검색 후 결과 확인, 제출 후 주문 확인 같은 3-5개의 핵심 경로를 테스트합니다. 배포 전 또는 CI의 일일 빌드에서만 실행합니다.

이 조합의 장점은 다음과 같습니다.

1. Browser Mode가 대부분의 UI 버그를 커버하므로 개발 단계에서 발견할 수 있습니다.
2. Playwright가 페이지 간 통합 버그를 커버하므로 배포 전에 검증할 수 있습니다.
3. 유지보수 비용을 통제할 수 있습니다. 컴포넌트 테스트 50개, E2E 테스트 5개 정도라면 CI를 지나치게 느리게 만들지 않습니다.

언제 무엇을 선택할까?

간단히 판단하면 다음과 같습니다.

• Browser Mode 선택: 단일 컴포넌트의 UI 동작, 예를 들어 클릭, 입력, 렌더링, 스타일을 테스트해야 할 때. 컴포넌트 코드가 바뀌면 즉시 피드백이 필요할 때.
• Playwright 선택: 로그인 -> 이동 -> 조작 -> 검증처럼 여러 페이지 흐름을 테스트해야 할 때. 또는 프론트엔드 + 백엔드 API + 데이터베이스처럼 시스템 간 통합을 테스트해야 할 때.

예를 들어 날짜 선택기 컴포넌트의 날짜 범위 제한, 비활성 날짜, 형식 표시를 테스트한다면 Browser Mode를 사용합니다. 사용자가 예약 페이지에서 날짜를 선택하고, 주문을 제출하고, 결제 페이지로 이동하는 과정을 테스트한다면 Playwright를 사용합니다.

또 한 가지가 있습니다. Browser Mode는 프론트엔드만 테스트하지만 Playwright는 풀스택도 테스트할 수 있습니다. 애플리케이션에 백엔드 API가 있다면 Playwright E2E로 프론트엔드와 백엔드 연동을 함께 검증할 수 있습니다. Browser Mode는 프론트엔드 컴포넌트만 테스트하므로 백엔드는 mock해야 합니다.

CI 환경 커버리지 게이트

커버리지 설정은 CI 환경의 마지막 고리입니다. 솔직히 저도 예전에는 이 부분을 크게 신경 쓰지 않았습니다. 어느 날 코드 리팩터링 후 테스트 커버리지가 80%에서 60%로 떨어졌고, 운영 환경에서 버그가 난 뒤에야 커버리지 게이트의 중요성을 알았습니다.

커버리지 설정

vitest.config.ts에 커버리지 임계값을 추가합니다.

test: {
  coverage: {
    provider: 'v8',  // 또는 'istanbul'
    reporter: ['text', 'json', 'html'],
    thresholds: {
      lines: 80,
      functions: 80,
      branches: 75,
      statements: 80
    }
  }
}

임계값은 어느 정도가 적절할까요? 제 경험은 다음과 같습니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

• 새 프로젝트: 50%부터 시작해 천천히 올립니다. 처음부터 너무 높게 잡으면 개발 압박이 큽니다.
• 성숙한 프로젝트: 80%가 합리적인 값입니다. 핵심 모듈은 90% 또는 95%로 더 높게 둘 수 있습니다.
• 100%를 추구하지 말기: 경계 분기나 예외 처리는 테스트하기 어려운 경우가 있습니다. 억지로 테스트를 쓰면 오히려 시간이 낭비됩니다.

커버리지 테스트를 실행합니다.

npx vitest run --coverage

커버리지가 임계값보다 낮으면 Vitest가 오류를 내고 CI 빌드가 실패합니다. 이것이 게이트입니다. 임계값보다 낮은 코드는 메인 브랜치에 병합할 수 없습니다.

GitHub Actions 통합

CI 워크플로에는 두 단계를 추가합니다. 테스트 실행과 커버리지 리포트입니다.

# .github/workflows/test.yml
name: Test

on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci
      - run: npx playwright install chromium --with-deps

      - name: Run tests with coverage
        run: npx vitest run --coverage

      - name: Report coverage
        uses: davelosert/vitest-coverage-report-action@v2
        with:
          json-summary-path: './coverage/coverage-summary.json'

이 Action은 PR 댓글에 커버리지 변화를 자동으로 표시합니다.

• 커버리지 변화율, 예를 들어 80%에서 79%로 내려가면 -1%로 표시
• 어떤 파일의 커버리지가 낮아졌는지
• 새로 추가된 코드 중 커버되지 않은 부분

PR 작성자는 한눈에 알 수 있습니다. 내가 새로 작성한 코드의 커버리지가 부족하니 테스트를 보강해야겠다고요.

CI 주의 사항

Browser Mode를 CI 환경에서 사용할 때는 몇 가지 함정이 있습니다.

1. Playwright 브라우저 설치: --with-deps 옵션을 추가해야 합니다. 그렇지 않으면 Chromium이 시작되지 않을 수 있습니다.
2. Headless 모드: CI 환경에는 디스플레이가 없으므로 설정에서 headless: true를 강제합니다.
3. Timeout 설정: Browser Mode 테스트는 jsdom보다 느립니다. CI timeout 임계값을 조금 늘리는 것이 좋습니다. 저는 30초로 둡니다.
4. 병렬 제어: Browser Mode는 브라우저 인스턴스를 공유하므로 병렬 테스트 수를 너무 높이지 않는 편이 좋습니다. 저는 maxWorkers: 4로 제한합니다.

제가 사용하는 CI 워크플로의 전체 설정은 다음과 같습니다.

- name: Run browser tests
  run: npx vitest run --coverage --browser.headless
  env:
    CI: true

--browser.headless는 브라우저 창이 열리지 않도록 보장하고, CI: true 환경 변수는 Vitest가 일부 동작을 자동으로 조정하게 합니다. 예를 들어 색상 출력을 비활성화합니다.

정리

길게 이야기했지만 핵심은 간단합니다. jsdom은 실제 브라우저 동작을 테스트할 수 없고, Browser Mode는 할 수 있습니다. Canvas, CSS 계산 스타일, Web Components, 드래그, 애니메이션 같은 상황에서는 Browser Mode가 사실상 유일한 선택입니다.

설정은 어렵지 않습니다. @vitest/browser-playwright를 설치하고 vitest.config.ts를 몇 줄 수정하면 실행할 수 있습니다. React와 Vue 컴포넌트 테스트 API도 Testing Library와 비슷해서 배우는 장벽이 높지 않습니다.

하지만 Browser Mode가 만능은 아닙니다. Browser Mode는 단일 컴포넌트를 테스트하고, Playwright는 흐름을 테스트합니다. 둘을 조합해 사용하세요. 개발 단계에서는 Browser Mode로 모든 UI 컴포넌트를 커버하고, 배포 전에는 Playwright E2E로 핵심 경로를 검증합니다. 이렇게 하면 테스트 커버리지는 넓어지고 CI도 빠르게 유지할 수 있습니다.

커버리지 게이트는 마지막 고리입니다. 임계값을 설정하고, 임계값보다 낮은 PR은 병합하지 못하게 하면 커버리지가 서서히 떨어지는 것을 막을 수 있습니다. GitHub Actions에 coverage-report-action을 추가하면 PR 댓글에 커버리지 변화가 자동으로 표시되어 문제를 한눈에 볼 수 있습니다.

아직 Browser Mode를 써 보지 않았다면 간단한 컴포넌트부터 시작해 보세요. 버튼 컴포넌트나 입력 컴포넌트처럼 작은 것부터 Browser Mode를 설정하고, 설정이 올바르게 동작하는지 확인한 다음 복잡한 컴포넌트로 확장하면 됩니다. 시행착오는 분명 있겠지만, 그 과정을 지나 테스트 작성이 손에 익으면 개발 효율은 확실히 올라갑니다.