설치, 설정, 첫 초록 테스트

"npm install 부터 첫 초록 체크까지 5분."

한 줄 설치

Vitest 는 runner 용 의존성 하나, 그 위에 얹을 DOM 에뮬레이터랑 Testing Library 헬퍼들. 전형적인 React + TypeScript 프로젝트라면 설치 명령은 한 줄.

--save-dev 플래그 (또는 -D) 는 다 devDependencies 로 넣어 — 이 패키지들은 프로덕션 번들로 안 가고, 가서도 안 돼.

최소 config

이미 vite.config.ts 가 있으면 Vitest 가 거기 test 필드를 바로 읽어 — 별도 config 파일 아예 필요 없을 수도 있어. 필요하면 (테스트 전용 환경, 빌드와 다른 alias) vitest.config.ts 옆에 둬.

첫날부터 값어치하는 두 필드:

environment: 컴포넌트 테스트는 'happy-dom', 순수 로직 테스트는 'node'. 섞어 쓰면 파일 상단에 // @vitest-environment node 로 파일별 지정.
globals: true 면 describe, it, expect 를 import 없이 전역으로 쓸 수 있어. 편의성 vs 명시성 — 팀 default 정하고 거기 충실해. 아래 코드는 globals off 하고 명시 import 야. 코드 리뷰에서 더 잘 읽혀서.

package.json 에 test 스크립트 추가해. 장기적으로 npx vitest run 보다 npm test 를 천 배 더 칠 거야. 한 번에 세팅: "test": "vitest", "test:run": "vitest run", "test:ui": "vitest --ui". CLI 의 두 글자 명령은 누적돼.

첫 테스트 파일

관례: 테스트 파일을 코드 옆에 두거나 (format.ts + format.test.ts) 평행한 __tests__/ 폴더에 둬. 옆에 두는 관례가 네비게이션 쉽고, 코드가 사라질 때 깔끔하게 같이 지워져. __tests__/ 관례는 monorepo 에서 격리가 더 좋아.

Vitest 는 default 로 *.{test,spec}.{ts,tsx,js,jsx} 매칭 파일을 발견해 — manifest 없고, opt-in 등록도 없어. 파일 떨궈 save 하면 watcher 가 다음 tick 에 잡아.

setupFiles — 손이 가는 유일한 hook

모든 테스트 파일 전에 코드 돌려야 할 때 — matcher 확장, polyfill, testing-library 설정 — 그게 setupFiles 야. 대부분 React 프로젝트는 하나 써: vitest.setup.ts 하나에서 @testing-library/jest-dom/vitest import 해서 toBeInTheDocument(), toHaveClass() 같은 matcher 를 노출시켜.

Config 는 시간이 지나면 작아져, 커지지 않아. 첫날 Vitest config 는 environment, setupFiles, 어쩌면 globals. config 가 30줄 넘게 자라면 왜인지 물어봐 — 보통 다른 도구가 이미 하는 plugin 이 유기적으로 자랐거나, 잘못된 레이어에서 기능 (coverage, UI 모드) 을 켰어.

Code

설치 — 한 줄, devDependencies·bash

# Vitest core + a fast DOM emulator + React Testing Library + matchers
npm install -D vitest happy-dom \
  @testing-library/react @testing-library/user-event @testing-library/jest-dom

# First sanity check — should print 'Vitest 4.x.x'
npx vitest --version

최소 Vitest config — happy-dom + setup 파일·typescript

// vitest.config.ts
import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'happy-dom',
    globals: false,                       // import describe/it/expect explicitly
    setupFiles: ['./vitest.setup.ts'],    // run before every test file
    css: true,                            // process CSS imports without crashing
    include: ['src/**/*.{test,spec}.{ts,tsx}'],
  },
});

vitest.setup.ts — testing-library matcher·typescript

// vitest.setup.ts
import '@testing-library/jest-dom/vitest';

// Add any global mocks or polyfills here, sparingly.
// Example — silence noisy 'not implemented' warnings from happy-dom:
// vi.spyOn(console, 'warn').mockImplementation(() => {});

첫 테스트 파일 — `npm test` 로 실행·typescript

// src/lib/format.test.ts
import { describe, it, expect } from 'vitest';
import { formatCurrency } from './format';

describe('formatCurrency', () => {
  it('formats whole numbers with a currency symbol', () => {
    expect(formatCurrency(1234, 'USD')).toBe('$1,234.00');
  });

  it('rounds to two decimals', () => {
    expect(formatCurrency(1.005, 'USD')).toBe('$1.01');
  });
});

Exercise

너 프로젝트에서 설치 명령 돌리고, vitest.config.ts 떨궈, 가장 작은 테스트 짜 — expect(1 + 1).toBe(2). npm test 돌려서 통과하는 거 봐. 그 다음 expect(1 + 1).toBe(3) 으로 바꿔서 터미널에서 실패가 어떻게 보이는지 봐. 색상, diff, 파일 포인터 — 그 실패 UX 가 네가 살게 될 곳이야.

Hint

npm test 가 아무것도 출력 안 하고 멈춰 있으면 watch 모드일 가능성 높아 (vitest 의 default). q 눌러서 종료하거나, 한 번만 돌리는 vitest run 써 — CI 에서 유용해.

설치, 설정, 첫 초록 테스트

한 줄 설치

최소 config

첫 테스트 파일

setupFiles — 손이 가는 유일한 hook

Code

External links

Exercise

Progress

댓글 0