Vitest 4.0 출시: 테스트 도구의 새로운 시대를 열다

안녕하세요, 개발자 여러분! 오늘은 JavaScript 테스트 라이브러리 Vitest의 메이저 버전인 4.0이 출시된 소식을 전해드리려 합니다. 2025년 10월 22일에 공식 발표된 이 릴리스는 Vitest의 브라우저 모드를 안정화시키고, 시각 회귀 테스트, 스키마 검증 등 혁신적인 기능을 도입하며, 개발자 경험을 한층 업그레이드합니다. Vitest 코어에 기여한 640명 이상의 커뮤니티 멤버들에게 깊은 감사를 표하며, 이번 포스트에서 주요 업데이트를 자세히 살펴보겠습니다.

Vitest는 Vite의 빠른 빌드 시스템을 활용한 테스트 러너로, Jest와 유사한 API를 제공하면서도 더 가벼운 성능으로 사랑받고 있습니다. 만약 Vitest를 처음 사용한다면, Getting Started 가이드부터 시작해보세요. 이제 본격적으로 Vitest 4.0의 하이라이트를 탐구해 보죠!

브라우저 모드의 안정화: 더 이상 실험적이지 않다

Vitest 4.0의 가장 큰 뉴스는 브라우저 모드(Browser Mode) 가 안정 버전으로 전환된 점입니다. 이전에는 실험적 태그가 붙어 있었지만, 이제 완전한 프로덕션 레디 상태로 사용할 수 있어요. 이를 위해 브라우저 제공자(Provider)를 별도의 패키지로 분리했습니다:

• @vitest/browser-playwright: Playwright를 사용한 브라우저 테스트.
• @vitest/browser-webdriverio: WebdriverIO를 위한 옵션.
• @vitest/browser-preview: 미리보기 기능.

설정 예시는 간단합니다. 예를 들어, Playwright의 경우 vitest.config.ts에 다음과 같이 추가하세요:

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

export default defineConfig({
  test: {
    browser: {
      provider: browserProvider,
      launchOptions: { headless: true }
    }
  }
})

또한, page 컨텍스트는 이제 vitest/browser에서 직접 임포트할 수 있으며, 이전 버전과의 호환성을 위해 다음 메이저 릴리스까지는 기존 방식도 지원합니다. @vitest/browser 패키지는 더 이상 필요 없으니 제거하세요. 이 변화로 브라우저 테스트가 더 모듈화되고 유지보수하기 쉬워졌습니다.

시각 회귀 테스트와 새로운 매처: UI 테스트의 혁명

브라우저 모드에서 시각 회귀 테스트(Visual Regression Testing) 를 지원하는 toMatchScreenshot 어설션이 추가되었습니다. UI 컴포넌트나 페이지의 스크린샷을 참조 이미지와 비교해 변화점을 자동으로 감지할 수 있어요. 예시:

import { expect, test } from 'vitest'
import { toMatchScreenshot } from '@vitest/expect'

test('버튼 스크린샷 비교', async ({ page }) => {
  await page.goto('/button')
  await expect(page).toMatchScreenshot('button-state')
})

더불어, toBeInViewport 매처가 도입되어 IntersectionObserver API를 활용해 요소가 뷰포트 내에 있는지 확인할 수 있습니다. 부분 가시성을 위한 ratio 옵션(예: 0.5)도 지원하죠. 이 기능들은 E2E 테스트에서 UI 안정성을 크게 높여줄 거예요.

Playwright 트레이스와 로케이터 향상: 디버깅의 편의성 UP

Playwright 트레이스 지원이 추가되어 브라우저 테스트의 디버깅이 훨씬 수월해졌습니다. trace 옵션을 on, on-first-retry 등으로 설정하면 테스트 실패 시 트레이스 파일이 생성되며, HTML 리포터에서 직접 링크로 확인할 수 있어요. CLI 플래그 --browser.trace=on으로도 활성화 가능합니다. Playwright Trace Viewer로 상세 분석이 가능하니, 복잡한 브라우저 상호작용을 추적하는 데 딱입니다.

로케이터 측면에서는 Playwright 전용 page.frameLocator API가 새로 추가되어 iframe 요소를 쉽게 다룰 수 있습니다. 모든 로케이터에 length 속성이 노출되어 toHaveLength 매처와 결합할 수 있어요.

타입 인식 훅과 expect 확장: 타입스크립트 개발자를 위한 선물

test.extend로 확장된 라이프사이클 훅(예: beforeEach, afterEach)이 이제 타입 인식(Type-Aware)을 지원합니다. 반환된 test 객체에서 직접 컨텍스트 타입을 참조할 수 있어 타입 안전성이 강화됐습니다.

expect 객체에 Chai의 assert 메서드가 노출되어 타입 좁히기(Type Narrowing)가 용이해졌고, 새로운 expect.schemaMatching 매처는 Standard Schema v1 객체로 값을 검증합니다. Zod, Valibot, ArkType 같은 스키마 라이브러리와 잘 어울리며, 이메일 유효성 검사 등에 유용해요:

import { z } from 'zod'
import { expect, test } from 'vitest'

const emailSchema = z.string().email()

test('스키마 검증', () => {
  expect('user@example.com').toMatchSchema(emailSchema)
})

이 외에도 고급 공용 API 메서드가 추가되었으니, Vitest API 문서를 확인하세요.

리포터와 디버깅 개선: 일상 테스트가 더 스마트해지다

디버깅 측면에서 VSCode 확장 프로그램에 "Debug Test" 버튼이 브라우저 테스트를 위한 지원이 추가됐습니다. --inspect 플래그로 수동 디버깅 시 DevTools 연결이 자동화되며, trackUnhandledErrors가 비활성화되어 충돌을 방지합니다.

리포터 업데이트:

• basic 리포터 제거: 대신 default 리포터에 summary: false 옵션 사용.
• default 리포터: 단일 테스트 파일에서만 트리 형식 출력.
• 새 tree 리포터: 항상 트리 형식으로 테스트 출력.
• verbose 리포터: 이제 CI 외 환경에서도 테스트를 하나씩 출력 (이전 CI 전용 동작은 config로 조건부 적용).

주의할 점: Breaking Changes와 마이그레이션 가이드

Vitest 4.0은 브라우저 모드의 패키지 분리와 임포트 변경 등 몇 가지 breaking changes를 포함합니다. 전체 목록은 Changelog을 참조하세요. 업그레이드 전에 반드시 Migration Guide를 읽고, 브라우저 제공자 패키지 업데이트와 리포터 설정 조정을 확인하세요. 대부분의 경우 큰 이슈 없이 마이그레이션할 수 있지만, 안전을 위해 테스트를 먼저 실행해보는 걸 추천합니다.