vitest-testing-skills

name	vitest-testing-skills
description	Advanced guidelines and best practices for writing tests using Vitest. Apply this skill when generating, reviewing, or refactoring test codes to prevent common pitfalls and ensure high performance.

Vitest Testing Guidelines & Best Practices

이 프로젝트에서 Vitest를 사용하여 테스트 코드를 작성할 때 준수해야 할 핵심 지침입니다. AI는 테스트 코드를 생성하거나 수정할 때 이 규칙을 최우선으로 적용해야 합니다.

1. 테스트 기본 원칙 (Core Principles)

• AAA 패턴 준수: 모든 테스트는 Arrange(준비), Act(실행), Assert(검증) 단계를 시각적으로 명확히 분리하여 작성합니다.
• 행위 기반 검증 (Testing Behavior): 내부 변수명이나 구현 세부 사항을 테스트하지 마세요. 사용자 관점의 입력과 동작(출력)만 검증합니다.
• 파일 병치 (Colocation): 테스트 파일은 타겟 파일과 동일한 디렉토리에 위치시킵니다. (예: utils/math.ts -> utils/math.test.ts)

2. 모킹 및 격리 (Mocking & Isolation)

• 초기화: 테스트 간의 상태 오염을 막기 위해, describe 블록 내부의 beforeEach에서 vi.clearAllMocks()를 호출하세요.
• 호이스팅 주의 (Hoisting): vi.mock()은 파일 최상단으로 호이스팅됩니다. vi.mock 내부에서 외부 변수를 참조해야 할 경우 반드시 vi.hoisted()를 사용하여 변수도 함께 호이스팅되도록 처리하세요. 호이스팅을 원치 않는 동적 모킹 시에는 vi.doMock()을 사용합니다.
• 시간 제어 (Fake Timers): 시간에 의존하는 로직은 실제 시간을 기다리지 말고 vi.useFakeTimers()와 vi.advanceTimersByTime()을 사용하세요.

3. 타입 검증 (Type Testing)

• 런타임 테스트 분리: 복잡한 유틸리티 타입이나 제네릭(Generic)의 정확성을 검증해야 할 경우, 일반 런타임 테스트 파일이 아닌 *.test-d.ts 파일을 생성하세요.
• 타입 단언: Vitest의 expectTypeOf 또는 assertType API를 사용하여 정적 타입 추론이 올바르게 작동하는지 검증합니다.

4. UI 컴포넌트 테스트 (DOM & Browser)

• 접근성 중심 쿼리: @testing-library 사용 시 querySelector 등 DOM 구조에 의존하는 쿼리를 금지하고, getByRole, getByText 등 접근성 기반 쿼리를 사용하세요.
• 가상 DOM의 한계 인지: jsdom이나 happy-dom은 실제 브라우저가 아니므로 IntersectionObserver 등 실제 브라우저 API가 필요한 경우, 이를 명시적으로 모킹하거나 Browser Mode 환경을 고려한 코드를 작성해야 합니다.

5. 안티 패턴 (Strictly Avoid)

• 거대한 단일 테스트 (God Test): 하나의 it 블록에 여러 동작을 몰아넣지 말고, 하나의 논리적 동작만 검증하도록 쪼개세요.
• 무의미한 커버리지용 테스트: 커버리지 수치만을 위한 의미 없는 검증(expect(true).toBe(true))을 작성하지 마세요.