[Vitest] 1편. Vitest 4로 Node.js 테스트 환경 구축하기

반응형

 

1편. Vitest 4로 Node.js 테스트 환경 구축하기

 

📚 목차
1. Vitest 개요와 실습 환경 이해
2. 프로젝트 기본 환경 구성
3. Vitest 설치 및 기본 설정
4. 첫 테스트 작성 및 실행

 

📂 [GitHub 예시 코드 보러가기] (https://github.com/cericube/nodejs-tutorials) /vitest

 

1. Vitest 개요와 실습 환경 이해

Vitest는 Vite 생태계를 중심으로 탄생한 차세대 테스트 러너입니다.

Vite는 Native ES Module(ESM)을 기반으로 매우 빠른 개발 경험을 제공하며, 초기에는 프론트엔드 중심 도구로 출발했지만 현재는 Node.js 백엔드 영역까지 빠르게 확장되고 있습니다.

 

🔷 Vitest의 핵심 특징

1. 빠른 실행 속도
Vite의 HMR(Hot Module Replacement) 기술을 활용하여, 수정된 파일만 즉시 반영되므로 테스트를 매우 빠르게 재실행할 수 있습니다.
2. Native ESM 지원
별도의 node_modules 설정을 복잡하게 조정할 필요 없이, 최신 자바스크립트(ESM) 문법을 그대로 사용할 수 있습니다.
3. Vite 기반 공유 설정
프로젝트의 빌드 설정(vite.config.ts)과 테스트 설정을 하나로 통합하여 관리할 수 있어, 설정 파편화와 유지보수 비용을 줄일 수 있습니다.
4. 강력한 호환성
Jest의 API(describe, it, expect)와 거의 100% 호환되기 때문에, 기존 테스트 코드의 마이그레이션이 매우 수월합니다.

 

🔷 Jest vs Vitest 비교표

Vitest는 특히 ESM 기반 Node.js 프로젝트에서 압도적인 개발 경험을 제공합니다.

항목	Jest	Vitest
핵심 엔진	자체 엔진 (CommonJS 기반)	Vite 기반 (Native ESM)
트랜스파일러	Babel 또는 ts-jest 별도 설정 필요	esbuild 내장
TypeScript 지원	추가 라이브러리 및 설정 필수	별도 설정 없이 기본 지원
설정 관리	jest.config.js 별도 관리	vite.config.ts와 통합
Watch 모드	프로젝트 규모 증가 시 반응 속도 저하	스마트 캐싱으로 빠른 실시간 반응
특화 기능	광범위한 레거시 생태계	브라우저 모드, UI 대시보드

트랜스파일러(Transpiler)란?
최신 문법으로 작성한 코드를, 실행 환경이 이해할 수 있는 코드로 변환해 주는 도구입니다.

 

🔷 실습 프로젝트 구조 이해

nodejs-tutorials/
├─ package.json
├─ tsconfig.json
├─ vitest.config.ts
├─ Vitest/
│  ├─ src/ch01/
│  └─ tests/ch01/
└─ prisma/
:

1. Vitest 폴더 분리

테스트 전용 코드와 실습 코드를 실제 서비스 코드와 명확히 분리하여 관리할 수 있어, 프로젝트 구조의 가독성과 유지보수성을 높일 수 있습니다.

2. 루트 프로젝트와 Vitest 서브 프로젝트 분리

루트 프로젝트와 테스트 전용 Vitest 서브 프로젝트를 분리하여 구성함으로써, 빌드 설정과 테스트 설정을 독립적으로 관리하고 환경 간 충돌을 최소화할 수 있습니다.

 

✔️ 실무 구조 예시

project-root/
├── src/
│   ├── utils/
│   │   ├── string.ts
│   │   └── math.ts
│   ├── services/
│   │   └── UserService.ts
│   └── api/
│       └── endpoints.ts
├── tests/
│   ├── unit/
│   │   ├── utils/
│   │   │   ├── string.test.ts
│   │   │   └── math.test.ts
│   │   └── services/
│   │       └── UserService.test.ts
│   ├── integration/
│   │   └── api/
│   │       └── endpoints.test.ts
│   ├── fixtures/
│   │   ├── users.json
│   │   └── mockData.ts
│   └── mocks/
│       ├── handlers.ts
│       └── server.ts
└── vitest.config.ts

▸ tests/unit/: 단일 함수나 클래스의 독립적인 기능 테스트

▸ tests/integration/: 여러 모듈이 협력하는 시나리오 테스트

▸ tests/fixtures/: 테스트 데이터 저장소

▸ tests/mocks/: Mock 서버, 핸들러 등 재사용 가능한 Mock 설정

 

2. 프로젝트 기본 환경 구성

참고: Node.js 개발환경 구축하기 : JavaScript, TypeScript, Vitest

Node.js 개발환경 구축하기 : JavaScript, TypeScript, Vitest

 

🔷 프로젝트 초기화(vitest)

# 1. vitest 이동
cd /nodejs-tutorals/vitest

# 2. 프로젝트 초기화: package.json
npm init -y

# 3. TypeScript 컴파일러 설정 파일 생성: tsconfig.json
npx tsc --init

# tsconfig.json 예시
{
  // 1. 루트의 공통 설정을 그대로 가져옵니다.
  "extends": "../tsconfig.json",

  "compilerOptions": {
    // 2. 이 프로젝트만의 소스 및 출력 경로 설정
    "rootDir": "./src", // 작성할 소스 코드 위치
    "outDir": "./dist" // 컴파일된 JS 파일이 저장될 위치
  },

  // 3. 실제 검사 및 컴파일 대상 지정
  "include": ["src/**/*", "src/shared"], // src 폴더 안의 모든 파일을 대상으로 함
  "exclude": ["node_modules", "dist"]
}

# package.json 예시
{
  "name": "vitest-study",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "vitest",
    "test:ui": "vitest --ui",
    "test:run": "vitest run"
  }
}

Vitest 서브 프로젝트는 루트 TypeScript 설정을 상속하면서도, 소스 경로와 빌드 경로를 독립적으로 관리하도록 구성합니다.

또한 package.json의 스크립트를 통해 개발용, UI 기반, CI 실행 환경을 명확히 분리하여 테스트 실행 목적에 따라 유연하게 사용할 수 있습니다.

반응형

 

3. Vitest 설치 및 기본 설정

Vitest는 Vite 설정 파일(vite.config.ts)을 그대로 활용하기 때문에, 별도의 복잡한 설정 없이도 빠르게 테스트 환경을 구성할 수 있습니다.

 

🔷 패키지 설치

cd nodejs-tutorials/vitest

npm install -D vitest @vitest/ui

# npm install -D supertest
# - Express / Fastify / Nest API 테스트 표준 도구
# npm install -D @vitest/coverage-v8
# - V8 기반 빠른 커버리지 측정

▸ vitest : 테스트 실행, 파일 감시(Watch), 모듈 로딩, Mocking, Assertion 등을 모두 담당하는 핵심 엔진
▸ @vitest/ui : @vitest/ui는 브라우저에서 테스트 상태를 시각적으로 확인하고 관리할 수 있는 UI 대시보드

 

🔷 vite.config.ts 작성

프로젝트 루트에 vite.config.ts 파일을 생성합니다.
Vitest는 해당 설정 파일을 자동으로 인식하여 테스트 환경을 구성합니다.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    // describe, it, expect 등을 import 없이 전역으로 사용
    globals: true,

    // 테스트가 실행되는 런타임 환경을 지정합니다.
    environment: 'node',
    
    // Vitest가 테스트 파일을 탐색할 경로 패턴을 지정합니다.
    include: ['tests/**/*.test.ts'],
  },
});

 

📌 global : true 사용 시 주의 사항

TypeScript를 사용하는 경우, 타입 인식이 되지 않을 수 있으므로 tsconfig.json의 types 항목에 다음을 추가하는 것을 권장합니다.

{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

 

✔️ 실무 설정 예시

// vitest.config.ts
import { defineConfig } from 'vitest/config';
import path from 'path';

export default defineConfig({
  test: {
    // describe, it, expect 등을 import 없이 전역으로 사용
    globals: true,

    // 테스트 실행 환경 (Node.js 런타임)
    environment: 'node',

    // 코드 커버리지 설정
    coverage: {
      provider: 'v8',                      // V8 엔진 기반 커버리지 수집 (빠름)
      reporter: ['text', 'json', 'html'],  // 콘솔, JSON 파일, HTML 리포트 생성
      exclude: ['tests/**', '**/*.test.ts'] // 테스트 코드 자체는 커버리지에서 제외
    },

    // 테스트 파일 탐색 패턴
    // tests 폴더 아래의 *.test.ts 파일만 실행
    include: ['tests/**/*.test.ts'],

    // import 경로 별칭 설정
    alias: {
      '@': path.resolve(__dirname, './src'),       // @/xxx → src/xxx
      '@tests': path.resolve(__dirname, './tests') // @tests/xxx → tests/xxx
    }
  }
});

 

 

4. 첫 테스트 작성 및 실행

🔷 TypeScript 소스 코드 작성 방법

1) 소스 코드 작성 (src/ch01/math.ts)

// src/ch01/math.ts
export const add = (a: number, b: number) => a + b;

 

2) 테스트 코드 작성 (tests/ch01/math.test.ts)

// tests/ch01/math.test.ts
import { describe, it, expect } from 'vitest';
import { add } from '../../src/ch01/math';

describe('Math Service', () => {
  it('1 더하기 2는 3이어야 한다', () => {
    const result = add(1, 2);
    expect(result).toBe(3);
  });
});

▸ describe - 여러 개의 테스트를 하나의 그룹으로 묶는 역할을 합니다.
▸ it - 하나의 테스트 케이스를 정의합니다.

▸ expect - 실행 결과가 기대한 값과 일치하는지 검증합니다.

 

🔷테스트 실행(CLI 모드 / UI 모드)

npm run 계열 명령은
자동으로 node_modules/.bin 폴더를 PATH에 추가해서 실행합니다.
따라서 Terminal에서 직접 vitest 입력하면 안되고 반드시 npm script를 통해 실행해야 합니다.

 

1) CLI 모드 실행

# package.json의 npm scripts를 실행 합니다.(권장)
npm test

# npx가 임시로 node_modules/.bin에서 실행 파일을 찾아 실행합니다
# npx vitest

▸ 기본적으로 Watch 모드로 실행됩니다.

▸ ./tests 폴더에 있는 모들 테스트 파일을 자동으로 찾아서 실행합니다.
▸ 소스 코드나 테스트 파일을 수정하면 자동으로 테스트가 다시 실행됩니다.
▸ 빠른 피드백 루프를 만들기에 매우 편리합니다.

vitest CLI 모드 실행 화면

 

✔️ 특정 파일만 테스트 하고 싶을때

npm test tests/ch01/math.test.ts

 

2) UI 모드 실행

브라우저 기반 대시보드로 테스트 결과를 확인할 수도 있습니다.

# package.json의 npm scripts를 실행 합니다.(권장)
npm run test:ui

# npx가 임시로 node_modules/.bin에서 실행 파일을 찾아 실행합니다
# npx vitest --ui

▸ 브라우저가 자동으로 열리며 테스트 현황을 시각적으로 확인할 수 있습니다.
▸ 테스트 성공/실패, 실행 시간, 파일 구조, 의존성 그래프 등을 한눈에 볼 수 있습니다.
▸ 테스트 규모가 커질수록 전체 구조를 파악하는 데 큰 도움이 됩니다.

vitest UI 모드 화면 예시

 

---

※ 게시된 글 및 이미지 중 일부는 AI 도구의 도움을 받아 생성되거나 다듬어졌습니다.

반응형