Vitest API

Vitest 인스턴스는 현재 테스트 모드를 필요로 합니다. 모드는 다음 중 하나입니다:

런타임 테스트 실행 시 test
벤치마크 실행 시 benchmark 실험적

Vitest 3의 새로운 기능

Vitest 3은 공개 API 안정화에 더욱 가까워졌습니다. 이를 위해 Vitest 클래스에서 이전에 공개되었던 일부 메서드를 더 이상 사용하지 않도록 하고 제거했습니다. 다음 API는 비공개로 변경되었습니다:

configOverride (setGlobalTestNamePattern 또는 enableSnapshotUpdate 사용)
coverageProvider
filenamePattern
runningPromise
closingPromise
isCancelling
coreWorkspaceProject
resolvedProjects
_browserLastPort
_options
reporters
vitenode
runner
pool
setServer
_initBrowserServers
rerunTask
changeProjectName
changeNamePattern
changeFilenamePattern
rerunFailed
_createRootProject (_ensureRootProject로 이름 변경되었지만 여전히 비공개)
filterTestsBySource (새로운 내부 vitest.specifications 인스턴스로 이동됨)
runFiles (대신 runTestSpecifications 사용)
onAfterSetServer

다음 API는 더 이상 사용되지 않습니다:

invalidates
changedTests (대신 onFilterWatchedSpecification 사용)
server (대신 vite 사용)
getProjectsByTestFile (대신 getModuleSpecifications 사용)
getFileWorkspaceSpecs (대신 getModuleSpecifications 사용)
getModuleProjects (this.projects로 직접 필터링)
updateLastChanged (invalidateFile로 이름 변경)
globTestSpecs (대신 globTestSpecifications 사용)
globTestFiles (대신 globTestSpecifications 사용)
listFile (대신 getRelevantTestSpecifications 사용)

mode

test

테스트 모드는 test 또는 it 내부의 함수만 호출하며, bench를 만나면 오류를 발생시킵니다. 이 모드는 구성의 include 및 exclude 옵션을 사용하여 테스트 파일을 찾습니다.

benchmark 실험적

벤치마크 모드는 bench 함수를 호출하며, test 또는 it를 만나면 오류를 발생시킵니다. 이 모드는 구성의 benchmark.include 및 benchmark.exclude 옵션을 사용하여 벤치마크 파일을 찾습니다.

config

루트(또는 전역) 구성입니다. 프로젝트가 정의되면, 이 구성은 globalConfig로 참조됩니다.

WARNING

이것은 Vitest 구성이며, Vite 구성을 확장하지 않습니다. test 속성에서 결정된 값만 포함합니다.

vite

이것은 전역 ViteDevServer입니다.

state 실험적

WARNING

공개 state는 실험적인 API입니다 (vitest.state.getReportedEntity 제외). 호환성을 깨뜨리는 변경 사항이 SemVer를 따르지 않을 수 있으니, 사용할 때 Vitest 버전을 고정하십시오.

전역 상태는 현재 테스트에 대한 정보를 저장합니다. 기본적으로 @vitest/runner의 API를 사용하지만, state.getReportedEntity()를 호출하여 보고된 작업 API를 사용하는 것을 권장합니다:

const task = vitest.state.idMap.get(taskId); // old API
const testCase = vitest.state.getReportedEntity(task); // new API

향후에는 이전 API가 더 이상 제공되지 않을 것입니다.

snapshot

전역 스냅샷 관리자입니다. Vitest는 snapshot.add 메서드를 사용하여 모든 스냅샷을 관리합니다.

vitest.snapshot.summary 속성을 통해 최신 스냅샷 요약을 얻을 수 있습니다.

cache

최신 테스트 결과와 테스트 파일 통계를 저장하는 캐시 관리자입니다. Vitest에서는 기본 시퀀서가 테스트를 정렬하는 데만 사용됩니다.

projects

사용자 프로젝트에 속하는 테스트 프로젝트 배열입니다. 사용자가 프로젝트를 지정하지 않으면, 이 배열에는 루트 프로젝트만 포함됩니다.

Vitest는 이 배열에 항상 하나 이상의 프로젝트가 있도록 보장합니다. 사용자가 존재하지 않는 --project 이름을 지정하면, Vitest는 이 배열이 정의되기 전에 오류를 발생시킵니다.

getRootProject

function getRootProject(): TestProject;

이것은 루트 테스트 프로젝트를 반환합니다. 루트 프로젝트는 일반적으로 어떤 테스트도 실행하지 않으며, 사용자가 구성에 루트 구성을 명시적으로 포함하거나 프로젝트가 전혀 정의되지 않은 경우가 아니라면 vitest.projects에 포함되지 않습니다.

루트 프로젝트의 주요 목표는 전역 구성을 설정하는 것입니다. 실제로 rootProject.config는 rootProject.globalConfig와 vitest.config를 직접 참조합니다:

(rootProject.config === rootProject.globalConfig) === rootProject.vitest.config;

provide

function provide<T extends keyof ProvidedContext & string>(
  key: T,
  value: ProvidedContext[T]
): void;

Vitest는 vitest.getRootProject().provide의 축약형인 provide 메서드를 제공합니다. 이 메서드를 사용하여 메인 스레드에서 테스트로 값을 전달할 수 있습니다. 모든 값은 저장되기 전에 structuredClone으로 검사되지만, 값 자체는 복제되지 않습니다.

테스트에서 값을 받으려면 vitest 엔트리포인트에서 inject 메서드를 가져와야 합니다:

import { inject } from 'vitest';
const port = inject('wsPort'); // 3000

더 나은 타입 안전성을 위해 ProvidedContext의 타입을 확장하는 것을 권장합니다:

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test', {
  watch: false,
});
vitest.provide('wsPort', 3000);

declare module 'vitest' {
  export interface ProvidedContext {
    wsPort: number;
  }
}

WARNING

기술적으로 provide는 TestProject의 메서드이므로 특정 프로젝트에 한정됩니다. 그러나 모든 프로젝트는 루트 프로젝트의 값을 상속하므로 vitest.provide는 테스트에 값을 전달하는 보편적인 방법입니다.

getProvidedContext

function getProvidedContext(): ProvidedContext;

이것은 루트 컨텍스트 객체를 반환합니다. vitest.getRootProject().getProvidedContext의 축약형입니다.

getProjectByName

function getProjectByName(name: string): TestProject;

이 메서드는 이름으로 프로젝트를 반환합니다. vitest.projects.find를 호출하는 것과 유사합니다.

WARNING

프로젝트가 존재하지 않는 경우, 이 메서드는 루트 프로젝트를 반환합니다. 반환된 프로젝트가 찾고 있는 프로젝트인지 다시 확인하십시오.

사용자가 이름을 사용자 정의하지 않으면, Vitest는 빈 문자열을 이름으로 할당합니다.

globTestSpecifications

function globTestSpecifications(
  filters?: string[]
): Promise<TestSpecification[]>;

이 메서드는 project.globTestFiles를 사용하여 모든 프로젝트의 모든 테스트를 수집하여 새로운 테스트 사양을 구성합니다. 테스트 파일과 일치하는 문자열 필터를 허용하며, 이 필터는 CLI가 지원하는 필터와 동일합니다.

이 메서드는 모든 테스트 사양을 자동으로 캐시합니다. 다음에 getModuleSpecifications를 호출할 때, 이전에 clearSpecificationsCache가 호출되지 않았다면 동일한 사양을 반환합니다.

WARNING

Vitest 3부터 poolMatchGlob에 여러 풀이 있거나 typecheck가 활성화된 경우 동일한 모듈 ID(파일 경로)를 가진 여러 테스트 사양이 존재할 수 있습니다. 이 기능은 Vitest 4에서 제거될 예정입니다.

const specifications = await vitest.globTestSpecifications(['my-filter']);
// [TestSpecification{ moduleId: '/tests/my-filter.test.ts' }]
console.log(specifications);

getRelevantTestSpecifications

function getRelevantTestSpecifications(
  filters?: string[]
): Promise<TestSpecification[]>;

이 메서드는 project.globTestFiles를 호출하여 모든 테스트 사양을 확인합니다. 테스트 파일과 일치하는 문자열 필터를 허용하며, 이 필터는 CLI가 지원하는 필터와 동일합니다. --changed 플래그가 지정된 경우, 목록은 변경된 파일만 포함하도록 필터링됩니다. getRelevantTestSpecifications는 어떤 테스트 파일도 실행하지 않습니다.

WARNING

이 메서드는 --changed 플래그를 필터링해야 하므로 느릴 수 있습니다. 단순히 테스트 파일 목록이 필요한 경우에는 사용하지 마십시오.

알려진 테스트 파일에 대한 사양 목록을 얻어야 하는 경우, 대신 getModuleSpecifications를 사용하십시오.
가능한 모든 테스트 파일 목록을 얻어야 하는 경우, globTestSpecifications를 사용하십시오.

mergeReports

function mergeReports(directory?: string): Promise<TestRunResult>;

지정된 디렉토리(지정되지 않은 경우 --merge-reports의 값)에 있는 여러 실행의 보고서를 병합합니다. 이 값은 config.mergeReports에도 설정할 수 있습니다 (기본적으로 .vitest-reports 폴더를 읽습니다).

directory는 항상 작업 디렉토리에 상대적으로 해석됩니다.

이 메서드는 config.mergeReports가 설정된 경우 startVitest에 의해 자동으로 호출됩니다.

collect

function collect(filters?: string[]): Promise<TestRunResult>;

테스트 콜백을 실행하지 않고 테스트 파일을 실행합니다. collect는 처리되지 않은 오류와 테스트 모듈 배열을 반환합니다. 테스트 파일과 일치하는 문자열 필터를 허용하며, 이 필터는 CLI가 지원하는 필터와 동일합니다.

이 메서드는 구성의 include, exclude, includeSource 값을 기반으로 테스트 사양을 확인합니다. 자세한 내용은 project.globTestFiles를 참조하십시오. --changed 플래그가 지정된 경우, 목록은 변경된 파일만 포함하도록 필터링됩니다.

WARNING

Vitest는 테스트를 수집하기 위해 정적 분석을 사용하지 않습니다. Vitest는 일반 테스트를 실행하는 것처럼 각 테스트 파일을 격리하여 실행합니다.

따라서 테스트를 수집하기 전에 격리를 비활성화하지 않으면 이 메서드가 매우 느려집니다.

start

function start(filters?: string[]): Promise<TestRunResult>;

리포터, 커버리지 제공자를 초기화하고 테스트를 실행합니다. 이 메서드는 테스트 파일과 일치하는 문자열 필터를 허용하며, 이 필터는 CLI가 지원하는 필터와 동일합니다.

WARNING

vitest.init()도 호출되는 경우 이 메서드를 호출해서는 안 됩니다. Vitest가 초기화된 후 테스트를 실행해야 하는 경우, 대신 runTestSpecifications 또는 rerunTestSpecifications를 사용하십시오.

이 메서드는 config.mergeReports 및 config.standalone가 설정되지 않은 경우 startVitest에 의해 자동으로 호출됩니다.

init

function init(): Promise<void>;

리포터와 커버리지 제공자를 초기화합니다. 이 메서드는 어떤 테스트도 실행하지 않습니다. --watch 플래그가 지정되면, 이 메서드가 호출되지 않아도 Vitest는 변경된 테스트를 계속 실행합니다.

내부적으로 이 메서드는 --standalone 플래그가 활성화된 경우에만 호출됩니다.

WARNING

vitest.start()도 호출되는 경우 이 메서드를 호출해서는 안 됩니다.

이 메서드는 config.standalone가 설정된 경우 startVitest에 의해 자동으로 호출됩니다.

getModuleSpecifications

function getModuleSpecifications(moduleId: string): TestSpecification[];

모듈 ID와 관련된 테스트 사양 목록을 반환합니다. ID는 이미 절대 파일 경로로 확인되어야 합니다. ID가 include 또는 includeSource 패턴과 일치하지 않으면 반환된 배열은 비어 있습니다.

이 메서드는 moduleId 및 pool을 기반으로 이미 캐시된 사양을 반환할 수 있습니다. 그러나 project.createSpecification는 항상 새 인스턴스를 반환하며 자동으로 캐시되지 않습니다. 하지만 사양은 runTestSpecifications가 호출될 때 자동으로 캐시됩니다.

WARNING

Vitest 3부터 이 메서드는 파일이 테스트인지 확인하기 위해 캐시를 사용합니다. 캐시가 비어 있지 않은지 확인하려면 globTestSpecifications를 한 번 이상 호출하십시오.

clearSpecificationsCache

function clearSpecificationsCache(moduleId?: string): void;

Vitest는 globTestSpecifications 또는 runTestSpecifications가 호출될 때 각 파일에 대한 테스트 사양을 자동으로 캐시합니다. 이 메서드는 첫 번째 인수에 따라 주어진 파일 또는 전체 캐시를 지웁니다.

runTestSpecifications

function runTestSpecifications(
  specifications: TestSpecification[],
  allTestsRun = false
): Promise<TestRunResult>;

이 메서드는 받은 사양을 기반으로 모든 테스트를 실행합니다. 두 번째 인수 allTestsRun은 커버리지 제공자가 루트의 모든 파일에 커버리지를 계측해야 하는지 여부를 결정하는 데 사용됩니다 (커버리지가 활성화되고 coverage.all이 true로 설정된 경우에만 중요합니다).

WARNING

이 메서드는 onWatcherRerun, onWatcherStart, onTestsRerun 콜백을 트리거하지 않습니다. 파일 변경을 기반으로 테스트를 다시 실행하는 경우, 대신 rerunTestSpecifications를 사용하는 것을 고려하십시오.

rerunTestSpecifications

function rerunTestSpecifications(
  specifications: TestSpecification[],
  allTestsRun = false
): Promise<TestRunResult>;

이 메서드는 reporter.onWatcherRerun 및 onTestsRerun 이벤트를 트리거한 후, runTestSpecifications로 테스트를 실행합니다. 메인 프로세스에 오류가 없으면 reporter.onWatcherStart 이벤트를 발생시킵니다.

updateSnapshot

function updateSnapshot(files?: string[]): Promise<TestRunResult>;

지정된 파일의 스냅샷을 업데이트합니다. 파일이 제공되지 않으면, 실패한 테스트와 오래된 스냅샷이 있는 파일을 업데이트합니다.

collectTests

function collectTests(
  specifications: TestSpecification[]
): Promise<TestRunResult>;

테스트 콜백을 실행하지 않고 테스트 파일을 실행합니다. collectTests는 처리되지 않은 오류와 테스트 모듈 배열을 반환합니다.

이 메서드는 collect와 완전히 동일하게 작동하지만, 테스트 사양을 직접 제공해야 합니다.

WARNING

Vitest는 테스트를 수집하기 위해 정적 분석을 사용하지 않습니다. Vitest는 일반 테스트를 실행하는 것처럼 각 테스트 파일을 격리하여 실행합니다.

따라서 테스트를 수집하기 전에 격리를 비활성화하지 않으면 이 메서드가 매우 느려집니다.

cancelCurrentRun

function cancelCurrentRun(reason: CancelReason): Promise<void>;

이 메서드는 진행 중인 모든 테스트를 정상적으로 중단합니다. 시작된 테스트가 완료될 때까지 기다리며, 실행 예정이었지만 아직 시작되지 않은 테스트는 실행하지 않습니다.

setGlobalTestNamePattern

function setGlobalTestNamePattern(pattern: string | RegExp): void;

이 메서드는 전역 테스트 이름 패턴을 재정의합니다.

WARNING

이 메서드는 어떤 테스트도 실행하지 않습니다. 업데이트된 패턴으로 테스트를 실행하려면 runTestSpecifications를 호출하십시오.

resetGlobalTestNamePattern

function resetGlobalTestNamePattern(): void;

이 메서드는 테스트 이름 패턴을 재설정합니다. 즉, Vitest는 이제 어떤 테스트도 건너뛰지 않습니다.

WARNING

이 메서드는 어떤 테스트도 실행하지 않습니다. 패턴 없이 테스트를 실행하려면 runTestSpecifications를 호출하십시오.

enableSnapshotUpdate

function enableSnapshotUpdate(): void;

테스트 실행 시 스냅샷 업데이트를 허용하는 모드를 활성화합니다. 이 메서드가 호출된 후 실행되는 모든 테스트는 스냅샷을 업데이트합니다. 모드를 비활성화하려면 resetSnapshotUpdate를 호출하십시오.

WARNING

이 메서드는 어떤 테스트도 실행하지 않습니다. 스냅샷을 업데이트하려면 runTestSpecifications로 테스트를 실행하십시오.

resetSnapshotUpdate

function resetSnapshotUpdate(): void;

테스트 실행 시 스냅샷 업데이트를 허용하는 모드를 비활성화합니다. 이 메서드는 어떤 테스트도 실행하지 않습니다.

invalidateFile

function invalidateFile(filepath: string): void;

이 메서드는 모든 프로젝트의 캐시에서 파일을 무효화합니다. Vite의 캐시가 메모리에 유지되므로 자체 와처에 의존하는 경우에 주로 유용합니다.

DANGER

Vitest의 와처를 비활성화했지만 Vitest를 계속 실행하는 경우, 캐시를 비활성화할 방법이 없으므로 이 메서드를 사용하여 캐시를 수동으로 지우는 것이 중요합니다. 이 메서드는 파일의 임포터도 무효화합니다.

import

function import<T>(moduleId: string): Promise<T>

Vite 모듈 러너를 사용하여 파일을 가져옵니다. 파일은 전역 구성으로 Vite에 의해 변환되고 별도의 컨텍스트에서 실행됩니다. moduleId는 config.root에 상대적입니다.

DANGER

project.import는 Vite의 모듈 그래프를 재사용하므로, 일반적인 import를 사용하여 동일한 모듈을 가져오면 다른 모듈이 반환됩니다:

import * as staticExample from './example.js';
const dynamicExample = await vitest.import('./example.js');

dynamicExample !== staticExample; // ✅

INFO

내부적으로 Vitest는 이 메서드를 사용하여 전역 설정, 사용자 정의 커버리지 제공자 및 사용자 정의 리포터를 가져옵니다. 즉, 이들 모두는 동일한 Vite 서버에 속하는 한 동일한 모듈 그래프를 공유합니다.

close

function close(): Promise<void>;

모든 프로젝트와 관련 리소스를 닫습니다. 이 메서드는 한 번만 호출 가능합니다. 종료 프라미스는 서버가 재시작될 때까지 캐시됩니다.

exit

function exit(force = false): Promise<void>;

모든 프로젝트를 닫고 프로세스를 종료합니다. force가 true로 설정되면, 프로젝트를 닫은 후 프로세스가 즉시 종료됩니다.

이 메서드는 config.teardownTimeout 밀리초 후에도 프로세스가 여전히 활성 상태인 경우 process.exit()를 강제로 호출합니다.

shouldKeepServer

function shouldKeepServer(): boolean;

이 메서드는 테스트 완료 후 서버를 계속 실행해야 할 경우 true를 반환합니다. 이는 일반적으로 watch 모드가 활성화되었음을 의미합니다.

onServerRestart

function onServerRestart(fn: OnServerRestartHandler): void;

구성 변경으로 인해 서버가 다시 시작될 때 호출될 핸들러를 등록합니다.

onCancel

function onCancel(fn: (reason: CancelReason) => Awaitable<void>): void;

vitest.cancelCurrentRun으로 테스트 실행이 취소될 때 호출될 핸들러를 등록합니다.

onClose

function onClose(fn: () => Awaitable<void>): void;

서버가 닫힐 때 호출될 핸들러를 등록합니다.

onTestsRerun

function onTestsRerun(fn: OnTestsRerunHandler): void;

테스트가 다시 실행될 때 호출될 핸들러를 등록합니다. 테스트는 rerunTestSpecifications가 수동으로 호출되거나 파일이 변경되어 내장 와처가 다시 실행을 예약할 때 다시 실행될 수 있습니다.

onFilterWatchedSpecification

function onFilterWatchedSpecification(
  fn: (specification: TestSpecification) => boolean
): void;

파일이 변경될 때 호출될 핸들러를 등록합니다. 이 콜백은 테스트 파일을 다시 실행해야 하는지 여부를 나타내는 true 또는 false를 반환해야 합니다.

이 메서드를 사용하면 기본 와처 로직에 연결하여 사용자가 현재 추적하고 싶지 않은 테스트를 지연시키거나 폐기할 수 있습니다:

const continuesTests: string[] = [];

myCustomWrapper.onContinuesRunEnabled(testItem =>
  continuesTests.push(item.fsPath)
);

vitest.onFilterWatchedSpecification(specification =>
  continuesTests.includes(specification.moduleId)
);

Vitest는 pool 또는 locations 옵션에 따라 동일한 파일에 대해 다른 사양을 생성할 수 있으므로 참조에 의존하지 마십시오. Vitest는 vitest.getModuleSpecifications에서 캐시된 사양을 반환할 수도 있습니다. 캐시는 moduleId 및 pool을 기반으로 합니다. project.createSpecification는 항상 새 인스턴스를 반환합니다.

matchesProjectFilter 3.1.0+

function matchesProjectFilter(name: string): boolean;

이름이 현재 프로젝트 필터와 일치하는지 확인합니다. 프로젝트 필터가 없으면 항상 true를 반환합니다.

--project CLI 옵션을 프로그래밍 방식으로 변경하는 것은 불가능합니다.

Vitest API ​

mode ​

test ​

benchmark 실험적 ​

config ​

vite ​

state 실험적 ​

snapshot ​

cache ​

projects ​

getRootProject ​

provide ​

getProvidedContext ​

getProjectByName ​

globTestSpecifications ​

getRelevantTestSpecifications ​

mergeReports ​

collect ​

start ​

init ​

getModuleSpecifications ​

clearSpecificationsCache ​

runTestSpecifications ​

rerunTestSpecifications ​

updateSnapshot ​

collectTests ​

cancelCurrentRun ​

setGlobalTestNamePattern ​

resetGlobalTestNamePattern ​

enableSnapshotUpdate ​

resetSnapshotUpdate ​

invalidateFile ​

import ​

close ​

exit ​

shouldKeepServer ​

onServerRestart ​

onCancel ​

onClose ​

onTestsRerun ​

onFilterWatchedSpecification ​

matchesProjectFilter 3.1.0+ ​

Vitest API

mode

test

benchmark 실험적

config

vite

state 실험적

snapshot

cache

projects

getRootProject

provide

getProvidedContext

getProjectByName

globTestSpecifications

getRelevantTestSpecifications

mergeReports

collect

start

init

getModuleSpecifications

clearSpecificationsCache

runTestSpecifications

rerunTestSpecifications

updateSnapshot

collectTests

cancelCurrentRun

setGlobalTestNamePattern

resetGlobalTestNamePattern

enableSnapshotUpdate

resetSnapshotUpdate

invalidateFile

import

close

exit

shouldKeepServer

onServerRestart

onCancel

onClose

onTestsRerun

onFilterWatchedSpecification

matchesProjectFilter 3.1.0+