TestProject 3.0.0+

WARNING

이 가이드는 고급 Node.js API를 설명합니다. 프로젝트를 단순히 정의하는 방법은 "테스트 프로젝트" 가이드를 참조하세요.

name

name은 사용자가 할당하거나 Vitest가 자동으로 결정하는 고유한 문자열입니다. 사용자가 이름을 지정하지 않으면 Vitest는 프로젝트 루트에서 package.json 파일을 로드하여 해당 파일의 name 속성을 사용하려고 시도합니다. package.json이 없는 경우 Vitest는 기본적으로 폴더 이름을 사용합니다. 인라인 프로젝트는 이름으로 숫자를 사용합니다(문자열로 변환됨).

node.jsvitest.config.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.projects.map(p => p.name) === ['@pkg/server', 'utils', '2', 'custom'];

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      './packages/server', // "@pkg/server"가 포함된 package.json을 가짐
      './utils', // package.json 파일이 없음
      {
        // 이름을 사용자 정의하지 않음
        test: {
          pool: 'threads',
        },
      },
      {
        // 이름을 사용자 정의함
        test: {
          name: 'custom',
        },
      },
    ],
  },
});

INFO

루트 프로젝트가 사용자 프로젝트의 일부가 아닌 경우, 해당 name은 확인되지 않습니다.

vitest

vitest는 전역 Vitest 프로세스를 참조합니다.

serializedConfig

serializedConfig는 테스트 프로세스에 전달되는 구성입니다. Vitest는 직렬화할 수 없는 모든 함수와 속성을 수동으로 제거하여 구성을 직렬화합니다. 이 값은 테스트 환경과 Node.js 환경 모두에서 사용할 수 있도록 기본 진입점에서 해당 유형이 내보내집니다.

import type { SerializedConfig } from 'vitest';

const config: SerializedConfig = vitest.projects[0].serializedConfig;

WARNING

serializedConfig 속성은 getter입니다. 접근할 때마다 Vitest는 구성이 변경된 경우 다시 직렬화합니다. 이는 또한 항상 다른 참조를 반환한다는 것을 의미합니다.

project.serializedConfig === project.serializedConfig; // ❌

globalConfig

globalConfig는 Vitest가 초기화된 테스트 구성입니다. 이것이 루트 프로젝트인 경우, globalConfig와 config는 동일한 객체를 참조합니다. 이 구성은 coverage 또는 reporters와 같이 프로젝트 수준에서 설정할 수 없는 값에 유용합니다.

import type { ResolvedConfig } from 'vitest/node';

vitest.config === vitest.projects[0].globalConfig;

config

config는 프로젝트의 최종 테스트 구성입니다.

hash 3.2.0+

hash는 이 프로젝트의 고유 해시입니다. 이 값은 재실행 시에도 일관되게 유지됩니다.

프로젝트의 루트와 이름을 기반으로 생성됩니다. 루트 경로는 OS에 따라 일관되지 않을 수 있으므로 해시도 달라질 수 있습니다.

vite

vite는 프로젝트의 ViteDevServer 인스턴스입니다. 모든 프로젝트는 자체 Vite 서버를 가집니다.

browser

browser 값은 브라우저에서 테스트가 실행될 때만 설정됩니다. browser가 활성화되었지만 테스트가 아직 실행되지 않은 상태라면 이 값은 undefined가 됩니다. 프로젝트가 브라우저 테스트를 지원하는지 확인하려면 project.isBrowserEnabled() 메서드를 사용하세요.

WARNING

브라우저 API는 훨씬 더 실험적이며 SemVer를 따르지 않습니다. 브라우저 API는 나머지 API와 별도로 표준화될 예정입니다.

provide

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

provide는 config.provide 필드 외에도 테스트에 사용자 정의 값을 제공하는 방법입니다. 모든 값은 저장되기 전에 structuredClone으로 유효성 검사를 거치지만, providedContext 자체의 값은 복제되지 않습니다.

node.jstest.spec.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');
await vitest.start();

import { inject } from 'vitest';
const value = inject('key');

값은 동적으로 제공할 수 있습니다. 테스트에서 제공된 값은 다음 실행에서 업데이트됩니다.

TIP

이 메서드는 공개 API 사용이 어려운 경우 전역 설정 파일에서도 사용할 수 있습니다.

export default function setup({ provide }) {
  provide('wsPort', 3000);
}

getProvidedContext

function getProvidedContext(): ProvidedContext;

getProvidedContext 메서드는 컨텍스트 객체를 반환합니다. 모든 프로젝트는 vitest.provide에 의해 설정된 전역 컨텍스트를 상속받습니다.

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.provide('global', true);
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');

// { global: true, key: 'value' }
const context = project.getProvidedContext();

TIP

프로젝트 컨텍스트 값은 항상 루트 프로젝트의 컨텍스트를 덮어씁니다.

createSpecification

function createSpecification(
  moduleId: string,
  locations?: number[]
): TestSpecification;

createSpecification은 vitest.runTestSpecifications에서 사용할 수 있는 테스트 사양을 생성합니다. 사양은 테스트 파일을 특정 project 및 선택적 테스트 locations로 범위를 지정합니다. 테스트 위치는 소스 코드에서 테스트가 정의된 코드 줄입니다. 위치가 제공되면 Vitest는 해당 줄에 정의된 테스트만 실행합니다. testNamePattern이 정의되어 있다면 적용됩니다.

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];
const specification = project.createSpecification(
  resolve('./example.test.ts'),
  [20, 40] // 선택적 테스트 라인
);
await vitest.runTestSpecifications([specification]);

WARNING

createSpecification은 해결된 모듈 ID를 필요로 합니다. 파일을 자동으로 해석하거나 파일 시스템에 존재하는지 확인하지 않습니다.

또한 project.createSpecification은 항상 새 인스턴스를 반환합니다.

isRootProject

function isRootProject(): boolean;

isRootProject는 현재 프로젝트가 루트 프로젝트인지 확인합니다. vitest.getRootProject()를 호출하여 루트 프로젝트를 가져올 수도 있습니다.

globTestFiles

function globTestFiles(filters?: string[]): {
  /**
   * 필터와 일치하는 테스트 파일.
   */
  testFiles: string[];
  /**
   * 필터와 일치하는 타입 체크 테스트 파일. `typecheck.enabled`가 `true`가 아니면 비어 있습니다.
   */
  typecheckTestFiles: string[];
};

globTestFiles는 모든 테스트 파일을 glob 방식으로 찾습니다. 이 함수는 일반 테스트와 타입 체크 테스트를 포함하는 객체를 반환합니다.

이 메서드는 filters를 허용합니다. 필터는 Vitest 인스턴스의 다른 메서드와 달리 파일 경로의 일부만 허용됩니다.

project.globTestFiles(['foo']); // ✅
project.globTestFiles(['basic/foo.js:10']); // ❌

TIP

Vitest는 fast-glob을 사용하여 테스트 파일을 찾습니다. test.dir, test.root, root 또는 process.cwd()는 cwd 옵션을 설정합니다.

이 메서드는 여러 구성 옵션을 살펴봅니다.

일반 테스트 파일을 찾기 위한 test.include, test.exclude
인소스 테스트를 찾기 위한 test.includeSource, test.exclude
타입 체크 테스트를 찾기 위한 test.typecheck.include, test.typecheck.exclude

matchesTestGlob

function matchesTestGlob(moduleId: string, source?: () => string): boolean;

matchesTestGlob 메서드는 파일이 일반 테스트 파일인지 여부를 확인합니다. 유효성 검사를 위해 globTestFiles가 사용하는 것과 동일한 구성 속성을 사용합니다.

이 메서드는 또한 두 번째 매개변수로 소스 코드를 허용합니다. 이는 파일이 인소스 테스트인지 유효성을 검사하는 데 사용됩니다. 여러 프로젝트에 대해 이 메서드를 여러 번 호출할 경우 파일을 한 번 읽고 직접 전달하는 것이 좋습니다. 파일이 테스트 파일이 아니지만 includeSource glob과 일치한다면, source가 제공되지 않으면 Vitest는 파일을 동기적으로 읽습니다.

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];

project.matchesTestGlob(resolve('./basic.test.ts')); // true
project.matchesTestGlob(resolve('./basic.ts')); // false
project.matchesTestGlob(
  resolve('./basic.ts'),
  () => `
if (import.meta.vitest) {
  // ...
}
`
); // `includeSource`가 설정된 경우 true

import

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

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

DANGER

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

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

dynamicExample !== staticExample; // ✅

INFO

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

onTestsRerun

function onTestsRerun(cb: OnTestsRerunHandler): void;

onTestsRerun은 project.vitest.onTestsRerun의 약어입니다. 테스트가 재실행되도록 예약되었을 때(일반적으로 파일 변경으로 인해) 대기하는 콜백 함수를 받습니다.

project.onTestsRerun(specs => {
  console.log(specs);
});

isBrowserEnabled

function isBrowserEnabled(): boolean;

isBrowserEnabled는 이 프로젝트가 브라우저에서 테스트를 실행하면 true를 반환합니다.

close

function close(): Promise<void>;

close는 프로젝트 및 모든 관련 리소스를 닫습니다. 이 메서드는 한 번만 호출할 수 있으며, 종료 Promise는 서버가 다시 시작될 때까지 캐시됩니다. 리소스가 다시 필요하다면 새 프로젝트를 생성하세요.

구체적으로는, 이 메서드는 Vite 서버를 닫고, 타입 체커 서비스를 중지하고, 브라우저가 실행 중인 경우 브라우저를 닫고, 소스 코드를 포함하는 임시 디렉토리를 삭제하고, 제공된 컨텍스트를 재설정합니다.

TestProject 3.0.0+ ​

name ​

vitest ​

serializedConfig ​

globalConfig ​

config ​

hash 3.2.0+ ​

vite ​

browser ​

provide ​

getProvidedContext ​

createSpecification ​

isRootProject ​

globTestFiles ​

matchesTestGlob ​

import ​

onTestsRerun ​

isBrowserEnabled ​

close ​

TestProject 3.0.0+

name

vitest

serializedConfig

globalConfig

config

hash 3.2.0+

vite

browser

provide

getProvidedContext

createSpecification

isRootProject

globTestFiles

matchesTestGlob

import

onTestsRerun

isBrowserEnabled

close