Vitest 입문 가이드: 처음 시작하는 프론트엔드 테스트 환경 구축과 기본 문법
안녕하세요 Lovefield입니다.
프론트엔드 개발을 진행하다 보면 서비스 규모가 커지면서 "이 코드를 수정했을 때 다른 페이지가 망가지지는 않을까?"라는 불안을 자주 겪게 됩니다. 이때 가장 확실한 안전망이 되어주는 것이 바로 자동화된 테스트 코드입니다.
그동안 프론트엔드 테스트 도구로는 Jest가 널리 쓰였지만, 최근 Vite와 TypeScript 기반 프로젝트에서는 설정이 훨씬 간편하고 속도가 빠른 Vitest가 표준처럼 자리 잡고 있습니다. 별도의 복잡한 변환 설정 없이 기존 vite.config.ts를 그대로 활용할 수 있어 처음 테스트를 도입하는 분들에게도 진입 장벽이 매우 낮습니다.
이번 글에서는 Vitest를 처음 접하는 분들을 위해 설치부터 가장 기본적인 테스트 코드 작성법, 그리고 Vue 3 환경에서의 기초 테스트 방법까지 차근차근 정리해 보려 합니다.
Vitest 설치 및 첫 설정하기
이미 Vite 기반 프로젝트(Vue, React, Vanilla TS 등)가 구성되어 있다면 Vitest 설치는 매우 간단합니다. 터미널에서 bun을 사용해 개발 의존성으로 설치합니다.
Shell
1
bun add -d vitestpackage.json 스크립트 추가
테스트를 손쉽게 실행할 수 있도록 package.json에 실행 명령어를 등록합니다.
JSON
1
2
3
4
5
6
{
"scripts": {
"test": "vitest",
"test:run": "vitest run"
}
}bun run test: 파일이 수정될 때마다 자동으로 관련 테스트를 다시 실행해 주는 Watch 모드로 실행됩니다. 개발할 때 켜두면 매우 편리합니다.
bun run test:run: 모든 테스트를 한 번만 실행하고 종료합니다. 주로 CI/CD 배포 파이프라인에서 사용합니다.
첫 번째 테스트 코드 작성하기 (기본 문법)
Vitest는 기본적으로 프로젝트 내의 .test.ts 또는 .spec.ts로 끝나는 파일을 자동으로 찾아 테스트를 실행합니다.
간단한 덧셈과 할인율 계산 함수를 만들고, 이를 검증하는 테스트 파일을 작성해 보겠습니다.
TypeScript
1
2
3
4
5
6
7
// utils/price.ts
export function calculateDiscount(price: number, discountRate: number): number {
if (discountRate < 0 || discountRate > 100) {
throw new Error('할인율은 0에서 100 사이여야 합니다.');
}
return price * (1 - discountRate / 100);
}이제 같은 폴더에 price.spec.ts 파일을 생성합니다.
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// utils/price.spec.ts
import { describe, it, expect } from 'vitest';
import { calculateDiscount } from './price';
// 1. describe: 관련된 테스트들을 하나의 그룹으로 묶어줍니다.
describe('calculateDiscount 함수 테스트', () => {
// 2. it (또는 test): 실제 검증할 개별 테스트 케이스를 정의합니다.
it('10,000원 상품에 20% 할인을 적용하면 8,000원이 반환된다', () => {
const result = calculateDiscount(10000, 20);
// 3. expect: 실제 결과값과 기대하는 값을 비교(Assertion)합니다.
expect(result).toBe(8000);
});
it('할인율이 0%인 경우 원래 가격을 그대로 반환한다', () => {
expect(calculateDiscount(5000, 0)).toBe(5000);
});
it('할인율이 100%를 초과하면 에러를 발생시킨다', () => {
// 에러 발생 여부를 검증할 때는 함수로 한 번 감싸서 전달합니다.
expect(() => calculateDiscount(10000, 120)).toThrow('할인율은 0에서 100 사이여야 합니다.');
});
});자주 사용하는 핵심 검증(Matcher) 문법
expect(a).toBe(b): 숫자, 문자열, 불리언 같은 원시값이 정확히 일치하는지 확인합니다 (===).
expect(objA).toEqual(objB): 객체나 배열의 내부 구조와 값이 똑같은지 깊은 비교(Deep Equality)를 수행합니다.
expect(val).toBeTruthy() / toBeFalsy(): 값이 참(true) 또는 거짓(false)으로 평가되는지 확인합니다.
expect(arr).toContain(item): 배열에 특정 요소가 포함되어 있는지 확인합니다.
함수 호출 감시와 가짜 데이터 만들기 (Mocking)
실무 코드를 테스트하다 보면 외부 API를 호출하거나 특정 콜백 함수가 제대로 실행되었는지 확인해야 할 때가 많습니다. 이때 실제 서버에 요청을 보내지 않고 가짜 함수를 만들어 동작을 흉내 내는 기법을 모킹(Mocking)이라고 합니다.
Vitest에서는 vi.fn()을 통해 손쉽게 가짜 함수를 만들 수 있습니다.
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// utils/logger.spec.ts
import { describe, it, expect, vi } from 'vitest';
function processOrder(amount: number, onSuccess: (msg: string) => void) {
if (amount > 0) {
onSuccess(`${amount}원 결제가 완료되었습니다.`);
}
}
describe('processOrder 콜백 모킹 테스트', () => {
it('결제 금액이 0원보다 크면 onSuccess 콜백이 1번 호출된다', () => {
// 가짜(Mock) 함수 생성
const mockCallback = vi.fn();
processOrder(15000, mockCallback);
// 콜백이 호출되었는지 횟수와 전달된 인자 검증
expect(mockCallback).toHaveBeenCalledTimes(1);
expect(mockCallback).toHaveBeenCalledWith('15000원 결제가 완료되었습니다.');
});
it('결제 금액이 0원 이하이면 콜백이 호출되지 않는다', () => {
const mockCallback = vi.fn();
processOrder(0, mockCallback);
expect(mockCallback).not.toHaveBeenCalled();
});
});Vue 3 프로젝트에서 테스트 시작하기
Vue 3 프로젝트에서는 크게 순수 상태 로직(Composables)과 화면 UI(Component) 두 가지 영역으로 나누어 테스트를 시작하는 것이 좋습니다.
Composable 로직 테스트하기
DOM 렌더링이 필요 없는 순수한 Vue 반응형 상태 함수(ref, computed)는 별도의 추가 라이브러리 없이 바로 테스트할 수 있습니다.
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
// composables/useCounter.ts
import { ref, computed } from 'vue';
export function useCounter(initialValue = 0) {
const count = ref(initialValue);
const doubleCount = computed(() => count.value * 2);
const increment = () => {
count.value++;
};
return { count, doubleCount, increment };
}TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// composables/useCounter.spec.ts
import { describe, it, expect } from 'vitest';
import { useCounter } from './useCounter';
describe('useCounter', () => {
it('increment를 호출하면 count와 doubleCount가 함께 증가한다', () => {
const { count, doubleCount, increment } = useCounter(1);
expect(count.value).toBe(1);
expect(doubleCount.value).toBe(2);
increment();
expect(count.value).toBe(2);
expect(doubleCount.value).toBe(4);
});
});Vue 컴포넌트 렌더링 및 클릭 이벤트 테스트하기
.vue 컴포넌트가 화면에 글자를 잘 렌더링하는지, 버튼을 클릭했을 때 반응하는지 테스트하려면 @vue/test-utils와 가상 DOM 환경인 jsdom 패키지를 추가로 설치합니다.
Shell
1
bun add -d @vue/test-utils jsdom설치 후 vite.config.ts에 environment: 'jsdom' 옵션을 추가합니다.
TypeScript
1
2
3
4
5
6
7
8
9
10
// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
export default defineConfig({
plugins: [vue()],
test: {
environment: 'jsdom',
},
});이제 간단한 버튼 컴포넌트를 마운트하여 사용자 클릭을 시뮬레이션해 보겠습니다.
Vue
1
2
3
4
5
6
7
8
9
10
<!-- components/LikeButton.vue -->
<script setup lang="ts">
import { ref } from 'vue';
const likes = ref(0);
</script>
<template>
<button @click="likes++">좋아요 {{ likes }}</button>
</template>TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// components/LikeButton.spec.ts
import { describe, it, expect } from 'vitest';
import { mount } from '@vue/test-utils';
import LikeButton from './LikeButton.vue';
describe('LikeButton.vue', () => {
it('버튼을 클릭할 때마다 좋아요 숫자가 1씩 증가한다', async () => {
// 컴포넌트를 가상 DOM에 마운트
const wrapper = mount(LikeButton);
// 초기 렌더링 텍스트 확인
expect(wrapper.text()).toContain('좋아요 0');
// 버튼 클릭 이벤트 발생 (DOM 업데이트 반영을 위해 await 사용)
await wrapper.find('button').trigger('click');
expect(wrapper.text()).toContain('좋아요 1');
});
});정리하며
처음부터 프로젝트의 모든 파일에 100% 테스트 코드를 작성하려고 하면 금방 지치기 쉽습니다. Vitest를 처음 도입하신다면 다음 순서로 작게 시작해 보시는 것을 추천합니다.
날짜 포맷팅, 금액 계산, 데이터 변환 같은 순수 유틸리티 함수부터 테스트 작성하기
핵심 비즈니스 로직이 담긴 Vue Composable의 상태 변화 검증하기
여러 페이지에서 공통으로 재사용되는 공통 UI 컴포넌트의 클릭 및 입력 동작 검증하기
작은 단위 테스트 하나씩 쌓아가다 보면, 코드를 리팩터링할 때 느끼는 막연한 두려움이 확실한 자신감으로 바뀌는 경험을 하실 수 있을 것입니다.
해당 글은 AI를 통해 제작되었습니다.

개발자의 AI 레버리지: LLM을 단순 코드 작성을 넘어 '진짜 기술 공부'에 활용하는 방법
AI에게 단순히 코드 작성을 맡기는 것을 넘어, 아키텍처 트레이드오프 분석, 공식 문서 해부, 트러블슈팅 시뮬레이션을 통해 엔지니어링 역량을 깊게 성장시키는 실전 AI 학습 워크플로우를 정리합니다.
ETC
