Vitest 설정

20.1.1. vitest.config.ts

프로젝트 루트에 vitest.config.ts 파일을 생성하고 아래 설정을 기본으로 사용합니다.

import { defineConfig } from 'vitest/config'
import vue from '@vitejs/plugin-vue'
import { resolve } from 'path'

export default defineConfig({
  plugins: [vue()],

  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'),
    },
  },

  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: ['./vitest.setup.ts'],
    include: ['src/**/*.{test,spec}.{ts,tsx}'],
    exclude: ['node_modules', 'dist', 'e2e'],
  },
})

• globals: true를 설정하면 describe, it, expect 등을 import 없이 사용할 수 있습니다.
• environment는 jsdom 또는 happy-dom 중 하나를 지정합니다.
• setupFiles에 전역 설정 파일 경로를 지정합니다.
• include 패턴은 *.test.ts 또는 *.spec.ts 파일만 대상으로 합니다.

---

20.1.2. 테스트 환경

jsdom과 happy-dom 중 프로젝트 요구사항에 맞는 환경을 선택합니다.

항목	jsdom	happy-dom
실행 속도	보통	빠름 (jsdom 대비 약 2~3배)
DOM 호환성	높음 (브라우저 표준에 근접)	보통 (일부 API 미지원)
커뮤니티 생태계	넓음	성장 중
권장 사용처	정밀한 DOM 검증이 필요한 경우	빠른 피드백이 필요한 경우

• DOM 이벤트 버블링, window.getComputedStyle 등 정밀한 브라우저 API 테스트가 필요하면 jsdom을 사용합니다.
• 단순 렌더링 검증 위주의 테스트는 happy-dom을 사용하여 실행 속도를 확보합니다.
• TQS 기준 기본값은 jsdom으로 지정합니다.

---

20.1.3. 설정 파일

vitest.setup.ts 파일에서 전역 목(mock) 설정과 테스트 유틸리티를 초기화합니다.

// vitest.setup.ts
import { config } from '@vue/test-utils'

// 전역 컴포넌트 스텁 설정
config.global.stubs = {
  RouterLink: true,
  RouterView: true,
}

// 전역 목 설정
vi.stubGlobal('matchMedia', vi.fn(() => ({
  matches: false,
  addListener: vi.fn(),
  removeListener: vi.fn(),
})))

// IntersectionObserver 목
vi.stubGlobal('IntersectionObserver', vi.fn(() => ({
  observe: vi.fn(),
  unobserve: vi.fn(),
  disconnect: vi.fn(),
})))

• @vue/test-utils의 config.global을 통해 모든 테스트에 공통으로 적용되는 플러그인, 스텁, 목을 설정합니다.
• 브라우저 전용 API(matchMedia, IntersectionObserver 등)는 전역 목으로 등록합니다.

---

20.1.4. 실행 명령

package.json의 scripts에 아래 명령을 등록합니다.

{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage",
    "test:ui": "vitest --ui"
  }
}

명령	설명
yarn test	전체 테스트를 1회 실행합니다
yarn test:watch	파일 변경 감지 시 관련 테스트를 자동 재실행합니다
yarn test:coverage	커버리지 리포트를 포함하여 테스트를 실행합니다
yarn test:ui	Vitest UI를 브라우저에서 실행합니다

• 개발 중에는 yarn test:watch를 상시 실행하여 빠른 피드백을 확보해야 합니다.
• CI 환경에서는 yarn test를 사용하여 단일 실행 후 종료합니다.
• 커버리지 측정은 yarn test:coverage로 수행하며, 상세 기준은 20.4절을 따릅니다.