Vitest, Jest, 단위 테스트, Vite 마이그레이션 | 기존 설정을 언제 옮길까?

결론부터 조건으로 쓰면 이렇다.

“어느 쪽이 더 좋다”가 아니라 지금 쓰는 번들러와 얼마나 같은 파이프라인을 타느냐가 1순위다. Vite 앱에 Jest를 억지로 붙이면 babel-jest, 경로 별칭, CSS 모듈 mock을 이중으로 관리하게 된다.

공식 문서 기준으로 자주 묻는 항목만 압축했다. 벤치마크 수치는 저장소·파일 수·모킹 밀도에 따라 달라지므로, 여기서는 구조적 차이 위주로 적는다.

속도 체감은 “콜드 스타트 + 워치 재실행”에서 Vitest 쪽이 유리한 경우가 많다. 반대로 이미 수천 개 스펙이 Jest 플러그인에 묶여 있으면 이전 도중 깨지는 mock·트랜스폼이 더 비싸다. 숫자 한 방의 벤치보다 팀의 실패 비용이 먼저다.

Vite 프로젝트에 Vitest를 붙일 때는 보통 패키지 설치 후 vite.config.ts에 test 필드를 추가한다. 경로 별칭(@/)이 앱과 테스트에서 같아져서 “테스트만 경로가 안 된다” 류의 장애가 줄어든다.

Jest 쪽은 앱이 Vite여도 moduleNameMapper, transform, testEnvironment를 따로 맞춘다. CSS·SVG import mock, TypeScript 경로, ESM 지원 여부를 각각 손봐야 한다. Vite와 Webpack 비교에서 보듯 번들러가 갈리면 테스트 변환 파이프라인도 갈린다.

실무에서 자주 쓰는 최소 골격만 적으면 다음과 같다. (명령·옵션은 공식 문서 기준으로 프로젝트에 맞게 조정한다.)

둘 다 동작한다. 차이는 “앱 설정과 테스트 설정이 같은 파일을 보느냐”다. 프론트 팀이 Vite 플러그인을 자주 바꾸면 Vitest가 유지보수 면에서 유리하고, 백엔드·모바일·여러 패키지가 Jest 전역 설정 하나로 묶여 있으면 분리 설정의 이점이 작아진다.

Vitest는 Jest 호환을 목표로 설계됐다. describe, it, expect, vi.fn 대 jest.fn 같은 대응표가 공식 마이그레이션 가이드에 있다. 그래도 이전 시 자주 깨지는 지점은 고정돼 있다.

• jest.* 전역: Vitest는 vi 네임스페이스를 권장한다. 호환 모드로 넘길 수 있지만 플러그인·타입이 꼬이면 여기서 먼저 터진다.
• 수동 mock 경로: __mocks__ 규칙과 자동 mock 동작이 100% 같지 않을 수 있다. 네트워크·스토리지 mock이 많은 코드베이스일수록 한 파일씩 확인한다.
• 타이머: fake timers API 이름·기본값이 버전마다 미묘히 다르다. 애니메이션·디바운스 테스트는 이전 직후 우선 실행한다.
• 트랜스폼 특수 케이스: GraphQL 문서 로더, raw 파일 import, WASM 등은 Jest 쪽에 커스텀 transformer가 남아 있는 경우가 많다.

마이그레이션 순서는 보통 순수 유틸 → 훅 → 컴포넌트 → 네트워크 mock 의존 스펙이다. 한 번에 전 레포를 바꾸기보다 패키지 단위로 vitest 스크립트를 병행 실행하는 편이 안전하다. 단위 테스트 패턴 자체는 Vitest React 튜토리얼과 같은 구조를 쓰면 팀 내 문서 비용을 줄일 수 있다.

로컬에서 저장할 때마다 테스트가 2~3초 안에 돌아오면 개발 루프가 바뀐다. Vitest의 워치·스레드 풀은 이 구간을 노린다. CI에서는 이야기가 조금 다르다.

CI는 콜드 캐시, 의존성 설치, 병렬 잡 수, 샤딩 전략이 총시간을 좌우한다. Jest도 --maxWorkers와 캐시 디렉터리로 충분히 빠르게 만들 수 있다. 따라서 “CI가 느려서 Vitest로 간다”는 이유만으로는 약하다. 더 설득력 있는 이유는 다음이다.

• 로컬·CI가 같은 Vite 플러그인 세트를 쓰게 만들어 환경 차이를 줄인다.
• 모노레포에서 패키지별 Vite 라이브러리 빌드와 테스트 설정을 공유한다.
• 타입스크립트·JSX 변환을 이중 유지보수하지 않는다.

깃허브 액션 기준으로는 캐시 키에 lockfile과 node_modules뿐 아니라 테스트 캐시 경로를 넣을지 먼저 정한다. Vitest·Jest 모두 캐시 무효화가 잦으면 속도 이점이 사라진다. 실패 로그를 슬랙으로 보내는 팀이면 러너 교체 주간에 알림 노이즈가 늘 수 있으니, 브랜치 보호 규칙에 “테스트 잡 이름 변경”을 미리 반영한다.

유행 때문에 옮기다가 이틀을 설정에 쓰는 팀도 있다. 아래면 Jest 유지가 합리적이다.

반대로 신규 Vite 앱, 그린필드 디자인 시스템, 스토리북과 단위 테스트를 같이 키우는 패키지는 Vitest를 기본값으로 두는 팀이 늘었다. 선택 기준 문서를 위키 한 페이지로 남겨 두면 “왜 우리만 Jest냐” 논쟁을 반복하지 않는다.

Vite 앱 하나를 Jest에서 Vitest로 옮길 때 쓰는 최소 순서다. 규모가 크면 패키지 단위로 잘라 같은 순서를 반복한다.

1. 의존성 추가: vitest, 환경에 맞게 jsdom 또는 happy-dom, 리액트면 Testing Library 유지.
2. 설정 이전: jest.config의 testMatch·setup·alias를 vite test 블록으로 옮긴다.
3. 스크립트 병행: test:jest와 test:vitest를 잠시 공존시킨다. 한 번에 package.json의 test를 바꾸지 않는다.
4. API 치환: jest.fn → vi.fn, jest.mock → vi.mock. 자동 codemod가 있으면 1차 적용 후 수동 수정.
5. 깨진 스펙만 격리: 타이머·ESM·CSS 모듈 실패 파일을 이슈로 끊고, 통과 파일부터 CI 잡에 넣는다.
6. 커버리지·스냅샷 경로 확인: 리포트 업로드 경로와 스냅샷 업데이트 PR 규칙을 팀에 공지한다.
7. Jest 제거: 전 스펙 통과·CI 7일 안정 후 jest 관련 패키지와 설정을 삭제한다.

한글 주석·에러 메시지 정책이 있는 팀이면 expect 실패 메시지 스냅샷에 한글이 섞여 있는지 한 번 더 본다. 인코딩 이슈는 드물지만, Windows·macOS 혼합 환경에서 줄바꿈 스냅샷이 갈리는 문제는 여전하다. 가능하면 스냅샷보다 명시적 assertion 비중을 높이는 편이 리뷰가 가볍다.

E2E는 이 과정에서 건드리지 않는 것이 좋다. 단위 러너를 바꾸는 주에 플레이라이트 설정을 같이 건드리면 원인 분리가 안 된다. E2E는 기존 가이드 흐름을 유지하고, 단위만 교체한다.

1인·소규모 제품. Vite + React(또는 Vue)로 시작한다면 Vitest를 기본으로 둔다. 설정 파일이 하나 줄고, 로컬 피드백이 빨라 혼자 유지보수할 때 이득이 크다. 패키지 매니저는 팀 표준을 따르면 되고, 테스트 러너와는 독립이다.

시리즈 A 전후 스타트업. 이미 Jest 800개 이상이면 “전부 이전”보다 신규 패키지만 Vitest가 현실적이다. 디자인 시스템·유틸 패키지부터 옮기고 앱 본체는 출시 이후 창에 옮긴다. 채용 공고에 “Jest 필수”가 박혀 있어도 Vitest 경험은 대부분 바로 전이된다.

레거시 Webpack 모노레포. 번들러 이전 로드맵이 없다면 Jest 유지가 맞다. 번들러를 Vite로 옮기는 분기와 테스트 러너 교체를 같은 분기에 넣지 마라. 장애 원인 추적이 불가능에 가까워진다.

백엔드 Node 서비스. 프레임워크가 Fastify·Hono 등이어도 단위 테스트는 둘 다 가능하다. 프론트와 모노레포를 공유하면 Vitest로 맞추고, 백엔드만 별도 레포면 팀 익숙한 쪽을 고르면 된다. “백엔드라서 무조건 Jest” 규칙은 2026년 기준으로는 약하다.

• Vitest 공식 문서 — 설정, 환경, 브라우저 모드
• Vitest 마이그레이션 가이드 (Jest 등) — API 대응표
• Jest 공식 Getting Started — 설정·환경·매처
• Vite 가이드 — 플러그인·별칭이 테스트와 공유되는 이유

관련 내부 글: Vitest React 단위 테스트 튜토리얼, 플레이라이트 E2E 가이드, Vite vs Webpack 비교.