vitest-docs

Vitest 5

이 스킬은 https://vitest.dev/guide/ 에 문서화된 Vitest 5.x 를 다룹니다. 흔히 간과하기 쉬운 기본값, 함정, 비권장 API 및 문서에서 권장하는 패턴을 제공합니다. 참조 파일의 각 주장은 출처 페이지로 연결됩니다.

탐색 방법

1. 아래 빠른 규칙을 읽으세요. 가장 빈번한 실수를 잡아줍니다.
2. 작업에 해당하는 참조 파일 하나를 아래 표에서 열어보세요.
3. 코드가 Jest API 또는 Vitest 4 동작을 사용하는 경우, 먼저 references/migration.md 를 읽으세요.

빠른 시작

// vitest.config.ts
import { defineConfig } from 'vitest/config'
export default defineConfig({ test: { restoreMocks: true } })

// math.test.ts
import { expect, test } from 'vitest'

test.for([[1, 1, 2], [1, 2, 3]])('add(%i, %i) -> %i', ([a, b, expected]) => {
  expect(a + b).toBe(expected)
})

• Vite >= 6.4.0 및 Node.js >= 22.12.0 이 필요합니다. vite 는 피어 의존성입니다. https://vitest.dev/guide/migration
• 스크립트, CI 및 에이전트에서는 vitest run 을 사용하세요. vitest 만 실행하면 터미널에서 감시 모드가 시작됩니다. https://vitest.dev/guide/learn/writing-tests-with-ai
• .vitest/ 를 .gitignore 에 추가하세요. https://vitest.dev/guide

빠른 규칙

테스트 작성

• globals 는 꺼져 있습니다: test, expect, vi 는 vitest 에서 가져오세요. https://vitest.dev/config/globals
• 매개변수화는 test.each 대신 test.for 를 사용하세요. https://vitest.dev/guide/learn/writing-tests
• 설정 공유는 fixture 를 통해 수행하고 test.extend('name', fn) 을 사용하며 항상 분해 할당하세요. https://vitest.dev/guide/test-context
• beforeEach 에서 정리 함수를 반환하고 일치하는 afterEach 는 작성하지 마세요. https://vitest.dev/api/hooks
• done 콜백은 사용하지 마세요. 비동기 테스트를 사용하세요. https://vitest.dev/api/test
• 테스트는 실행 중에 타입을 검사하지 않습니다. tsc 또는 vitest --typecheck.enabled 를 실행하세요. https://vitest.dev/guide/learn/writing-tests , https://vitest.dev/guide/cli
• 동시 테스트에서는 컨텍스트에서 expect 를 사용하세요: async ({ expect }) => {}. https://vitest.dev/api/test

어서션

• 모든 .resolves, .rejects, expect.poll 및 toMatchFileSnapshot 에는 await 를 사용하세요. 그렇지 않으면 테스트가 실패합니다. https://vitest.dev/guide/migration
• 폴링은 expect.poll 또는 vi.waitFor 를 사용하고 setTimeout 을 이용한 지연은 절대 사용하지 마세요. https://vitest.dev/guide/recipes/wait-for
• expect.assert(x) 로 타입을 좁히세요. toBeDefined() 는 타입을 좁히지 않습니다. https://vitest.dev/guide/recipes/type-narrowing
• 스냅샷은 CI 에서 작성되지 않습니다. diff 를 확인한 후 vitest -u 로 업데이트하세요. https://vitest.dev/guide/snapshot

모킹

• 문자열보다 vi.mock(import('./x.js')) 를 선호하세요: 경로가 파일 이동을 따르고 팩토리가 타입 검사됩니다. https://vitest.dev/api/vi
• vi.mock 과 vi.hoisted 는 모듈 최상위에 유지하세요. 다른 곳에서는 오류가 발생합니다. https://vitest.dev/guide/migration
• 팩토리는 default 를 포함한 모든 내보내기를 반환합니다. https://vitest.dev/guide/migration/jest
• clearMocks 는 기본적으로 켜져 있습니다. 각 테스트 후 스파이를 복원하려면 restoreMocks: true 를 추가하세요. https://vitest.dev/config/clearmocks , https://vitest.dev/guide/learn/mock-functions
• 인수별 반환값: vi.when(fn).calledWith(1).thenReturn(x). https://vitest.dev/guide/recipes/conditional-mocking
• 클래스는 vi.fn(class { ... }) 로 모킹하세요. https://vitest.dev/guide/mocking/classes
• 자체 파일 내에서 호출되는 함수는 모킹할 수 없습니다. https://vitest.dev/guide/mocking/modules

설정 및 실행

• vitest.config.* 는 mergeConfig 로 병합하지 않는 한 vite.config.* 를 무시합니다. https://vitest.dev/config
• include, exclude 또는 reporters 를 설정하면 기본값을 대체합니다. configDefaults 를 펼쳐 사용하세요. https://vitest.dev/config/include
• 기본 환경은 node 입니다. jsdom 또는 happy-dom 은 직접 설치하세요. https://vitest.dev/guide/environment
• 기본 풀은 forks 입니다. 네이티브 모듈과 process.chdir 의 경우 유지하세요. https://vitest.dev/config/pool
• .only 는 CI 에서 실행을 실패시킵니다(allowOnly 참고). https://vitest.dev/api/test
• -t 는 ' > ' 로 결합된 전체 이름과 일치합니다. https://vitest.dev/guide/filtering

이전 패턴

이전	현재
jest.fn, jest.mock, jest.requireActual	vi.fn, vi.mock, await vi.importActual
test.each 행이 인수로 펼쳐짐	test.for 와 분해된 행 및 컨텍스트 사용
test.sequential, describe.sequential	{ concurrent: false }
import { bench } from 'vitest'	test() 내부의 bench fixture
test.scoped	test.override
workspace	test.projects
toMatchTypeOf	toExtend
테스트 또는 describe 내부의 vi.mock	최상위 vi.mock 또는 vi.doMock
자동 await 되는 await 없는 .resolves	await expect(p).resolves
toHaveTextContent(/regex/)	toMatchTextContent(/regex/)
stdout 의 vitest --reporter=json	.vitest/json/output.json 또는 stdout: true
vitest/environments, vitest/coverage	vitest/runtime, vitest/node

자세한 내용과 전체 목록: references/migration.md

참조 파일

파일	이 내용을 읽으세요
references/writing-tests.md	테스트 옵션, test.for, 동시성, fixture, 훅, 설정 파일, 전역 설정, 태그, 벤치마크, 인소스 테스트
references/assertions-and-snapshots.md	expect 함정, 비동기 어서션, 폴링, 타입 좁히기, 스키마 매칭, 사용자 정의 매처, 스냅샷, 타입 테스트
references/mocking.md	모크 정리, vi.fn, vi.spyOn, vi.mock, 클래스 모크, vi.when, 가짜 타이머, 전역, 환경, MSW, memfs
references/config-and-cli.md	설정 해석, include, globals, 환경, 풀, 프로젝트, CLI 필터, 감시, 리포터, 샤딩
references/coverage.md	v8 및 istanbul, coverage.include, 보고서, 임계값, 무시 힌트
references/debugging-and-performance.md	디버거 설정, 일반적인 오류, 의존성 인라인화, CommonJS, 프로파일링, 속도 향상, 격리 비활성화
references/browser-mode.md	브라우저 모드 설정, 인스턴스, Playwright 제공자, 로케이터, expect.element, userEvent, 컴포넌트 테스트, 시각적 및 ARIA 스냅샷
references/migration.md	Vitest 4에서 5로의 변경 사항 및 제거, Jest 및 Mocha 매핑, 업그레이드 위생

크롤링된 페이지: SOURCES.md