Vitest 구성하기

Vite를 사용 중이고 vite.config 파일이 있다면, Vitest는 해당 파일을 읽어 Vite 앱의 플러그인 및 설정을 따릅니다. 테스트를 위한 다른 구성을 원하거나 메인 앱이 Vite에 특별히 의존하지 않는다면, 다음 중 하나를 선택할 수 있습니다:

vitest.config.ts 파일을 생성합니다. 이 파일은 더 높은 우선순위를 가지며 vite.config.ts의 구성을 재정의합니다 (Vitest는 모든 표준 JS 및 TS 확장자를 지원하지만 json은 지원하지 않습니다). 즉, vite.config의 모든 옵션이 적용되지 않음을 의미합니다.
CLI에 --config 옵션을 전달합니다. (예: vitest --config ./path/to/vitest.config.ts)
defineConfig에서 process.env.VITEST 또는 mode 속성을 사용하여 vite.config.ts에 조건부로 다른 구성을 적용할 수 있습니다 (--mode로 재정의되지 않으면 test/benchmark로 설정됩니다).

vitest 자체를 구성하려면 Vite 설정에 test 속성을 추가해야 합니다. 또한 vite에서 defineConfig를 가져오는 경우, 구성 파일 상단에 삼중 슬래시 명령을 사용하여 Vitest 타입에 대한 참조를 추가해야 합니다.

구성 예시 열기

vite에서 defineConfig를 사용하는 경우 다음과 같이 설정합니다:

/// <reference types="vitest" />
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    // ... 여기에 옵션을 지정하세요.
  },
});

<reference types="vitest" />는 Vitest 4부터 더 이상 작동하지 않지만, vitest/config로 마이그레이션할 수 있습니다:

/// <reference types="vitest/config" />
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    // ... 여기에 옵션을 지정하세요.
  },
});

vitest/config에서 defineConfig를 사용하는 경우 다음과 같이 설정합니다:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    // ... 여기에 옵션을 지정하세요.
  },
});

필요한 경우 Vitest의 기본 옵션을 가져와 확장할 수 있습니다:

import { configDefaults, defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    exclude: [...configDefaults.exclude, 'packages/template/*'],
  },
});

별도의 vitest.config.js를 사용하는 경우, 필요하다면 다른 구성 파일에서 Vite의 옵션을 확장할 수도 있습니다:

import { defineConfig, mergeConfig } from 'vitest/config';
import viteConfig from './vite.config';

export default mergeConfig(
  viteConfig,
  defineConfig({
    test: {
      exclude: ['packages/template/*'],
    },
  })
);

Vite 설정이 함수로 정의된 경우, 다음과 같이 설정할 수 있습니다:

import { defineConfig, mergeConfig } from 'vitest/config';
import viteConfig from './vite.config';

export default defineConfig(configEnv =>
  mergeConfig(
    viteConfig(configEnv),
    defineConfig({
      test: {
        exclude: ['packages/template/*'],
      },
    })
  )
);

WARNING

이 페이지에 나열된 모든 옵션은 설정 내의 test 속성 아래에 있습니다:

export default defineConfig({
  test: {
    exclude: [],
  },
});

Vitest는 Vite 구성을 사용하므로 Vite의 모든 구성 옵션을 사용할 수 있습니다. 예를 들어, 전역 변수를 정의하는 define 또는 별칭을 정의하는 resolve.alias와 같은 옵션은 최상위 수준에 정의되어야 하며, test 속성 안에 정의되어서는 안 됩니다.

프로젝트 구성 내에서 지원되지 않는 구성 옵션 옆에는 * 기호가 있습니다. 즉, 루트 Vitest 설정에서만 설정할 수 있습니다.

include

타입: string[]
기본값: ['**/*.{test,spec}.?(c|m)[jt]s?(x)']
CLI: vitest [...include], vitest **/*.test.js

테스트 파일에 해당하는 글로브 패턴 목록입니다.

참고

커버리지를 사용할 때, Vitest는 자동으로 테스트 파일 include 패턴을 커버리지의 기본 exclude 패턴에 추가합니다. coverage.exclude를 참조하세요.

exclude

타입: string[]
기본값: ['**/node_modules/**', '**/dist/**', '**/cypress/**', '**/.{idea,git,cache,output,temp}/**', '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build,eslint,prettier}.config.*']
CLI: vitest --exclude "**/excluded-file"

테스트 파일에서 제외될 글로브 패턴 목록입니다.

WARNING

이 옵션은 커버리지에 영향을 주지 않습니다. 특정 파일을 커버리지 보고서에서 제거해야 한다면 coverage.exclude를 사용하십시오.

이 옵션은 CLI 플래그로 제공하더라도 설정을 재정의하지 않는 유일한 옵션입니다. --exclude 플래그를 통해 추가된 모든 글로브 패턴은 설정의 exclude에 추가됩니다.

includeSource

타입: string[]
기본값: []

소스 내 테스트 파일에 포함할 글로브 패턴입니다.

정의되면 Vitest는 import.meta.vitest가 있는 모든 일치하는 파일을 실행합니다.

name

타입: string | { label: string, color?: LabelColor }

테스트 프로젝트 또는 Vitest 프로세스에 사용자 지정 이름을 할당합니다. 이 이름은 CLI 및 UI에 표시되며, Node.js API를 통해 project.name으로 접근할 수 있습니다.

CLI 및 UI에서 사용되는 색상은 color 속성을 포함하는 객체를 제공하여 변경할 수 있습니다.

server

타입: { sourcemap?, deps?, ... }

Vite-Node 서버 옵션입니다.

server.sourcemap

타입: 'inline' | boolean
기본값: 'inline'

모듈에 인라인 소스 맵을 주입합니다.

server.debug

타입: { dumpModules?, loadDumppedModules? }

Vite-Node 디버거 옵션입니다.

server.debug.dumpModules

타입: boolean | string

변환된 모듈을 파일 시스템에 덤프합니다. 문자열을 전달하면 지정된 경로에 덤프됩니다.

server.debug.loadDumppedModules

타입: boolean

덤프된 모듈이 존재하면 파일 시스템에서 읽습니다. 파일 시스템에서 덤프 결과를 수정하여 디버깅할 때 유용합니다.

server.deps

타입: { external?, inline?, ... }

의존성 해결 처리입니다.

server.deps.external

타입: (string | RegExp)[]
기본값: [/\/node_modules\//]

외부화는 Vite가 패키지를 네이티브 Node로 직접 처리하도록 우회한다는 의미입니다. 외부화된 의존성은 Vite의 변환기 및 해결기에 적용되지 않으므로, 다시 로드할 때 HMR을 지원하지 않습니다. 기본적으로 node_modules 내부의 모든 패키지는 외부화됩니다.

이 옵션은 node_modules에 작성된 패키지 이름 또는 deps.moduleDirectories 내에 지정된 패키지 이름을 지원합니다. 예를 들어, packages/some-name 내에 위치한 @company/some-name 패키지는 some-name으로 지정되어야 하며, packages는 deps.moduleDirectories에 포함되어야 합니다. 기본적으로 Vitest는 실제 패키지 이름이 아닌 파일 경로를 항상 확인합니다.

정규식이 사용되는 경우, Vitest는 패키지 이름이 아닌 _파일 경로_에 대해 호출합니다.

server.deps.inline

타입: (string | RegExp)[] | true
기본값: []

Vite는 인라인 모듈을 처리합니다. 이는 ESM 형식으로 .js를 배포하는 패키지(Node가 처리할 수 없는)를 처리하는 데 도움이 될 수 있습니다.

true로 설정하면, 모든 의존성이 인라인됩니다. ssr.noExternal에 지정된 모든 의존성은 기본적으로 인라인됩니다.

server.deps.fallbackCJS

타입 boolean
기본값: false

의존성이 유효한 ESM 패키지인 경우, 경로를 기반으로 cjs 버전을 추측합니다. 이는 의존성이 잘못된 ESM 파일을 포함하는 경우에 도움이 될 수 있습니다.

이는 패키지가 ESM 및 CJS 모드에서 다른 로직을 가지고 있는 경우 잠재적으로 문제를 일으킬 수 있습니다.

server.deps.cacheDir

타입 string
기본값: 'node_modules/.vite'

캐시 파일을 저장할 디렉토리입니다.

deps

타입: { optimizer?, ... }

의존성 해결 처리입니다.

deps.optimizer

타입: { ssr?, web? }
참고: 의존성 최적화 옵션

의존성 최적화를 활성화합니다. 테스트가 많은 경우 성능 향상에 도움이 될 수 있습니다.

Vitest가 include에 지정된 외부 라이브러리를 만나면, esbuild를 사용하여 단일 파일로 번들링되고 전체 모듈로 가져와집니다. 이는 여러 가지 이유로 좋습니다:

많은 import를 가진 패키지를 가져오는 것은 성능상 부담이 큽니다. 이를 하나의 파일로 번들링하면 많은 시간을 절약할 수 있습니다.
UI 라이브러리를 가져오는 것은 Node.js 내부에서 실행되도록 의도되지 않았기 때문에 성능상 부담이 큽니다.
이제 번들링된 패키지 내에서 alias 설정이 적용됩니다.
테스트 코드가 브라우저에서 실행되는 방식과 더 유사하게 동작합니다.

deps.optimizer?.[mode].include 옵션에 있는 패키지만 번들링된다는 점에 유의하십시오 (일부 플러그인은 Svelte처럼 자동으로 이를 채웁니다). Vite 문서에서 사용 가능한 옵션에 대해 자세히 알아볼 수 있습니다 (Vitest는 disable 및 noDiscovery 옵션을 지원하지 않습니다). 기본적으로 Vitest는 jsdom 및 happy-dom 환경에는 optimizer.web을 사용하고, node 및 edge 환경에는 optimizer.ssr을 사용하지만, 이는 transformMode로 구성할 수 있습니다.

이 옵션은 또한 optimizeDeps 설정을 상속합니다 (웹의 경우 Vitest는 optimizeDeps를 확장하고, ssr의 경우 ssr.optimizeDeps를 확장합니다). deps.optimizer에서 include/exclude 옵션을 재정의하면 테스트 실행 시 optimizeDeps를 확장합니다. Vitest는 exclude에 나열된 옵션이 include에 있다면 자동으로 제거합니다.

TIP

코드가 실제로 cacheDir 또는 test.cache.dir 디렉토리에 있으므로 디버깅을 위해 node_modules 코드를 편집할 수 없습니다. console.log 문으로 디버깅하려면 직접 편집하거나 deps.optimizer?.[mode].force 옵션을 사용하여 재번들링을 강제할 수 있습니다.

deps.optimizer.{mode}.enabled

타입: boolean
기본값: false

의존성 최적화를 활성화합니다.

deps.web

타입: { transformAssets?, ... }

변환 모드가 web으로 설정될 때 외부 파일에 적용되는 옵션입니다. 기본적으로 jsdom 및 happy-dom은 web 모드를 사용하고, node 및 edge 환경은 ssr 변환 모드를 사용하므로, 이 옵션은 해당 환경 내의 파일에는 영향을 미치지 않습니다.

일반적으로 node_modules 내부의 파일은 외부화되지만, 이 옵션은 server.deps.external에 있는 파일에도 영향을 미칩니다.

deps.web.transformAssets

타입: boolean
기본값: true

Vitest가 자산(.png, .svg, .jpg 등) 파일을 Vite가 브라우저에서 처리하는 방식과 동일하게 처리하고 해결해야 하는지 여부입니다.

이 모듈은 쿼리가 지정되지 않은 경우 자산 경로를 기본 내보내기로 가집니다.

WARNING

현재 이 옵션은 vmThreads 및 vmForks 풀에서만 작동합니다.

deps.web.transformCss

타입: boolean
기본값: true

Vitest가 CSS(.css, .scss, .sass 등) 파일을 Vite가 브라우저에서 처리하는 방식과 동일하게 처리하고 해결해야 하는지 여부입니다.

CSS 파일이 css 옵션으로 비활성화된 경우, 이 옵션은 ERR_UNKNOWN_FILE_EXTENSION 오류를 억제합니다.

WARNING

현재 이 옵션은 vmThreads 및 vmForks 풀에서만 작동합니다.

deps.web.transformGlobPattern

타입: RegExp | RegExp[]
기본값: []

변환되어야 하는 외부 파일에 해당하는 정규식 패턴입니다.

기본적으로 node_modules 내부의 파일은 외부화되며 변환되지 않습니다. 단, CSS 또는 자산 파일이거나 해당 옵션이 비활성화되지 않은 경우는 예외입니다.

WARNING

현재 이 옵션은 vmThreads 및 vmForks 풀에서만 작동합니다.

deps.interopDefault

타입: boolean
기본값: true

CJS 모듈의 기본 내보내기를 명명된 내보내기로 해석합니다. 일부 의존성은 CJS 모듈만 번들링하며, require 구문 대신 import 구문을 사용하여 패키지를 가져올 때 Node.js가 정적으로 분석할 수 있는 명명된 내보내기를 사용하지 않습니다. Node 환경에서 명명된 내보내기를 사용하여 이러한 의존성을 가져올 때 다음 오류가 발생할 수 있습니다:

import { read } from 'fs-jetpack';
         ^^^^
SyntaxError: Named export 'read' not found. The requested module 'fs-jetpack' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export.

Vitest는 정적 분석을 수행하지 않으며, 코드를 실행하기 전에 오류를 발생시킬 수 없으므로, 이 기능이 비활성화된 경우 테스트 실행 시 다음 오류가 발생할 가능성이 높습니다:

TypeError: createAsyncThunk is not a function
TypeError: default is not a function

기본적으로 Vitest는 이 문제를 우회하기 위해 번들러를 사용한다고 가정하며 실패하지 않지만, 코드가 처리되지 않는 경우 이 동작을 수동으로 비활성화할 수 있습니다.

deps.moduleDirectories

타입: string[]
기본값: ['node_modules']

모듈 디렉토리로 처리될 디렉토리 목록입니다. 이 설정 옵션은 vi.mock의 동작에 영향을 미칩니다: 팩토리가 제공되지 않고 모의하려는 경로가 moduleDirectories 값 중 하나와 일치하는 경우, Vitest는 프로젝트의 루트에서 __mocks__ 폴더를 찾아 모의를 해결하려고 시도합니다.

이 옵션은 의존성을 외부화할 때 파일이 모듈로 처리될지 여부에도 영향을 미칩니다. 기본적으로 Vitest는 Vite 변환 단계를 우회하여 네이티브 Node.js로 외부 모듈을 가져옵니다.

이 옵션을 설정하면 기본값을 _재정의_합니다. 여전히 node_modules에서 패키지를 검색하려면 다른 옵션과 함께 포함하세요:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    deps: {
      moduleDirectories: ['node_modules', path.resolve('../../packages')],
    },
  },
});

runner

타입: VitestRunnerConstructor
기본값: 테스트 실행 시 node, 벤치마크 실행 시 benchmark

사용자 지정 테스트 러너 경로입니다. 이는 고급 기능이며 사용자 지정 라이브러리 러너와 함께 사용해야 합니다. 문서에서 자세히 알아볼 수 있습니다.

benchmark

타입: { include?, exclude?, ... }

vitest bench 실행 시 사용되는 옵션입니다.

benchmark.include

타입: string[]
기본값: ['**/*.{bench,benchmark}.?(c|m)[jt]s?(x)']

벤치마크 테스트 파일에 포함할 글로브 패턴입니다.

benchmark.exclude

타입: string[]
기본값: ['node_modules', 'dist', '.idea', '.git', '.cache']

벤치마크 테스트 파일에서 제외할 글로브 패턴입니다.

benchmark.includeSource

타입: string[]
기본값: []

소스 내 벤치마크 테스트 파일에 포함할 글로브 패턴입니다. 이 옵션은 includeSource와 유사합니다.

정의되면 Vitest는 import.meta.vitest가 있는 모든 일치하는 파일을 실행합니다.

benchmark.reporters

타입: Arrayable<BenchmarkBuiltinReporters | Reporter>
기본값: 'default'

출력을 위한 사용자 지정 리포터입니다. 하나 이상의 내장 보고서 이름, 리포터 인스턴스 및/또는 사용자 지정 리포터 경로를 포함할 수 있습니다.

benchmark.outputFile

benchmark.outputJson으로 대체되었습니다.

benchmark.outputJson

타입: string | undefined
기본값: undefined

벤치마크 결과를 저장할 파일 경로로, 나중에 --compare 옵션에 활용할 수 있습니다.

예시:

# 메인 브랜치의 결과 저장
git checkout main
vitest bench --outputJson main.json

# 브랜치 변경 후 메인 브랜치와 비교
git checkout feature
vitest bench --compare main.json

benchmark.compare

타입: string | undefined
기본값: undefined

현재 실행과 비교할 이전 벤치마크 결과 파일 경로입니다.

alias

타입: Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>

테스트 실행 시 사용자 지정 별칭을 정의합니다. 이 별칭은 resolve.alias의 별칭과 병합됩니다.

WARNING

Vitest는 테스트 실행을 위해 Vite SSR 프리미티브를 사용하며, 이로 인해 특정 제약사항이 있습니다.

별칭은 인라인된 모듈(모든 소스 코드는 기본적으로 인라인됨)이 import 키워드로 직접 가져온 모듈에만 영향을 미칩니다.
Vitest는 require 호출에 대한 별칭을 지원하지 않습니다.
외부 의존성(예: react -> preact)에 별칭을 지정하는 경우, 외부화된 의존성에서 작동하도록 실제 node_modules 패키지에 별칭을 지정하는 것이 좋습니다. Yarn과 pnpm 모두 npm: 접두사를 사용하여 별칭을 지원합니다.

globals

타입: boolean
기본값: false
CLI: --globals, --globals=false

기본적으로 vitest는 명시성을 위해 전역 API를 제공하지 않습니다. Jest처럼 API를 전역적으로 사용하려면 CLI에 --globals 옵션을 전달하거나 설정에 globals: true를 추가할 수 있습니다.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
  },
});

전역 API에서 TypeScript를 사용하려면 tsconfig.json의 types 필드에 vitest/globals를 추가하세요.

json

{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

컴파일에 더 많은 타입을 포함하도록 typeRoots를 재정의한 경우, vitest/globals를 찾을 수 있도록 node_modules를 다시 추가해야 합니다.

json

{
  "compilerOptions": {
    "typeRoots": ["./types", "./node_modules/@types", "./node_modules"],
    "types": ["vitest/globals"]
  }
}

프로젝트에서 이미 unplugin-auto-import를 사용하고 있다면, 해당 API를 자동 가져오기 위해 직접 사용할 수도 있습니다.

import { defineConfig } from 'vitest/config';
import AutoImport from 'unplugin-auto-import/vite';

export default defineConfig({
  plugins: [
    AutoImport({
      imports: ['vitest'],
      dts: true, // TypeScript 선언 파일 생성
    }),
  ],
});

environment

타입: 'node' | 'jsdom' | 'happy-dom' | 'edge-runtime' | string
기본값: 'node'
CLI: --environment=<env>

테스트에 사용될 환경입니다. Vitest의 기본 환경은 Node.js 환경입니다. 웹 애플리케이션을 구축하는 경우 jsdom 또는 happy-dom을 통해 브라우저와 유사한 환경을 사용할 수 있습니다.

엣지 함수를 구축하는 경우 edge-runtime 환경을 사용할 수 있습니다.

TIP

브라우저 모드를 사용하여 환경을 모의하지 않고 브라우저에서 통합 또는 단위 테스트를 실행할 수도 있습니다.

파일 상단에 @vitest-environment docblock 또는 주석을 추가하여 해당 파일의 모든 테스트에 사용할 다른 환경을 지정할 수 있습니다:

Docblock 스타일:

/**
 * @vitest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

주석 스타일:

// @vitest-environment happy-dom

test('use happy-dom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

Jest와의 호환성을 위해 @jest-environment도 제공됩니다:

/**
 * @jest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

Vitest를 --isolate=false 플래그로 실행하는 경우, 테스트는 node, jsdom, happy-dom, edge-runtime, custom environments 순서로 실행됩니다. 즉, 동일한 환경을 가진 모든 테스트는 그룹화되지만 여전히 순차적으로 실행됩니다.

0.23.0 버전부터 사용자 지정 환경을 정의할 수도 있습니다. 내장 환경이 아닌 환경이 사용되면 Vitest는 vitest-environment-${name} 패키지를 로드하려고 시도합니다. 해당 패키지는 Environment 형태의 객체를 내보내야 합니다:

import type { Environment } from 'vitest';

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  setup() {
    // 사용자 지정 설정
    return {
      teardown() {
        // 이 환경으로 모든 테스트가 실행된 후 호출됩니다.
      },
    };
  },
};

Vitest는 또한 vitest/environments 항목을 통해 builtinEnvironments를 노출합니다. 이는 단순히 확장하려는 경우에 유용합니다. 가이드에서 환경 확장에 대해 자세히 알아볼 수 있습니다.

TIP

jsdom 환경은 현재 JSDOM 인스턴스와 동일한 jsdom 전역 변수를 노출합니다. TypeScript가 이를 인식하도록 하려면 이 환경을 사용할 때 tsconfig.json에 vitest/jsdom을 추가할 수 있습니다:

json

{
  "compilerOptions": {
    "types": ["vitest/jsdom"]
  }
}

environmentOptions

타입: Record<'jsdom' | string, unknown>
기본값: {}

이 옵션은 현재 environment의 setup 메서드로 전달됩니다. 기본적으로 테스트 환경으로 JSDOM을 사용하는 경우에만 JSDOM 옵션을 구성할 수 있습니다.

environmentMatchGlobs

타입: [string, EnvironmentName][]
기본값: []

DEPRECATED

이 API는 Vitest 3에서 더 이상 사용되지 않습니다. 대신 프로젝트를 사용하여 다른 구성을 정의하세요.

export default defineConfig({
  test: {
    environmentMatchGlobs: [ 
      ['./*.jsdom.test.ts', 'jsdom'], 
    ], 
    projects: [ 
      { 
        extends: true, 
        test: { 
          environment: 'jsdom', 
        }, 
      }, 
    ], 
  },
})

글로브 패턴을 기반으로 환경을 자동으로 할당합니다. 첫 번째 일치 항목이 사용됩니다.

예시:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environmentMatchGlobs: [
      // tests/dom의 모든 테스트는 jsdom에서 실행됩니다.
      ['tests/dom/**', 'jsdom'],
      // tests/ 내 .edge.test.ts 파일을 가진 모든 테스트는 edge-runtime에서 실행됩니다.
      ['**/*.edge.test.ts', 'edge-runtime'],
      // ...
    ],
  },
});

poolMatchGlobs

타입: [string, 'threads' | 'forks' | 'vmThreads' | 'vmForks' | 'typescript'][]
기본값: []

DEPRECATED

이 API는 Vitest 3에서 더 이상 사용되지 않습니다. 대신 프로젝트를 사용하여 다른 구성을 정의하세요:

export default defineConfig({
  test: {
    poolMatchGlobs: [ 
      ['./*.threads.test.ts', 'threads'], 
    ], 
    projects: [ 
      { 
        test: { 
          extends: true, 
          pool: 'threads', 
        }, 
      }, 
    ], 
  },
})

글로브 패턴을 기반으로 테스트가 실행될 풀을 자동으로 할당합니다. 첫 번째 일치 항목이 사용됩니다.

예시:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolMatchGlobs: [
      // "worker-specific" 디렉토리의 모든 테스트는 `--pool=threads`를 활성화한 것처럼 워커 내부에서 실행됩니다.
      ['**/tests/worker-specific/**', 'threads'],
      // "browser" 디렉토리의 모든 테스트를 실제 브라우저에서 실행합니다.
      ['**/tests/browser/**', 'browser'],
      // 다른 전역 패턴을 지정하지 않은 경우, 다른 모든 테스트는 "browser.enabled" 및 "threads" 옵션을 기반으로 실행됩니다.
      // ...
    ],
  },
});

update*

타입: boolean
기본값: false
CLI: -u, --update, --update=false

스냅샷 파일 업데이트. 변경되거나 더 이상 사용되지 않는 스냅샷을 업데이트하고 삭제합니다.

watch*

타입: boolean
기본값: !process.env.CI && process.stdin.isTTY
CLI: -w, --watch, --watch=false

감시 모드 활성화.

대화형 환경에서는 --run이 명시적으로 지정되지 않는 한 이것이 기본값입니다.

CI 또는 비대화형 셸에서 실행될 때는 "감시" 모드가 기본값이 아니지만, 이 플래그로 명시적으로 활성화할 수 있습니다.

watchTriggerPatterns 3.2.0+ *

타입: WatcherTriggerPattern[]

Vitest는 정적 및 동적 import 문으로 구성된 모듈 그래프를 기반으로 테스트를 다시 실행합니다. 그러나 파일 시스템에서 읽거나 프록시에서 가져오는 경우 Vitest는 해당 의존성을 감지할 수 없습니다.

이러한 테스트를 올바르게 다시 실행하려면 정규식 패턴과 실행할 테스트 파일 목록을 반환하는 함수를 정의할 수 있습니다.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    watchTriggerPatterns: [
      {
        pattern: /^src\/(mailers|templates)\/(.*)\.(ts|html|txt)$/,
        testToRun: (id, match) => {
          // root 값에 상대적입니다.
          return `./api/tests/mailers/${match[2]}.test.ts`;
        },
      },
    ],
  },
});

WARNING

반환된 파일은 절대 경로이거나 루트에 대한 상대 경로여야 합니다. 이는 전역 옵션이며 프로젝트 구성 내에서는 사용할 수 없습니다.

root

타입: string
CLI: -r <path>, --root=<path>

프로젝트 루트입니다.

dir

타입: string
CLI: --dir=<path>
기본값: root와 동일

테스트 파일을 스캔할 기본 디렉토리입니다. 루트가 전체 프로젝트를 포함하는 경우 이 옵션을 지정하여 테스트 검색 속도를 높일 수 있습니다.

reporters*

타입: Reporter | Reporter[]
기본값: 'default'
CLI: --reporter=<name>, --reporter=<name1> --reporter=<name2>

출력을 위한 사용자 지정 리포터입니다. 리포터는 리포터 인스턴스, 내장 리포터를 선택하는 문자열 또는 사용자 지정 구현 경로(예: './path/to/reporter.ts', '@scope/reporter')일 수 있습니다.

outputFile*

타입: string | Record<string, string>
CLI: --outputFile=<path>, --outputFile.json=./path

--reporter=json, --reporter=html 또는 --reporter=junit 옵션도 지정된 경우 테스트 결과를 파일에 씁니다. 문자열 대신 객체를 제공하여 여러 리포터를 사용할 때 개별 출력을 정의할 수 있습니다.

pool*

타입: 'threads' | 'forks' | 'vmThreads' | 'vmForks'
기본값: 'forks'
CLI: --pool=threads

테스트 실행에 사용되는 풀입니다.

threads*

tinypool(경량 Piscina 포크)을 사용하여 멀티 스레딩을 활성화합니다. 스레드를 사용할 때는 process.chdir()와 같은 프로세스 관련 API를 사용할 수 없습니다. Prisma, bcrypt, canvas와 같은 네이티브 언어로 작성된 일부 라이브러리는 여러 스레드에서 실행될 때 문제가 발생하여 세그먼트 오류가 발생합니다. 이러한 경우에는 forks 풀을 대신 사용하는 것이 좋습니다.

forks*

threads 풀과 유사하지만 tinypool을 통해 worker_threads 대신 child_process를 사용합니다. 테스트와 메인 프로세스 간의 통신은 threads 풀만큼 빠르지 않습니다. process.chdir()와 같은 프로세스 관련 API는 forks 풀에서 사용할 수 있습니다.

vmThreads*

threads 풀에서 VM 컨텍스트(샌드박스 환경 내부)를 사용하여 테스트를 실행합니다.

이렇게 하면 테스트가 더 빠르게 실행되지만, VM 모듈은 ESM 코드를 실행할 때 불안정합니다. 테스트에서 메모리 누수가 발생할 수 있습니다. 이를 해결하려면 poolOptions.vmThreads.memoryLimit 값을 수동으로 편집하는 것을 고려하세요.

WARNING

샌드박스에서 코드를 실행하는 것은 몇 가지 장점(더 빠른 테스트)이 있지만, 여러 가지 단점도 있습니다.

fs, path 등과 같은 네이티브 모듈 내의 전역 변수는 테스트 환경에 있는 전역 변수와 다릅니다. 결과적으로 이러한 네이티브 모듈에서 발생하는 모든 오류는 코드에서 사용된 Error 생성자와 다른 Error 생성자를 참조합니다:

try {
  fs.writeFileSync('/doesnt exist');
} catch (err) {
  console.log(err instanceof Error); // false
}

ES 모듈을 가져오면 무기한 캐시되어 컨텍스트(테스트 파일)가 많으면 메모리 누수가 발생합니다. Node.js에는 해당 캐시를 지우는 API가 없습니다.
샌드박스 환경에서 전역 변수에 액세스하는 데 더 오래 걸립니다.

이 옵션을 사용할 때 이러한 문제에 유의하십시오. Vitest 팀은 이러한 문제를 자체적으로 해결할 수 없습니다.

vmForks*

vmThreads 풀과 유사하지만 tinypool을 통해 worker_threads 대신 child_process를 사용합니다. 테스트와 메인 프로세스 간의 통신은 vmThreads 풀만큼 빠르지 않습니다. process.chdir()와 같은 프로세스 관련 API는 vmForks 풀에서 사용할 수 있습니다. 이 풀은 vmThreads에 나열된 것과 동일한 함정을 가지고 있음을 유의하십시오.

poolOptions*

타입: Record<'threads' | 'forks' | 'vmThreads' | 'vmForks', {}>
기본값: {}

poolOptions.threads

threads 풀 옵션입니다.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      threads: {
        // 스레드 관련 옵션은 여기에
      },
    },
  },
});

poolOptions.threads.maxThreads*

타입: number | string
기본값: 사용 가능한 CPU 수

최대 스레드 수 또는 비율입니다. VITEST_MAX_THREADS 환경 변수를 사용할 수도 있습니다.

poolOptions.threads.minThreads*

타입: number | string
기본값: 사용 가능한 CPU 수

최소 스레드 수 또는 비율입니다. VITEST_MIN_THREADS 환경 변수를 사용할 수도 있습니다.

poolOptions.threads.singleThread

타입: boolean
기본값: false

동일한 환경을 가진 모든 테스트를 단일 워커 스레드 내에서 실행합니다. 이렇게 하면 내장 모듈 격리가 비활성화되지만(소스 코드 또는 인라인된 코드는 각 테스트에 대해 다시 평가됨), 테스트 성능을 향상시킬 수 있습니다.

WARNING

이 옵션은 테스트를 순차적으로 실행하도록 강제하지만, Jest의 --runInBand와는 다릅니다. Vitest는 테스트를 병렬로 실행하는 것뿐만 아니라 격리를 제공하기 위해 워커를 사용합니다. 이 옵션을 비활성화하면 테스트는 순차적으로 실행되지만 동일한 전역 컨텍스트에서 실행되므로 직접 격리를 제공해야 합니다.

이는 전역 상태에 의존하는 경우(프론트엔드 프레임워크는 일반적으로 그렇습니다) 또는 코드가 각 테스트에 대해 환경이 별도로 정의되어야 하는 경우 모든 종류의 문제를 일으킬 수 있습니다. 그러나 전역 상태에 반드시 의존하지 않거나 쉽게 우회할 수 있는 테스트의 경우 테스트 속도를 높일 수 있습니다(최대 3배 빠름).

poolOptions.threads.useAtomics*

타입: boolean
기본값: false

스레드 동기화를 위해 Atomics를 사용합니다.

이는 일부 경우에 성능을 향상시킬 수 있지만, 이전 Node 버전에서는 세그먼트 오류를 일으킬 수 있습니다.

poolOptions.threads.isolate

Type: boolean
Default: true

각 테스트 파일에 대한 환경을 격리합니다.

poolOptions.threads.execArgv*

타입: string[]
기본값: []

스레드에서 node에 추가 인수를 전달합니다. 자세한 내용은 명령줄 API | Node.js를 참조하십시오.

WARNING

일부 옵션(예: --prof, --title)은 워커를 충돌시킬 수 있으므로 사용할 때 주의하십시오. https://github.com/nodejs/node/issues/41103을 참조하십시오.

poolOptions.forks

forks 풀 옵션입니다.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      forks: {
        // 포크 관련 옵션은 여기에
      },
    },
  },
});

poolOptions.forks.maxForks*

타입: number | string
기본값: 사용 가능한 CPU 수

최대 포크 수 또는 비율입니다. VITEST_MAX_FORKS 환경 변수를 사용할 수도 있습니다.

poolOptions.forks.minForks*

타입: number | string
기본값: 사용 가능한 CPU 수

최소 포크 수 또는 비율입니다. VITEST_MIN_FORKS 환경 변수를 사용할 수도 있습니다.

poolOptions.forks.isolate

타입: boolean
기본값: true

각 테스트 파일에 대한 환경을 격리합니다.

poolOptions.forks.singleFork

타입: boolean
기본값: false

동일한 환경을 가진 모든 테스트를 단일 자식 프로세스 내에서 실행합니다. 이렇게 하면 내장 모듈 격리가 비활성화되지만(소스 코드 또는 인라인된 코드는 각 테스트에 대해 다시 평가됨), 테스트 성능을 향상시킬 수 있습니다.

WARNING

이 옵션은 테스트를 순차적으로 실행하도록 강제하지만, Jest의 --runInBand와는 다릅니다. Vitest는 테스트를 병렬로 실행하는 것뿐만 아니라 격리를 제공하기 위해 자식 프로세스를 사용합니다. 이 옵션을 비활성화하면 테스트는 순차적으로 실행되지만 동일한 전역 컨텍스트에서 실행되므로 직접 격리를 제공해야 합니다.

poolOptions.forks.execArgv*

타입: string[]
기본값: []

자식 프로세스에서 node 프로세스에 추가 인수를 전달합니다. 자세한 내용은 명령줄 API | Node.js를 참조하십시오.

WARNING

일부 옵션(예: --prof, --title)은 워커를 충돌시킬 수 있으므로 사용할 때 주의하십시오. https://github.com/nodejs/node/issues/41103을 참조하십시오.

poolOptions.vmThreads

vmThreads 풀 옵션입니다.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      vmThreads: {
        // VM 스레드 관련 옵션은 여기에
      },
    },
  },
});

poolOptions.vmThreads.maxThreads*

타입: number | string
기본값: 사용 가능한 CPU 수

최대 스레드 수 또는 비율입니다. VITEST_MAX_THREADS 환경 변수를 사용할 수도 있습니다.

poolOptions.vmThreads.minThreads*

타입: number | string
기본값: 사용 가능한 CPU 수

최소 스레드 수 또는 비율입니다. VITEST_MIN_THREADS 환경 변수를 사용할 수도 있습니다.

poolOptions.vmThreads.memoryLimit*

타입: string | number
기본값: 1 / CPU 코어 수

워커가 재활용되기 전의 메모리 제한을 지정합니다. 이 값은 환경에 따라 크게 달라지므로 기본값에 의존하기보다는 수동으로 지정하는 것이 좋습니다.

TIP

구현은 Jest의 workerIdleMemoryLimit을 기반으로 합니다.

제한은 여러 가지 방법으로 지정할 수 있으며, 결과가 무엇이든 Math.floor를 사용하여 정수 값으로 변환됩니다:

<= 1 - 값은 시스템 메모리의 백분율로 간주됩니다. 따라서 0.5는 워커의 메모리 제한을 전체 시스템 메모리의 절반으로 설정합니다.
> 1 - 고정 바이트 값으로 간주됩니다. 이전 규칙 때문에 1바이트(이유는 모르겠지만) 값을 원한다면 1.1을 사용할 수 있습니다.
단위 포함
- 50% - 위와 같이 전체 시스템 메모리의 백분율입니다.
- 100KB, 65MB 등 - 고정 메모리 제한을 나타내는 단위 포함.
  - K / KB - 킬로바이트 (x1000)
  - KiB - 키비바이트 (x1024)
  - M / MB - 메가바이트 - MiB - 메비바이트
  - G / GB - 기가바이트 - GiB - 기비바이트

WARNING

백분율 기반 메모리 제한은 잘못된 시스템 메모리 보고로 인해 Linux CircleCI 워커에서 작동하지 않습니다.

poolOptions.vmThreads.useAtomics*

타입: boolean
기본값: false

스레드 동기화를 위해 Atomics를 사용합니다.

이는 일부 경우에 성능을 향상시킬 수 있지만, 이전 Node 버전에서는 세그먼트 오류를 일으킬 수 있습니다.

poolOptions.vmThreads.execArgv*

타입: string[]
기본값: []

VM 컨텍스트에서 node 프로세스에 추가 인수를 전달합니다. 자세한 내용은 명령줄 API | Node.js를 참조하십시오.

WARNING

일부 옵션(예: --prof, --title)은 워커를 충돌시킬 수 있으므로 사용할 때 주의하십시오. https://github.com/nodejs/node/issues/41103 을 참조하십시오.

poolOptions.vmForks*

vmForks 풀 옵션입니다.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      vmForks: {
        // VM 포크 관련 옵션은 여기에
      },
    },
  },
});

poolOptions.vmForks.maxForks*

타입: number | string
기본값: 사용 가능한 CPU 수

최대 포크 수 또는 비율입니다. VITEST_MAX_FORKS 환경 변수를 사용할 수도 있습니다.

poolOptions.vmForks.minForks*

타입: number | string
기본값: 사용 가능한 CPU 수

최소 포크 수 또는 비율입니다. VITEST_MIN_FORKS 환경 변수를 사용할 수도 있습니다.

poolOptions.vmForks.memoryLimit*

타입: string | number
기본값: 1 / CPU 코어 수

워커가 재활용되기 전의 메모리 제한을 지정합니다. 이 값은 환경에 따라 크게 달라지므로 기본값에 의존하기보다는 수동으로 지정하는 것이 좋습니다. 값 계산 방법은 poolOptions.vmThreads.memoryLimit에 설명되어 있습니다.

poolOptions.vmForks.execArgv*

타입: string[]
기본값: []

VM 컨텍스트에서 node 프로세스에 추가 인수를 전달합니다. 자세한 내용은 명령줄 API | Node.js를 참조하십시오.

WARNING

일부 옵션(예: --prof, --title)은 워커를 충돌시킬 수 있으므로 사용할 때 주의하십시오. https://github.com/nodejs/node/issues/41103을 참조하십시오.

fileParallelism*

타입: boolean
기본값: true
CLI: --no-file-parallelism, --fileParallelism=false

모든 테스트 파일을 병렬로 실행해야 하는지 여부입니다. 이 값을 false로 설정하면 maxWorkers 및 minWorkers 옵션이 1로 재정의됩니다.

TIP

이 옵션은 동일한 파일에서 실행되는 테스트에는 영향을 미치지 않습니다. 이를 병렬로 실행하려면 describe 또는 구성을 통해 concurrent 옵션을 사용하십시오.

maxWorkers*

타입: number | string

테스트를 실행할 최대 워커 수 또는 비율입니다. poolOptions.{threads,vmThreads}.maxThreads/poolOptions.forks.maxForks가 더 높은 우선순위를 가집니다.

minWorkers*

타입: number | string

테스트를 실행할 최소 워커 수 또는 비율입니다. poolOptions.{threads,vmThreads}.minThreads/poolOptions.forks.minForks가 더 높은 우선순위를 가집니다.

testTimeout

타입: number
기본값: Node.js에서는 5_000, browser.enabled가 true인 경우 15_000
CLI: --test-timeout=5000, --testTimeout=5000

테스트의 기본 시간 초과(밀리초)입니다. 시간 초과를 완전히 비활성화하려면 0을 사용하십시오.

hookTimeout

타입: number
기본값: Node.js에서는 10_000, browser.enabled가 true인 경우 30_000
CLI: --hook-timeout=10000, --hookTimeout=10000

훅의 기본 시간 초과(밀리초)입니다. 시간 초과를 완전히 비활성화하려면 0을 사용하십시오.

teardownTimeout*

타입: number
기본값: 10000
CLI: --teardown-timeout=5000, --teardownTimeout=5000

Vitest가 종료될 때 닫기를 기다리는 기본 시간 초과(밀리초)입니다.

silent*

타입: boolean | 'passed-only'
기본값: false
CLI: --silent, --silent=false

테스트의 콘솔 출력을 숨깁니다.

실패한 테스트의 로그만 보려면 'passed-only'를 사용하십시오. 실패한 테스트의 로그는 테스트가 완료된 후 출력됩니다.

setupFiles

타입: string | string[]

설정 파일 경로입니다. 각 테스트 파일 전에 실행됩니다.

INFO

설정 파일을 편집하면 모든 테스트가 자동으로 다시 실행됩니다.

process.env.VITEST_POOL_ID(정수형 문자열)를 사용하여 스레드를 구분할 수 있습니다.

TIP

참고: --isolate=false로 실행하는 경우, 이 설정 파일은 동일한 전역 범위에서 여러 번 실행됩니다. 즉, 각 테스트 전에 동일한 전역 객체에 액세스하므로 필요한 것 이상으로 동일한 작업을 수행하지 않도록 주의하십시오.

예를 들어, 전역 변수에 의존할 수 있습니다:

import { config } from '@some-testing-lib';

if (!globalThis.defined) {
  config.plugins = [myCoolPlugin];
  computeHeavyThing();
  globalThis.defined = true;
}

// 훅은 각 스위트 전에 재설정됩니다.
afterEach(() => {
  cleanup();
});

globalThis.resetBeforeEachTest = true;

provide 2.1.0+

타입: Partial<ProvidedContext>

inject 메서드를 사용하여 테스트 내부에서 액세스할 수 있는 값을 정의합니다.

vitest.config.jsapi.test.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    provide: {
      API_KEY: '123',
    },
  },
});

import { expect, inject, test } from 'vitest';

test('api key is defined', () => {
  expect(inject('API_KEY')).toBe('123');
});

WARNING

속성은 문자열이어야 하며 값은 직렬화 가능해야 합니다. 이 객체는 다른 프로세스 간에 전송되기 때문입니다.

TIP

TypeScript를 사용하는 경우, 타입 안전한 액세스를 위해 ProvidedContext 타입을 확장해야 합니다:

declare module 'vitest' {
  export interface ProvidedContext {
    API_KEY: string;
  }
}

// 증강이 올바르게 작동하도록 이 파일을 모듈로 표시합니다.
export {};

globalSetup

타입: string | string[]

프로젝트 루트에 대한 상대 경로로 전역 설정 파일 경로입니다.

전역 설정 파일은 setup 및 teardown이라는 이름의 함수를 내보내거나, teardown 함수를 반환하는 default 함수를 내보낼 수 있습니다 (예시).

INFO

여러 개의 globalSetup 파일을 사용할 수 있습니다. setup과 teardown은 순차적으로 실행되며, teardown은 역순으로 실행됩니다.

WARNING

전역 설정은 실행 중인 테스트가 하나 이상 있는 경우에만 실행됩니다. 이는 감시 모드에서 테스트 파일이 변경된 후 전역 설정이 실행되기 시작할 수 있음을 의미합니다(테스트 파일은 전역 설정이 완료될 때까지 기다린 후 실행됩니다).

주의: 전역 설정은 다른 전역 범위에서 실행되므로 테스트는 여기에 정의된 변수에 액세스할 수 없습니다. 그러나 provide 메서드를 통해 직렬화 가능한 데이터를 테스트에 전달할 수 있습니다:

example.test.jsglobalSetup.ts 3.0.0+ globalSetup.ts 2.0.0+

import { inject } from 'vitest';

inject('wsPort') === 3000;

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

export default function setup(project: TestProject) {
  project.provide('wsPort', 3000);
}

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

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

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

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

Vitest 3부터 Vitest가 테스트를 다시 실행할 때 호출될 사용자 지정 콜백 함수를 정의할 수 있습니다. 함수가 비동기인 경우, 러너는 테스트를 실행하기 전에 완료될 때까지 기다립니다. project를 { onTestsRerun }처럼 구조 분해할 수 없습니다. 컨텍스트에 의존하기 때문입니다.

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

export default function setup(project: TestProject) {
  project.onTestsRerun(async () => {
    await restartDb();
  });
}

forceRerunTriggers*

타입: string[]
기본값: ['**/package.json/**', '**/vitest.config.*/**', '**/vite.config.*/**']

전체 스위트 재실행을 트리거할 파일 경로의 글로브 패턴입니다. --changed 인수와 함께 사용하면 git diff에서 트리거가 발견되면 전체 테스트 스위트를 실행합니다.

CLI 명령 호출을 테스트하는 경우 유용합니다. Vite는 모듈 그래프를 구성할 수 없기 때문입니다:

test('execute a script', async () => {
  // `dist/index.js`의 내용이 변경되면 Vitest는 이 테스트를 다시 실행할 수 없습니다.
  await execa('node', ['dist/index.js']);
});

TIP

파일이 server.watch.ignored에 의해 제외되지 않았는지 확인하십시오.

coverage*

커버리지 수집을 위해 v8, istanbul 또는 사용자 지정 커버리지 솔루션을 사용할 수 있습니다.

점 표기법으로 CLI에 커버리지 옵션을 제공할 수 있습니다:

npx vitest --coverage.enabled --coverage.provider=istanbul --coverage.all

WARNING

점 표기법으로 커버리지 옵션을 사용하는 경우, --coverage.enabled를 지정하는 것을 잊지 마십시오. 이 경우 단일 --coverage 옵션을 제공하지 마십시오.

coverage.provider

타입: 'v8' | 'istanbul' | 'custom'
기본값: 'v8'
CLI: --coverage.provider=<provider>

커버리지 수집 도구를 선택하려면 provider를 사용하십시오.

coverage.enabled

타입: boolean
기본값: false
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.enabled, --coverage.enabled=false

커버리지 수집을 활성화합니다. --coverage CLI 옵션을 사용하여 재정의할 수 있습니다.

coverage.include

타입: string[]
기본값: ['**']
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.include=<path>, --coverage.include=<path1> --coverage.include=<path2>

글로브 패턴으로 커버리지에 포함되는 파일 목록입니다.

coverage.extension

타입: string | string[]
기본값: ['.js', '.cjs', '.mjs', '.ts', '.mts', '.tsx', '.jsx', '.vue', '.svelte', '.marko', '.astro']
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.extension=<extension>, --coverage.extension=<extension1> --coverage.extension=<extension2>

coverage.exclude

타입: string[]
기본값:

[
  'coverage/**',
  'dist/**',
  '**/node_modules/**',
  '**/[.]**',
  'packages/*/test?(s)/**',
  '**/*.d.ts',
  '**/virtual:*',
  '**/__x00__*',
  '**/\x00*',
  'cypress/**',
  'test?(s)/**',
  'test?(-*).?(c|m)[jt]s?(x)',
  '**/*{.,-}{test,spec,bench,benchmark}?(-d).?(c|m)[jt]s?(x)',
  '**/__tests__/**',
  '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build,eslint,prettier}.config.*',
  '**/vitest.{workspace,projects}.[jt]s?(on)',
  '**/.{eslint,mocha,prettier}rc.{?(c|m)js,yml}',
];

사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.exclude=<path>, --coverage.exclude=<path1> --coverage.exclude=<path2>

글로브 패턴으로 커버리지에서 제외되는 파일 목록입니다.

이 옵션은 모든 기본 옵션을 재정의합니다. 무시할 새 패턴을 추가할 때 기본 옵션을 확장하십시오:

import { coverageConfigDefaults, defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      exclude: ['**/custom-pattern/**', ...coverageConfigDefaults.exclude],
    },
  },
});

참고

Vitest는 테스트 파일 include 패턴을 coverage.exclude에 자동으로 추가합니다. 테스트 파일의 커버리지를 표시하는 것은 불가능합니다.

coverage.all

타입: boolean
기본값: true
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.all, --coverage.all=false

테스트되지 않은 파일을 포함하여 모든 파일을 보고서에 포함할지 여부입니다.

coverage.clean

타입: boolean
기본값: true
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.clean, --coverage.clean=false

테스트 실행 전에 커버리지 결과를 정리합니다.

coverage.cleanOnRerun

타입: boolean
기본값: true
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.cleanOnRerun, --coverage.cleanOnRerun=false

감시 재실행 시 커버리지 보고서를 정리합니다. 감시 모드에서 이전 실행의 커버리지 결과를 유지하려면 false로 설정하십시오.

coverage.reportsDirectory

타입: string
기본값: './coverage'
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.reportsDirectory=<path>

WARNING

coverage.clean이 활성화된 경우(기본값), Vitest는 테스트를 실행하기 전에 이 디렉토리를 삭제합니다.

커버리지 보고서를 작성할 디렉토리입니다.

HTML 리포터의 출력에서 커버리지 보고서를 미리 보려면 이 옵션을 HTML 보고서 디렉토리의 하위 디렉토리(예: ./html/coverage)로 설정해야 합니다.

coverage.reporter

타입: string | string[] | [string, {}][]
기본값: ['text', 'html', 'clover', 'json']
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.reporter=<reporter>, --coverage.reporter=<reporter1> --coverage.reporter=<reporter2>

사용할 커버리지 리포터입니다. 모든 리포터의 자세한 목록은 istanbul 문서를 참조하십시오. 리포터별 옵션에 대한 자세한 내용은 @types/istanbul-reporter를 참조하십시오.

리포터는 세 가지 유형을 가집니다:

단일 리포터: { reporter: 'html' }
옵션 없는 여러 리포터: { reporter: ['html', 'json'] }

리포터 옵션이 있는 단일 또는 여러 리포터:

{
  reporter: [
    ['lcov', { projectRoot: './src' }],
    ['json', { file: 'coverage.json' }],
    ['text'],
  ];
}

사용자 지정 커버리지 리포터를 전달할 수도 있습니다. 자세한 내용은 가이드 - 사용자 지정 커버리지 리포터를 참조하십시오.

{
  reporter: [
    // NPM 패키지 이름을 사용하여 리포터 지정
    '@vitest/custom-coverage-reporter',
    ['@vitest/custom-coverage-reporter', { someOption: true }],

    // 로컬 경로를 사용하여 리포터 지정
    '/absolute/path/to/custom-reporter.cjs',
    ['/absolute/path/to/custom-reporter.cjs', { someOption: true }],
  ];
}

Vitest UI에서 커버리지 보고서를 확인할 수 있습니다: 자세한 내용은 Vitest UI 커버리지를 참조하십시오.

coverage.reportOnFailure

타입: boolean
기본값: false
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.reportOnFailure, --coverage.reportOnFailure=false

테스트가 실패하더라도 커버리지 보고서를 생성합니다.

coverage.allowExternal

타입: boolean
기본값: false
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.allowExternal, --coverage.allowExternal=false

프로젝트 root 외부 파일의 커버리지를 수집합니다.

coverage.excludeAfterRemap 2.1.0+

타입: boolean
기본값: false
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.excludeAfterRemap, --coverage.excludeAfterRemap=false

커버리지가 원본 소스로 다시 매핑된 후 제외를 다시 적용합니다. 이는 소스 파일이 트랜스파일되어 비소스 파일의 소스 맵을 포함할 수 있는 경우에 유용합니다.

coverage.exclude 패턴과 일치하더라도 보고서에 파일이 표시되는 경우 이 옵션을 사용하십시오.

coverage.skipFull

타입: boolean
기본값: false
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.skipFull, --coverage.skipFull=false

100% 문, 분기 및 함수 커버리지를 가진 파일을 표시하지 않습니다.

coverage.thresholds

커버리지 임계값 옵션입니다.

임계값이 양수로 설정되면 필요한 최소 커버리지 백분율로 해석됩니다. 예를 들어, 라인 임계값을 90으로 설정하면 라인의 90%가 커버되어야 합니다.

임계값이 음수로 설정되면 허용되는 최대 미커버 항목 수로 처리됩니다. 예를 들어, 라인 임계값을 -10으로 설정하면 10개 이상의 라인이 미커버될 수 없습니다.

{
  coverage: {
    thresholds: {
      // 90% 함수 커버리지 필요
      functions: 90,

      // 10개 이상의 라인이 미커버되지 않도록 요구
      lines: -10,
    }
  }
}

coverage.thresholds.lines

타입: number
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.thresholds.lines=<number>

라인에 대한 전역 임계값입니다.

coverage.thresholds.functions

타입: number
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.thresholds.functions=<number>

함수에 대한 전역 임계값입니다.

coverage.thresholds.branches

타입: number
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.thresholds.branches=<number>

분기에 대한 전역 임계값입니다.

coverage.thresholds.statements

타입: number
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.thresholds.statements=<number>

문에 대한 전역 임계값입니다.

coverage.thresholds.perFile

타입: boolean
기본값: false
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.thresholds.perFile, --coverage.thresholds.perFile=false

파일별 임계값을 확인합니다.

coverage.thresholds.autoUpdate

타입: boolean
기본값: false
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.thresholds.autoUpdate=<boolean>

현재 커버리지가 구성된 임계값보다 좋을 때 lines, functions, branches, statements의 모든 임계값 값을 구성 파일로 업데이트합니다. 이 옵션은 커버리지가 향상될 때 임계값을 유지하는 데 도움이 됩니다.

coverage.thresholds.100

타입: boolean
기본값: false
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.thresholds.100, --coverage.thresholds.100=false

전역 임계값을 100으로 설정합니다. --coverage.thresholds.lines 100 --coverage.thresholds.functions 100 --coverage.thresholds.branches 100 --coverage.thresholds.statements 100의 단축키입니다.

coverage.thresholds[glob-pattern]

타입: { statements?: number functions?: number branches?: number lines?: number }
기본값: undefined
사용 가능한 프로바이더: 'v8' | 'istanbul'

글로브 패턴과 일치하는 파일에 대한 임계값을 설정합니다.

참고

Vitest는 글로브 패턴으로 커버되는 파일을 포함하여 모든 파일을 전역 커버리지 임계값에 포함합니다. 이는 Jest의 동작과 다릅니다.

{
  coverage: {
    thresholds: {
      // 모든 파일에 대한 임계값
      functions: 95,
      branches: 70,

      // 일치하는 글로브 패턴에 대한 임계값
      'src/utils/**.ts': {
        statements: 95,
        functions: 90,
        branches: 85,
        lines: 80,
      },

      // 이 패턴과 일치하는 파일은 라인 임계값만 설정됩니다.
      // 전역 임계값은 상속되지 않습니다.
      '**/math.ts': {
        lines: 100,
      }
    }
  }
}

coverage.thresholds[glob-pattern].100 2.1.0+

타입: boolean
기본값: false
사용 가능한 프로바이더: 'v8' | 'istanbul'

글로브 패턴과 일치하는 파일에 대한 임계값을 100으로 설정합니다.

{
  coverage: {
    thresholds: {
      // 모든 파일에 대한 임계값
      functions: 95,
      branches: 70,

      // 일치하는 글로브 패턴에 대한 임계값
      'src/utils/**.ts': { 100: true },
      '**/math.ts': { 100: true }
    }
  }
}

coverage.ignoreEmptyLines

타입: boolean
기본값: true (v1에서는 false)
사용 가능한 프로바이더: 'v8'
CLI: --coverage.ignoreEmptyLines=<boolean>

빈 줄, 주석 및 기타 비런타임 코드(예: Typescript 타입)를 무시합니다. experimentalAstAwareRemapping: false가 필요합니다.

이 옵션은 사용된 컴파일러가 트랜스파일된 코드에서 주석 및 기타 비런타임 코드를 제거하는 경우에만 작동합니다. 기본적으로 Vite는 ESBuild를 사용하여 .ts, .tsx, .jsx 파일에서 주석 및 Typescript 타입을 제거합니다.

ESBuild를 다른 파일에도 적용하려면 esbuild 옵션에 정의하십시오:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  esbuild: {
    // 코드 커버리지에서 주석을 제거하기 위해 모든 파일을 ESBuild로 트랜스파일합니다.
    // `test.coverage.ignoreEmptyLines`가 작동하려면 필요합니다:
    include: ['**/*.js', '**/*.jsx', '**/*.mjs', '**/*.ts', '**/*.tsx'],
  },
  test: {
    coverage: {
      provider: 'v8',
      ignoreEmptyLines: true,
    },
  },
});

coverage.experimentalAstAwareRemapping

타입: boolean
기본값: false
사용 가능한 프로바이더: 'v8'
CLI: --coverage.experimentalAstAwareRemapping=<boolean>

실험적인 AST 기반 분석으로 커버리지를 다시 매핑합니다. 기본 모드에 비해 더 정확한 결과를 제공합니다.

coverage.ignoreClassMethods

타입: string[]
기본값: []
사용 가능한 프로바이더: 'istanbul'
CLI: --coverage.ignoreClassMethods=<method>

커버리지에서 무시할 클래스 메서드 이름의 배열로 설정합니다. 자세한 내용은 istanbul 문서를 참조하십시오.

coverage.watermarks

타입:

{
  statements?: [number, number],
  functions?: [number, number],
  branches?: [number, number],
  lines?: [number, number]
}

기본값:

{
  statements: [50, 80],
  functions: [50, 80],
  branches: [50, 80],
  lines: [50, 80]
}

사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.watermarks.statements=50,80, --coverage.watermarks.branches=50,80

문, 라인, 분기 및 함수에 대한 워터마크입니다. 자세한 내용은 istanbul 문서를 참조하십시오.

coverage.processingConcurrency

타입: boolean
기본값: Math.min(20, os.availableParallelism?.() ?? os.cpus().length)
사용 가능한 프로바이더: 'v8' | 'istanbul'
CLI: --coverage.processingConcurrency=<number>

커버리지 결과를 처리할 때 사용되는 동시성 제한입니다.

coverage.customProviderModule

타입: string
사용 가능한 프로바이더: 'custom'
CLI: --coverage.customProviderModule=<path or module name>

사용자 지정 커버리지 프로바이더 모듈의 모듈 이름 또는 경로를 지정합니다. 자세한 내용은 가이드 - 사용자 지정 커버리지 프로바이더를 참조하십시오.

testNamePattern*

타입 string | RegExp
CLI: -t <pattern>, --testNamePattern=<pattern>, --test-name-pattern=<pattern>

패턴과 일치하는 전체 이름을 가진 테스트를 실행합니다. 이 속성에 OnlyRunThis를 추가하면 테스트 이름에 OnlyRunThis라는 단어가 포함되지 않은 테스트는 건너뛰게 됩니다.

import { expect, test } from 'vitest';

// 실행
test('OnlyRunThis', () => {
  expect(true).toBe(true);
});

// 건너뛰기
test('doNotRun', () => {
  expect(true).toBe(true);
});

open*

타입: boolean
기본값: !process.env.CI
CLI: --open, --open=false

Vitest UI (WIP) 열기.

api

타입: boolean | number
기본값: false
CLI: --api, --api.port, --api.host, --api.strictPort

포트를 수신하고 API를 제공합니다. true로 설정하면 기본 포트는 51204입니다.

browser 실험적

기본값: { enabled: false }
CLI: --browser=<name>, --browser.name=chrome --browser.headless

브라우저 테스트 실행을 위한 구성입니다. "브라우저 구성 참조" 문서를 참조하십시오.

WARNING

이것은 실험적인 기능입니다. 호환성이 깨지는 변경 사항이 SemVer를 따르지 않을 수 있으므로, 사용할 때 Vitest 버전을 고정하십시오.

clearMocks

타입: boolean
기본값: false

각 테스트 전에 모든 스파이에 .mockClear()를 호출합니다. 이렇게 하면 모의 구현에 영향을 주지 않고 모의 기록이 지워집니다.

mockReset

타입: boolean
기본값: false

각 테스트 전에 모든 스파이에 .mockReset()을 호출합니다. 이렇게 하면 모의 기록이 지워지고 각 구현이 원래대로 재설정됩니다.

restoreMocks

타입: boolean
기본값: false

각 테스트 전에 모든 스파이에 .mockRestore()를 호출합니다. 이렇게 하면 모의 기록이 지워지고 각 구현이 원래대로 복원되며, 스파이된 객체의 원래 디스크립터가 복원됩니다.

unstubEnvs

타입: boolean
기본값: false

각 테스트 전에 vi.unstubAllEnvs를 호출합니다.

unstubGlobals

타입: boolean
기본값: false

각 테스트 전에 vi.unstubAllGlobals를 호출합니다.

testTransformMode

타입: { web?, ssr? }

글로브 패턴과 일치하는 테스트 내부에서 가져온 모든 모듈에 대한 변환 방법을 결정합니다. 기본적으로 환경에 따라 달라집니다. 예를 들어, JSDOM 환경을 가진 테스트는 ssr: false 플래그로 모든 파일을 처리하고 Node 환경을 가진 테스트는 ssr: true로 모든 모듈을 처리합니다.

testTransformMode.ssr

타입: string[]
기본값: []

지정된 테스트 내부의 모든 모듈에 대해 SSR 변환 파이프라인을 사용합니다.
Vite 플러그인은 해당 파일을 처리할 때 ssr: true 플래그를 받습니다.

testTransformMode.web

타입: string[]
기본값: []

먼저 일반 변환 파이프라인(브라우저 대상)을 수행한 다음, Node에서 코드를 실행하기 위해 SSR 재작성을 수행합니다.
Vite 플러그인은 해당 파일을 처리할 때 ssr: false 플래그를 받습니다.

snapshotFormat*

타입: PrettyFormatOptions

스냅샷 테스트를 위한 형식 옵션입니다. 이 옵션은 pretty-format으로 전달됩니다.

TIP

주의: 이 객체의 plugins 필드는 무시됩니다.

pretty-format 플러그인을 통해 스냅샷 직렬 변환기를 확장해야 하는 경우, expect.addSnapshotSerializer API 또는 snapshotSerializers 옵션을 사용하십시오.

snapshotSerializers*

타입: string[]
기본값: []

스냅샷 테스트를 위한 스냅샷 직렬 변환기 모듈 경로 목록으로, 사용자 지정 스냅샷 직렬 변환기를 추가하려는 경우 유용합니다. 자세한 내용은 사용자 지정 직렬 변환기를 참조하십시오.

resolveSnapshotPath*

타입: (testPath: string, snapExtension: string, context: { config: SerializedConfig }) => string
기본값: 스냅샷 파일을 __snapshots__ 디렉토리에 저장합니다.

기본 스냅샷 경로 재정의. 예를 들어, 테스트 파일 옆에 스냅샷을 저장하려면:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    resolveSnapshotPath: (testPath, snapExtension) => testPath + snapExtension,
  },
});

allowOnly

타입: boolean
기본값: !process.env.CI
CLI: --allowOnly, --allowOnly=false

only로 표시된 테스트 및 스위트를 허용합니다.

dangerouslyIgnoreUnhandledErrors*

타입: boolean
기본값: false
CLI: --dangerouslyIgnoreUnhandledErrors --dangerouslyIgnoreUnhandledErrors=false

발생하는 처리되지 않은 오류를 무시합니다.

passWithNoTests*

타입: boolean
기본값: false
CLI: --passWithNoTests, --passWithNoTests=false

테스트가 발견되지 않아도 Vitest는 실패하지 않습니다.

logHeapUsage

타입: boolean
기본값: false
CLI: --logHeapUsage, --logHeapUsage=false

각 테스트 후 힙 사용량 표시. 메모리 누수 디버깅에 유용합니다.

css

타입: boolean | { include?, exclude?, modules? }

CSS 처리 여부 구성. 제외되면 CSS 파일은 후속 처리를 우회하기 위해 빈 문자열로 대체됩니다. CSS 모듈은 런타임에 영향을 미치지 않도록 프록시를 반환합니다.

css.include

타입: RegExp | RegExp[]
기본값: []

실제 CSS를 반환하고 Vite 파이프라인에 의해 처리되어야 하는 파일에 대한 RegExp 패턴입니다.

TIP

모든 CSS 파일을 처리하려면 /.+/를 사용하십시오.

css.exclude

타입: RegExp | RegExp[]
기본값: []

빈 CSS 파일을 반환할 파일에 대한 RegExp 패턴입니다.

css.modules

타입: { classNameStrategy? }
기본값: {}

css.modules.classNameStrategy

타입: 'stable' | 'scoped' | 'non-scoped'
기본값: 'stable'

CSS 파일을 처리하기로 결정한 경우, CSS 모듈 내부의 클래스 이름이 범위 지정되어야 하는지 여부를 구성할 수 있습니다. 다음 옵션 중 하나를 선택할 수 있습니다:

stable: 클래스 이름은 _${name}_${hashedFilename}으로 생성됩니다. 이는 CSS 내용이 변경되어도 생성된 클래스는 동일하게 유지되지만, 파일 이름이 수정되거나 파일이 다른 폴더로 이동하면 변경됨을 의미합니다. 이 설정은 스냅샷 기능을 사용하는 경우 유용합니다.
scoped: 클래스 이름은 일반적으로 생성되며, css.modules.generateScopedName 메서드가 있고 CSS 처리가 활성화된 경우 이를 존중합니다. 기본적으로 파일 이름은 _${name}_${hash}로 생성되며, 여기서 해시는 파일 이름과 파일 내용을 포함합니다.
non-scoped: 클래스 이름은 해시되지 않습니다.

WARNING

기본적으로 Vitest는 프록시를 내보내 CSS 모듈 처리를 우회합니다. 클래스에서 CSS 속성에 의존하는 경우 include 옵션을 사용하여 CSS 처리를 활성화해야 합니다.

maxConcurrency

타입: number
기본값: 5
CLI: --max-concurrency=10, --maxConcurrency=10

test.concurrent로 표시된 테스트가 동시에 실행될 수 있는 수입니다.

이 제한을 초과하는 테스트는 사용 가능한 슬롯이 나타날 때까지 대기열에 추가됩니다.

cache*

타입: false
CLI: --no-cache, --cache=false

캐시 기능을 비활성화하려면 이 옵션을 사용하십시오. 현재 Vitest는 더 길고 실패한 테스트를 먼저 실행하기 위해 테스트 결과에 대한 캐시를 저장합니다.

캐시 디렉토리는 Vite의 cacheDir 옵션으로 제어됩니다:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  cacheDir: 'custom-folder/.vitest',
});

process.env.VITEST를 사용하여 Vitest에 대해서만 디렉토리를 제한할 수 있습니다:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  cacheDir: process.env.VITEST ? 'custom-folder/.vitest' : undefined,
});

sequence

타입: { sequencer?, shuffle?, seed?, hooks?, setupFiles?, groupOrder }

테스트 정렬 옵션입니다.

점 표기법으로 CLI에 시퀀스 옵션을 제공할 수 있습니다:

npx vitest --sequence.shuffle --sequence.seed=1000

sequence.sequencer*

타입: TestSequencerConstructor
기본값: BaseSequencer

샤딩 및 정렬을 위한 메서드를 정의하는 사용자 지정 클래스입니다. sort 및 shard 메서드 중 하나만 재정의해야 하는 경우 vitest/node의 BaseSequencer를 확장할 수 있지만, 둘 다 존재해야 합니다.

샤딩은 정렬 전에 발생하며, --shard 옵션이 제공된 경우에만 발생합니다.

sequencer.groupOrder가 지정되면, 시퀀서는 각 그룹 및 풀에 대해 한 번씩 호출됩니다.

groupOrder 3.2.0+

타입: number
기본값: 0

여러 프로젝트를 사용할 때 이 프로젝트가 테스트를 실행하는 순서를 제어합니다.

동일한 그룹 순서 번호를 가진 프로젝트는 함께 실행되며, 그룹은 가장 낮은 순서부터 가장 높은 순서로 실행됩니다.
이 옵션을 설정하지 않으면 모든 프로젝트가 병렬로 실행됩니다.
여러 프로젝트가 동일한 그룹 순서를 사용하는 경우, 동시에 실행됩니다.

이 설정은 프로젝트가 실행되는 순서에만 영향을 미치며, 프로젝트 내 테스트의 순서에는 영향을 미치지 않습니다. 테스트 격리 또는 프로젝트 내 테스트 순서를 제어하려면 isolate 및 sequence.sequencer 옵션을 사용하십시오.

예시

이 예시를 고려하십시오:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          name: 'slow',
          sequence: {
            groupOrder: 0,
          },
        },
      },
      {
        test: {
          name: 'fast',
          sequence: {
            groupOrder: 0,
          },
        },
      },
      {
        test: {
          name: 'flaky',
          sequence: {
            groupOrder: 1,
          },
        },
      },
    ],
  },
});

이 프로젝트의 테스트는 다음 순서로 실행됩니다:

 0. slow  |
          |> 함께 실행
 0. fast  |

 1. flaky |> slow와 fast가 끝난 후 단독으로 실행

sequence.shuffle

타입: boolean | { files?, tests? }
기본값: false
CLI: --sequence.shuffle, --sequence.shuffle=false

파일과 테스트를 무작위로 실행하려면 이 옵션 또는 CLI 인수 --sequence.shuffle를 사용하여 활성화할 수 있습니다.

Vitest는 일반적으로 캐시를 사용하여 테스트를 정렬하므로 오래 실행되는 테스트가 더 일찍 시작됩니다. 이렇게 하면 테스트 실행 속도가 빨라집니다. 파일과 테스트가 무작위 순서로 실행되면 이러한 성능 향상을 잃게 되지만, 이전에 실행된 다른 테스트에 우연히 의존하는 테스트를 추적하는 데 유용할 수 있습니다.

sequence.shuffle.files

타입: boolean
기본값: false
CLI: --sequence.shuffle.files, --sequence.shuffle.files=false

파일을 무작위화할지 여부입니다. 이 옵션을 활성화하면 오래 실행되는 테스트가 더 일찍 시작되지 않을 수 있습니다.

sequence.shuffle.tests

타입: boolean
기본값: false
CLI: --sequence.shuffle.tests, --sequence.shuffle.tests=false

테스트를 무작위화할지 여부입니다.

sequence.concurrent

타입: boolean
기본값: false
CLI: --sequence.concurrent, --sequence.concurrent=false

테스트를 병렬로 실행하려면 이 옵션 또는 CLI 인수 --sequence.concurrent를 사용하여 활성화할 수 있습니다.

sequence.seed*

타입: number
기본값: Date.now()
CLI: --sequence.seed=1000

테스트가 무작위 순서로 실행되는 경우 무작위화 시드를 설정합니다.

sequence.hooks

타입: 'stack' | 'list' | 'parallel'
기본값: 'stack'
CLI: --sequence.hooks=<value>

훅 실행 순서 변경.

stack은 "after" 훅을 역순으로 정렬하고, "before" 훅은 정의된 순서대로 실행됩니다.
list는 모든 훅을 정의된 순서대로 정렬합니다.
parallel은 단일 그룹의 훅을 병렬로 실행합니다 (부모 스위트의 훅은 여전히 현재 스위트의 훅보다 먼저 실행됩니다).

TIP

이 옵션은 onTestFinished에 영향을 미치지 않습니다. 항상 역순으로 호출됩니다.

sequence.setupFiles

타입: 'list' | 'parallel'
기본값: 'parallel'
CLI: --sequence.setupFiles=<value>

설정 파일 실행 순서 변경.

list는 설정 파일을 정의된 순서대로 실행합니다.
parallel은 설정 파일을 병렬로 실행합니다.

typecheck

타입 검사 테스트 환경 구성 옵션입니다.

typecheck.enabled

타입: boolean
기본값: false
CLI: --typecheck, --typecheck.enabled

정규 테스트와 함께 타입 검사를 활성화합니다.

typecheck.only

타입: boolean
기본값: false
CLI: --typecheck.only

타입 검사가 활성화된 경우 타입 검사 테스트만 실행합니다. CLI를 사용할 때 이 옵션은 자동으로 타입 검사를 활성화합니다.

typecheck.checker

타입: 'tsc' | 'vue-tsc' | string
기본값: tsc

타입 검사에 사용할 도구입니다. Vitest는 타입에 따라 더 쉬운 구문 분석을 위해 특정 매개변수로 프로세스를 생성합니다. 검사기는 tsc와 동일한 출력 형식을 구현해야 합니다.

타입 검사기를 사용하려면 패키지가 설치되어 있어야 합니다:

tsc는 typescript 패키지가 필요합니다.
vue-tsc는 vue-tsc 패키지가 필요합니다.

tsc --noEmit --pretty false와 동일한 출력을 생성하는 사용자 지정 바이너리 또는 명령 이름의 경로를 전달할 수도 있습니다.

typecheck.include

타입: string[]
기본값: ['**/*.{test,spec}-d.?(c|m)[jt]s?(x)']

테스트 파일로 처리될 파일에 대한 글로브 패턴입니다.

typecheck.exclude

타입: string[]
기본값: ['**/node_modules/**', '**/dist/**', '**/cypress/**', '**/.{idea,git,cache,output,temp}/**']

테스트 파일로 처리되어서는 안 되는 파일에 대한 글로브 패턴입니다.

typecheck.allowJs

타입: boolean
기본값: false

@ts-check 주석이 있는 JS 파일을 확인합니다. tsconfig에서 활성화한 경우 이 옵션은 이를 덮어쓰지 않습니다.

typecheck.ignoreSourceErrors

타입: boolean
기본값: false

Vitest가 테스트 파일 외부에서 오류를 발견하더라도 실패하지 않습니다. 이렇게 하면 비테스트 오류는 전혀 표시되지 않습니다.

기본적으로 Vitest가 소스 오류를 발견하면 테스트 스위트가 실패합니다.

typecheck.tsconfig

타입: string
기본값: 가장 가까운 tsconfig.json을 찾으려고 시도합니다.

프로젝트 루트에 대한 상대 경로로 사용자 지정 tsconfig 경로입니다.

typecheck.spawnTimeout

타입: number
기본값: 10_000

타입 검사기를 생성하는 데 걸리는 최소 시간(밀리초)입니다.

slowTestThreshold*

타입: number
기본값: 300
CLI: --slow-test-threshold=<number>, --slowTestThreshold=<number>

테스트 또는 스위트가 느리다고 간주되어 결과에 보고되는 밀리초 수입니다.

chaiConfig

타입: { includeStack?, showDiff?, truncateThreshold? }
기본값: { includeStack: false, showDiff: true, truncateThreshold: 40 }

Chai config와 동일합니다.

chaiConfig.includeStack

타입: boolean
기본값: false

Assertion 오류 메시지에 스택 추적을 포함할지 여부에 영향을 미칩니다. 기본값인 false는 오류 메시지에서 스택 추적을 억제합니다.

chaiConfig.showDiff

타입: boolean
기본값: true

발생한 AssertionErrors에 showDiff 플래그를 포함할지 여부에 영향을 미칩니다. false는 항상 false입니다. true는 어설션이 diff를 표시하도록 요청했을 때 true입니다.

chaiConfig.truncateThreshold

타입: number
기본값: 40

어설션 오류에서 실제 값과 예상 값의 길이 임계값을 설정합니다. 이 임계값을 초과하면(예: 큰 데이터 구조의 경우) 값은 [ Array(3) ] 또는 { Object (prop1, prop2) }와 같은 것으로 대체됩니다. 잘라내기를 완전히 비활성화하려면 0으로 설정하십시오.

이 구성 옵션은 test.each 제목 및 어설션 오류 메시지 내부의 값 잘라내기에 영향을 미칩니다.

bail

타입: number
기본값: 0
CLI: --bail=<value>

주어진 수의 테스트가 실패하면 테스트 실행을 중지합니다.

기본적으로 Vitest는 일부 테스트가 실패하더라도 모든 테스트 케이스를 실행합니다. 이는 100% 성공적인 빌드에만 관심이 있고 테스트 실패 시 가능한 한 빨리 테스트 실행을 중지하려는 CI 빌드에는 바람직하지 않을 수 있습니다. bail 옵션은 실패가 발생했을 때 더 많은 테스트가 실행되는 것을 방지하여 CI 실행 속도를 높이는 데 사용할 수 있습니다.

retry

타입: number
기본값: 0
CLI: --retry=<value>

테스트가 실패하면 지정된 횟수만큼 다시 시도합니다.

onConsoleLog*

타입: (log: string, type: 'stdout' | 'stderr') => boolean | void

테스트에서 console.log에 대한 사용자 지정 핸들러입니다. false를 반환하면 Vitest는 로그를 콘솔에 출력하지 않습니다.

타사 라이브러리의 로그를 필터링하는 데 유용할 수 있습니다.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    onConsoleLog(log: string, type: 'stdout' | 'stderr'): boolean | void {
      return !(log === 'message from third party library' && type === 'stdout');
    },
  },
});

onStackTrace*

타입: (error: Error, frame: ParsedStack) => boolean | void

오류를 처리할 때 각 스택 추적의 각 프레임에 필터링 함수를 적용합니다. 첫 번째 인수 error는 표준 Error와 동일한 속성을 가진 객체이지만 실제 인스턴스는 아닙니다.

타사 라이브러리의 스택 추적 프레임을 필터링하는 데 유용할 수 있습니다.

import type { ParsedStack } from 'vitest';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    onStackTrace(error: Error, { file }: ParsedStack): boolean | void {
      // ReferenceError가 발생하면 전체 스택을 표시합니다.
      if (error.name === 'ReferenceError') {
        return;
      }

      // 타사 라이브러리의 모든 프레임을 거부합니다.
      if (file.includes('node_modules')) {
        return false;
      }
    },
  },
});

diff

타입: string
CLI: --diff=<path>

DiffOptions 객체 또는 DiffOptions를 내보내는 모듈의 경로입니다. diff 표시를 사용자 지정하려는 경우 유용합니다.

예를 들어, 구성 객체로:

import { defineConfig } from 'vitest/config';
import c from 'picocolors';

export default defineConfig({
  test: {
    diff: {
      aIndicator: c.bold('--'),
      bIndicator: c.bold('++'),
      omitAnnotationLines: true,
    },
  },
});

또는 모듈로:

vitest.config.jsvitest.diff.ts

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    diff: './vitest.diff.ts',
  },
});

import type { DiffOptions } from 'vitest';
import c from 'picocolors';

export default {
  aIndicator: c.bold('--'),
  bIndicator: c.bold('++'),
  omitAnnotationLines: true,
} satisfies DiffOptions;

diff.expand

타입: boolean
기본값: true
CLI: --diff.expand=false

모든 공통 라인을 확장합니다.

diff.truncateThreshold

타입: number
기본값: 0
CLI: --diff.truncateThreshold=<path>

표시될 diff 결과의 최대 길이입니다. 이 임계값을 초과하는 diff는 잘립니다. 기본값 0에서는 잘라내기가 적용되지 않습니다.

diff.truncateAnnotation

타입: string
기본값: '... Diff result is truncated'
CLI: --diff.truncateAnnotation=<annotation>

diff 결과가 잘릴 때 끝에 출력되는 주석입니다.

diff.truncateAnnotationColor

타입: DiffOptionsColor = (arg: string) => string
기본값: noColor = (string: string): string => string

잘라내기 주석의 색상이며, 기본값은 색상 없이 출력됩니다.

diff.printBasicPrototype

타입: boolean
기본값: false

diff 출력에서 기본 프로토타입 Object 및 Array를 인쇄합니다.

diff.maxDepth

타입: number
기본값: 20 (다른 유형을 비교할 때는 8)

중첩된 객체를 인쇄할 때 재귀할 깊이를 제한합니다.

fakeTimers

타입: FakeTimerInstallOpts

vi.useFakeTimers()를 사용할 때 Vitest가 @sinon/fake-timers로 전달할 옵션입니다.

fakeTimers.now

타입: number | Date
기본값: Date.now()

지정된 Unix epoch로 가짜 타이머를 설치합니다.

fakeTimers.toFake

타입: ('setTimeout' | 'clearTimeout' | 'setImmediate' | 'clearImmediate' | 'setInterval' | 'clearInterval' | 'Date' | 'nextTick' | 'hrtime' | 'requestAnimationFrame' | 'cancelAnimationFrame' | 'requestIdleCallback' | 'cancelIdleCallback' | 'performance' | 'queueMicrotask')[]
기본값: nextTick 및 queueMicrotask를 제외한 전역적으로 사용 가능한 모든 것

가짜로 만들 전역 메서드 및 API 이름의 배열입니다.

setTimeout() 및 nextTick()만 모의하려면 이 속성을 ['setTimeout', 'nextTick']으로 지정하십시오.

nextTick 모의는 --pool=forks를 사용하여 node:child_process 내부에서 Vitest를 실행할 때 지원되지 않습니다. NodeJS는 node:child_process 내부에서 process.nextTick을 내부적으로 사용하며, 모의될 때 중단됩니다. --pool=threads로 Vitest를 실행할 때 nextTick 모의는 지원됩니다.

fakeTimers.loopLimit

타입: number
기본값: 10_000

vi.runAllTimers()를 호출할 때 실행될 타이머의 최대 수입니다.

fakeTimers.shouldAdvanceTime

타입: boolean
기본값: false

@sinonjs/fake-timers에게 실제 시스템 시간 변화를 기반으로 모의 시간을 자동으로 증가시키도록 지시합니다(예: 실제 시스템 시간에서 20ms 변화마다 모의 시간이 20ms 증가합니다).

fakeTimers.advanceTimeDelta

타입: number
기본값: 20

shouldAdvanceTime: true와 함께 사용할 때만 관련이 있습니다. 실제 시스템 시간에서 advanceTimeDelta ms 변화마다 모의 시간을 advanceTimeDelta ms씩 증가시킵니다.

fakeTimers.shouldClearNativeTimers

타입: boolean
기본값: true

가짜 타이머에게 "네이티브"(즉, 가짜가 아닌) 타이머를 해당 핸들러에 위임하여 지우도록 지시합니다. 비활성화하면 가짜 타이머 세션을 시작하기 전에 타이머가 존재했던 경우 잠재적으로 예상치 못한 동작이 발생할 수 있습니다.

workspace*

DEPRECATED

이 옵션은 더 이상 사용되지 않으며 다음 주요 버전에서 제거될 예정입니다. 대신 projects를 사용하십시오.

타입: string | TestProjectConfiguration[]
CLI: --workspace=./file.js
기본값: 구성 파일 또는 루트에 가까운 vitest.{workspace,projects}.{js,ts,json}

루트에 대한 상대 경로로 워크스페이스 구성 파일의 경로입니다.

Vitest 3부터 루트 구성에서 워크스페이스 배열을 정의할 수도 있습니다. 구성에서 workspace가 수동으로 정의되면 Vitest는 루트의 vitest.workspace 파일을 무시합니다.

projects*

타입: TestProjectConfiguration[]
기본값: []

프로젝트 배열입니다.

isolate

타입: boolean
기본값: true
CLI: --no-isolate, --isolate=false

격리된 환경에서 테스트를 실행합니다. 이 옵션은 vmThreads 및 vmForks 풀에는 영향을 미치지 않습니다.

이 옵션을 비활성화하면 코드가 부작용에 의존하지 않는 경우(node 환경을 가진 프로젝트의 경우 일반적으로 그렇습니다) 성능이 향상될 수 있습니다.

TIP

poolOptions 속성을 사용하여 특정 풀에 대한 격리를 비활성화할 수 있습니다.

includeTaskLocation

타입: boolean
기본값: false

Vitest API가 리포터에서 작업을 수신할 때 location 속성을 포함해야 하는지 여부입니다. 테스트가 많은 경우 약간의 성능 저하가 발생할 수 있습니다.

location 속성은 원본 파일의 test 또는 describe 위치에 해당하는 column 및 line 값을 가집니다.

이 옵션은 명시적으로 비활성화하지 않고 Vitest를 다음으로 실행하는 경우 자동으로 활성화됩니다:

Vitest UI
또는 headless 모드 없이 브라우저 모드를 사용하는 경우
또는 HTML 리포터를 사용하는 경우

TIP

이 옵션은 이에 의존하는 사용자 지정 코드를 사용하지 않는 경우 아무런 영향을 미치지 않습니다.

snapshotEnvironment

타입: string

사용자 지정 스냅샷 환경 구현의 경로입니다. Node.js API를 지원하지 않는 환경에서 테스트를 실행하는 경우 유용합니다. 이 옵션은 브라우저 러너에는 영향을 미치지 않습니다.

이 객체는 SnapshotEnvironment 형태를 가져야 하며 스냅샷 파일을 해결하고 읽고 쓰는 데 사용됩니다:

export interface SnapshotEnvironment {
  getVersion: () => string;
  getHeader: () => string;
  resolvePath: (filepath: string) => Promise<string>;
  resolveRawPath: (testPath: string, rawPath: string) => Promise<string>;
  saveSnapshotFile: (filepath: string, snapshot: string) => Promise<void>;
  readSnapshotFile: (filepath: string) => Promise<string | null>;
  removeSnapshotFile: (filepath: string) => Promise<void>;
}

API의 일부만 덮어쓰려면 vitest/snapshot 진입점에서 기본 VitestSnapshotEnvironment를 확장할 수 있습니다.

WARNING

이것은 낮은 수준의 옵션이며 기본 Node.js API에 액세스할 수 없는 고급 경우에만 사용해야 합니다.

스냅샷 기능을 구성하기만 하면 되는 경우 snapshotFormat 또는 resolveSnapshotPath 옵션을 사용하십시오.

env

타입: Partial<NodeJS.ProcessEnv>

테스트 중 process.env 및 import.meta.env에서 사용할 수 있는 환경 변수입니다. 이 변수는 메인 프로세스(예: globalSetup)에서는 사용할 수 없습니다.

expect

타입: ExpectOptions

expect.requireAssertions

타입: boolean
기본값: false

모든 테스트 시작 시 expect.hasAssertions()를 호출하는 것과 동일합니다. 이렇게 하면 어떤 테스트도 우연히 통과하지 않도록 합니다.

TIP

이것은 Vitest의 expect에서만 작동합니다. assert 또는 .should 어설션을 사용하는 경우, 이는 계산되지 않으며 어설션 부족으로 인해 테스트가 실패합니다.

vi.setConfig({ expect: { requireAssertions: false } })를 호출하여 이 값을 변경할 수 있습니다. 이 구성은 vi.resetConfig가 수동으로 호출될 때까지 모든 후속 expect 호출에 적용됩니다.

expect.poll

expect.poll에 대한 전역 구성 옵션입니다. 이는 expect.poll(condition, options)에 전달할 수 있는 것과 동일한 옵션입니다.

expect.poll.interval

타입: number
기본값: 50

폴링 간격(밀리초)입니다.

expect.poll.timeout

타입: number
기본값: 1000

폴링 시간 초과(밀리초)입니다.

printConsoleTrace

타입: boolean
기본값: false

모든 console 메서드를 호출할 때 항상 콘솔 추적을 인쇄합니다. 디버깅에 유용합니다.

attachmentsDir 3.2.0+

타입: string
기본값: '.vitest-attachments'

프로젝트 루트에 대한 상대 경로로 context.annotate에 의해 생성된 첨부 파일을 저장할 디렉토리 경로입니다.

Vitest 구성하기 ​

include ​

exclude ​

includeSource ​

name ​

server ​

server.sourcemap ​

server.debug ​

server.debug.dumpModules ​

server.debug.loadDumppedModules ​

server.deps ​

server.deps.external ​

server.deps.inline ​

server.deps.fallbackCJS ​

server.deps.cacheDir ​

deps ​

deps.optimizer ​

deps.optimizer.{mode}.enabled ​

deps.web ​

deps.web.transformAssets ​

deps.web.transformCss ​

deps.web.transformGlobPattern ​

deps.interopDefault ​

deps.moduleDirectories ​

runner ​

benchmark ​

benchmark.include ​

benchmark.exclude ​

benchmark.includeSource ​

benchmark.reporters ​

benchmark.outputFile ​

benchmark.outputJson ​

benchmark.compare ​

alias ​

globals ​

environment ​

environmentOptions ​

environmentMatchGlobs ​

poolMatchGlobs ​

update* ​

watch* ​

watchTriggerPatterns 3.2.0+ * ​

root ​

dir ​

reporters* ​

outputFile* ​

pool* ​

threads* ​

forks* ​

vmThreads* ​

vmForks* ​

poolOptions* ​

poolOptions.threads ​

poolOptions.threads.maxThreads* ​

poolOptions.threads.minThreads* ​

poolOptions.threads.singleThread ​

poolOptions.threads.useAtomics* ​

poolOptions.threads.isolate ​

poolOptions.threads.execArgv* ​

poolOptions.forks ​

poolOptions.forks.maxForks* ​

poolOptions.forks.minForks* ​

poolOptions.forks.isolate ​

poolOptions.forks.singleFork ​

poolOptions.forks.execArgv* ​

poolOptions.vmThreads ​

poolOptions.vmThreads.maxThreads* ​

poolOptions.vmThreads.minThreads* ​

poolOptions.vmThreads.memoryLimit* ​

poolOptions.vmThreads.useAtomics* ​

poolOptions.vmThreads.execArgv* ​

poolOptions.vmForks* ​

poolOptions.vmForks.maxForks* ​

poolOptions.vmForks.minForks* ​

poolOptions.vmForks.memoryLimit* ​

poolOptions.vmForks.execArgv* ​

fileParallelism* ​

maxWorkers* ​

minWorkers* ​

testTimeout ​

Vitest 구성하기

include

exclude

includeSource

name

server

server.sourcemap

server.debug

server.debug.dumpModules

server.debug.loadDumppedModules

server.deps

server.deps.external

server.deps.inline

server.deps.fallbackCJS

server.deps.cacheDir

deps

deps.optimizer

deps.optimizer.{mode}.enabled

deps.web

deps.web.transformAssets

deps.web.transformCss

deps.web.transformGlobPattern

deps.interopDefault

deps.moduleDirectories

runner

benchmark

benchmark.include

benchmark.exclude

benchmark.includeSource

benchmark.reporters

benchmark.outputFile

benchmark.outputJson

benchmark.compare

alias

globals

environment

environmentOptions

environmentMatchGlobs

poolMatchGlobs

update*

watch*

watchTriggerPatterns 3.2.0+ *

root

dir

reporters*

outputFile*

pool*

threads*

forks*

vmThreads*

vmForks*

poolOptions*

poolOptions.threads

poolOptions.threads.maxThreads*

poolOptions.threads.minThreads*

poolOptions.threads.singleThread

poolOptions.threads.useAtomics*

poolOptions.threads.isolate

poolOptions.threads.execArgv*

poolOptions.forks

poolOptions.forks.maxForks*

poolOptions.forks.minForks*

poolOptions.forks.isolate

poolOptions.forks.singleFork

poolOptions.forks.execArgv*

poolOptions.vmThreads

poolOptions.vmThreads.maxThreads*

poolOptions.vmThreads.minThreads*

poolOptions.vmThreads.memoryLimit*

poolOptions.vmThreads.useAtomics*

poolOptions.vmThreads.execArgv*

poolOptions.vmForks*

poolOptions.vmForks.maxForks*

poolOptions.vmForks.minForks*

poolOptions.vmForks.memoryLimit*

poolOptions.vmForks.execArgv*

fileParallelism*

maxWorkers*

minWorkers*

testTimeout