Vitest 설정하기

구성

vitest는 Vite 앱의 플러그인 및 설정과 일치하도록 루트 디렉터리에 vite.config.ts 파일이 있는 경우 해당 파일을 읽어 설정을 적용합니다. 테스트에 다른 설정을 사용하거나 메인 앱이 Vite를 사용하지 않는 경우에는 다음 방법 중 하나를 선택할 수 있습니다.

• vitest.config.ts 파일을 생성합니다. 이 파일은 vite.config.ts 파일보다 우선 순위가 높아 vite.config.ts의 설정을 덮어씁니다.
• CLI에 --config 옵션을 전달합니다 (예: vitest --config ./path/to/vitest.config.ts).
• vite.config.ts 파일에서 조건에 따라 다른 설정을 적용하기 위해 process.env.VITEST 또는 defineConfig의 mode 속성(재정의되지 않은 경우 test/benchmark로 설정됨)을 사용합니다.

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

vite에서 defineConfig를 사용하는 경우:

/// <reference types="vitest" />
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/*'],
    },
  })
);

WARNING

mergeConfig 도우미 함수는 Vitest v0.30.0부터 사용할 수 있습니다. 이전 버전을 사용하는 경우 vite에서 직접 가져올 수 있습니다.

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

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

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

옵션

TIP

다음 옵션 외에도 Vite의 모든 설정 옵션을 사용할 수 있습니다. 예를 들어 전역 변수를 정의하는 define 또는 별칭을 정의하는 resolve.alias 등이 있습니다.

TIP

워크스페이스 프로젝트 설정 내에서 지원되지 않는 모든 설정 옵션에는 * 기호가 표시됩니다.

include

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

테스트 실행에 포함할 파일을 glob 패턴으로 지정합니다.

exclude

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

테스트 실행에서 제외할 파일을 glob 패턴으로 지정합니다.

includeSource

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

소스 코드 내에 있는 테스트 파일을 glob 패턴으로 지정합니다.

이 옵션이 정의되면 Vitest는 파일 내에 import.meta.vitest가 있는 모든 파일을 실행합니다.

server

• 타입: { sourcemap?, deps?, ... }
• 버전: Vitest 0.34.0 이후

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.js 자체 모듈로 처리하도록 설정하는 것을 의미합니다. 외부화된 종속성은 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가 인라인 모듈로 처리할 모듈을 지정합니다. 이는 Node가 처리할 수 없는 ESM 형식으로 .js 파일을 제공하는 패키지를 처리하는 데 유용할 수 있습니다.

true인 경우 모든 종속성이 인라인됩니다. ssr.noExternal에 지정된 모든 종속성은 기본적으로 인라인됩니다.

server.deps.fallbackCJS

• 타입 boolean
• 기본값: false

종속성이 유효한 ESM 패키지인 경우 파일 경로를 기반으로 CommonJS 버전을 추정합니다. 종속성에 잘못된 ESM 파일이 있는 경우에 유용할 수 있습니다.

패키지에 ESM 및 CJS 모드에서 다른 로직이 있는 경우 잠재적으로 불일치가 발생할 수 있습니다.

server.deps.cacheDir

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

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

deps

• 타입: { optimizer?, registerNodeLoader?, ... }

의존성 해결 관련 설정입니다.

deps.optimizer

• 타입: { ssr?, web? }
• 버전: Vitest 0.34.0 이후
• 참조: 종속성 최적화 옵션

의존성 최적화를 활성화합니다. 테스트 수가 많을 때 성능 향상을 기대할 수 있습니다. Vitest 0.34.0 이전에는 deps.experimentalOptimizer라는 이름으로 사용되었습니다.

Vitest가 include에 나열된 외부 라이브러리를 발견하면 esbuild를 사용하여 단일 파일로 번들링하고 전체 모듈로 가져옵니다. 이는 다음과 같은 여러 가지 이유로 유용합니다.

• 많은 가져오기가 있는 패키지를 가져오는 것은 비용이 많이 듭니다. 하나의 파일로 번들링하면 시간을 절약할 수 있습니다.
• 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
• 기본값: Vite 4.3.2 이상을 사용하는 경우 true, 그렇지 않으면 false

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

WARNING

이 옵션은 Vite 4.3.2 이상에서만 작동합니다.

deps.web

• 타입: { transformAssets?, ... }
• 버전: Vitest 0.34.2 이후

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

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

deps.web.transformAssets

• 타입: boolean
• 기본값: true

Vitest가 이미지(.png, .svg, .jpg 등) 파일을 Vite가 브라우저에서 처리하는 방식과 동일하게 처리하고 해석할지 여부를 설정합니다.

쿼리가 지정되지 않은 경우 이 모듈에는 자산 경로와 동일한 기본 내보내기가 있습니다.

WARNING

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

deps.web.transformCss

• 타입: boolean
• 기본값: true

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

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

WARNING

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

deps.web.transformGlobPattern

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

변환해야 하는 외부 파일과 일치하는 정규식 패턴입니다.

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

WARNING

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

deps.registerNodeLoader*

• 타입: boolean
• 기본값: false

Vite의 모듈 해석 알고리즘을 사용하여 외부화된 파일 내부의 import 구문을 처리하기 위해 실험적인 Node.js 로더를 사용합니다.

비활성화된 경우 alias 및 <plugin>.resolveId는 외부화된 패키지 내부의 가져오기에 영향을 미치지 않습니다 (기본적으로 node_modules).

deps.interopDefault

• 타입: boolean
• 기본값: true

CommonJS 모듈의 default export를 named export처럼 취급합니다. 몇몇 의존성 모듈은 CommonJS 형식으로만 제공되며, Node.js 환경에서 require 대신 import 구문으로 불러올 때 named export를 지원하지 않아 정적 분석이 불가능할 수 있습니다. 명명된 내보내기를 사용하여 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의 동작에 영향을 줍니다. 만약 vi.mock 사용 시 factory 함수가 주어지지 않았고, mock하려는 대상의 경로가 moduleDirectories에 설정된 값 중 하나와 일치한다면, Vitest는 프로젝트 root 디렉토리 아래의 __mocks__ 폴더에서 해당 mock을 찾습니다.

이 옵션은 의존성 모듈을 외부 모듈로 처리할지 여부에도 영향을 줍니다. 기본적으로 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)']

벤치마크 테스트 파일에 대한 glob 패턴을 지정합니다.

benchmark.exclude

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

벤치마크 테스트 파일에서 제외할 glob 패턴을 지정합니다.

benchmark.includeSource

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

소스 코드 내에 있는 벤치마크 테스트 파일에 대한 glob 패턴을 지정합니다. 이 옵션은 includeSource와 유사합니다.

이 옵션이 정의되면 Vitest는 파일 내에 import.meta.vitest가 있는 모든 파일을 실행합니다.

benchmark.reporters

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

출력에 대한 사용자 지정 리포터를 설정합니다. 하나 이상의 기본 제공 보고서 이름, 리포터 인스턴스 및/또는 사용자 지정 리포터 경로를 포함할 수 있습니다.

benchmark.outputFile

• 타입: string | Record<string, string>

--reporter=json 옵션이 활성화되었을 때, 벤치마크 결과를 파일로 저장합니다. 문자열 대신 객체 형태로 설정하면, 여러 개의 리포터를 사용할 때 각각의 출력 파일 경로를 개별적으로 지정할 수 있습니다.

alias

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

테스트 내부에서 실행할 때 사용자 지정 별칭을 정의합니다. resolve.alias의 별칭과 병합됩니다.

globals

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

기본적으로 vitest는 코드의 명확성을 위해 전역 API를 제공하지 않습니다. Jest처럼 전역 API를 사용하고 싶다면, CLI에서 --globals 옵션을 사용하거나 설정 파일에 globals: true를 추가하면 됩니다.

// vite.config.ts
import { defineConfig } from 'vitest/config';

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

TypeScript 환경에서 전역 API를 사용하려면, tsconfig.json 파일의 types 필드에 vitest/globals를 추가해야 합니다.

// tsconfig.json
{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

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

// vite.config.ts
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 환경을 사용할 수 있습니다.

파일 상단에 @vitest-environment 독블록을 추가하여 특정 파일 내의 모든 테스트에 적용할 환경을 지정할 수 있습니다.

독블록 스타일:

/**
 * @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();
});

--threads=false 플래그를 사용하여 Vitest를 실행하면, 테스트는 node, jsdom, happy-dom, edge-runtime, custom environments 순서대로 실행됩니다. 즉, 동일한 환경의 테스트는 함께 그룹화되어 순차적으로 실행됩니다.

0.23.0 버전부터는 사용자 정의 환경을 설정할 수 있습니다. 내장 환경 외의 환경을 사용하는 경우, Vitest는 vitest-environment-${name} 패키지를 로드하려고 시도합니다. 해당 패키지는 Environment 타입의 객체를 export해야 합니다.

import type { Environment } from 'vitest';

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  setup() {
    // custom setup
    return {
      teardown() {
        // called after all tests with this env have been run
      },
    };
  },
};

Vitest는 확장성을 위해 vitest/environments 엔트리를 통해 builtinEnvironments를 제공합니다. 환경 확장에 대한 자세한 내용은 가이드를 참조하십시오.

environmentOptions

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

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

environmentMatchGlobs

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

glob 패턴을 기반으로 테스트 환경을 자동으로 지정합니다. 먼저 일치하는 항목이 적용됩니다.

예시:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environmentMatchGlobs: [
      // tests/dom 디렉토리의 모든 테스트는 jsdom 환경에서 실행됩니다.
      ['tests/dom/**', 'jsdom'],
      // .edge.test.ts로 끝나는 모든 테스트는 edge-runtime 환경에서 실행됩니다.
      ['**/*.edge.test.ts', 'edge-runtime'],
      // ...
    ],
  },
});

poolMatchGlobs

• 타입: [string, 'threads' | 'child_process' | 'experimentalVmThreads'][]
• 기본값: []
• 버전: Vitest 0.29.4 이후

glob 패턴을 기반으로 테스트를 실행할 풀을 자동으로 할당합니다. 먼저 일치하는 항목이 적용됩니다.

예시:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolMatchGlobs: [
      // "worker-specific" 디렉토리의 모든 테스트는 `--threads`를 활성화한 것처럼 워커 스레드 내에서 실행됩니다.
      ['**/tests/worker-specific/**', 'threads'],
      // "browser" 디렉토리의 모든 테스트는 실제 브라우저에서 실행됩니다.
      ['**/tests/browser/**', 'browser'],
      // 다른 glob 패턴이 지정되지 않은 경우, 나머지 모든 테스트는 "browser.enabled" 및 "threads" 옵션에 따라 실행됩니다.
      // ...
    ],
  },
});

update*

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

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

watch*

• 타입: boolean
• 기본값: true
• CLI: -w, --watch, --watch=false

watch 모드를 활성화합니다.

root

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

프로젝트 루트 디렉토리를 지정합니다.

reporters*

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

테스트 결과를 출력하는 사용자 정의 리포터를 지정합니다. 리포터는 Reporter 인스턴스이거나 내장 리포터를 선택하는 문자열일 수 있습니다.

• 'default' - 테스트 스위트가 통과하면 결과를 축약해서 보여줍니다.
• 'basic' - CI 환경에서 기본 리포터와 유사한 리포터를 제공합니다.
• 'verbose' - 전체 작업 트리를 표시합니다.
• 'dot' - 각 작업을 점으로 표시합니다.
• 'junit' - JUnit XML 리포터 (VITEST_JUNIT_SUITE_NAME 환경 변수로 testsuites 태그 이름을 구성하고 VITEST_JUNIT_CLASSNAME으로 classname 태그 속성을 구성할 수 있습니다.)
• 'json' - 간단한 JSON 요약을 제공합니다.
• 'html' - @vitest/ui를 기반으로 HTML 보고서를 출력합니다.
• 'hanging-process' - Vitest가 프로세스를 안전하게 종료할 수 없는 경우, 중단된 프로세스 목록을 표시합니다. 이는 부하가 큰 작업일 수 있으므로 Vitest가 지속적으로 프로세스를 종료할 수 없는 경우에만 활성화하십시오.
• 사용자 정의 리포터의 경로 (예: './path/to/reporter.ts', '@scope/reporter')

outputFile*

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

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

experimentalVmThreads

• 타입: boolean
• CLI: --experimentalVmThreads, --experimental-vm-threads
• 버전: Vitest 0.34.0 이후

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

이 옵션을 사용하면 테스트 실행 속도가 빨라지지만 ESM 코드를 실행할 때 VM 모듈이 불안정해질 수 있습니다. 또한 테스트에서 메모리 누수가 발생할 수 있습니다. 이를 해결하려면 experimentalVmWorkerMemoryLimit 값을 수동으로 조정하는 것을 고려하십시오.

WARNING

샌드박스에서 코드를 실행하면 테스트 속도가 빨라지는 장점이 있지만 다음과 같은 단점도 있습니다.

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

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

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

이 옵션을 사용할 때는 이러한 문제를 인지해야 합니다. Vitest 팀은 이러한 문제를 해결할 수 없습니다.

experimentalVmWorkerMemoryLimit

• 타입: string | number
• CLI: --experimentalVmWorkerMemoryLimit, --experimental-vm-worker-memory-limit
• 기본값: 1 / CPU Cores
• 버전: Vitest 0.34.0 이후

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

이 옵션은 VM 컨텍스트에서 테스트를 실행하는 워커에만 영향을 줍니다.

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 워커에서 백분율 기반 메모리 제한이 작동하지 않습니다.

threads

• 타입: boolean
• 기본값: true
• CLI: --threads, --threads=false

tinypool ( Piscina의 경량 포크)을 사용하여 다중 스레딩을 활성화합니다. Vitest 0.29.0 이전에는 이 옵션이 비활성화된 경우에도 Vitest는 여전히 워커 스레드 내부에서 테스트를 실행했습니다. 0.29.0부터 이 옵션이 비활성화되면 Vitest는 child_process를 사용하여 프로세스를 생성하여 내부에서 테스트를 실행합니다. 즉, 워커 내에서 사용할 수 없었던 process.chdir 및 기타 API를 사용할 수 있습니다. 이전 동작으로 되돌리려면 대신 --single-thread 옵션을 사용하십시오.

이 옵션을 비활성화하면 모든 테스트가 여러 자식 프로세스 내부에서 실행됩니다.

singleThread

• 타입: boolean
• 기본값: false
• 버전: Vitest 0.29.0 이후

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

WARNING

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

전역 상태에 의존하거나 코드가 각 테스트에 대해 별도로 정의된 환경에 의존하는 경우 문제가 발생할 수 있습니다. 그러나 전역 상태에 반드시 의존하지 않거나 쉽게 우회할 수 있는 테스트의 경우 속도 향상을 기대할 수 있습니다(최대 3배 더 빠름).

maxThreads*

• 타입: number
• 기본값: 사용 가능한 CPU 코어 수

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

minThreads*

• 타입: number
• 기본값: 사용 가능한 CPU 코어 수

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

useAtomics*

• 타입: boolean
• 기본값: false
• 버전: Vitest 0.28.3 이후

Atomics를 사용하여 스레드를 동기화합니다.

이렇게 하면 성능이 향상될 수 있지만 이전 Node 버전에서 세그먼트 오류가 발생할 수 있습니다.

testTimeout

• 타입: number
• 기본값: 5000
• CLI: --test-timeout=5000

테스트의 기본 제한 시간(밀리초)을 설정합니다.

hookTimeout

• 타입: number
• 기본값: 10000

훅의 기본 제한 시간(밀리초)을 설정합니다.

teardownTimeout*

• 타입: number
• 기본값: 10000

Vitest가 종료될 때 teardown이 완료될 때까지 기다리는 기본 제한 시간(밀리초)을 설정합니다.

silent*

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

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

setupFiles

• 타입: string | string[]

설정 파일의 경로를 지정합니다. 각 테스트 파일이 실행되기 전에 실행됩니다.

INFO

설정 파일을 변경하면 모든 테스트가 다시 실행됩니다.

process.env.VITEST_POOL_ID (정수 형태의 문자열)를 사용하여 스레드를 구별할 수 있습니다 (threads: false로 실행하는 경우 항상 '1'입니다).

TIP

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

예를 들어 전역 변수를 사용할 수 있습니다.

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

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

// hooks are reset before each suite
afterEach(() => {
  cleanup();
});

globalThis.resetBeforeEachTest = true;

globalSetup

• 타입: string | string[]

프로젝트 루트를 기준으로 하는 전역 설정 파일의 경로를 지정합니다.

전역 설정 파일은 명명된 함수 setup 및 teardown 또는 teardown 함수를 반환하는 default 함수를 export할 수 있습니다 (예시).

INFO

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

WARNING

전역 설정은 다른 전역 범위에서 실행되므로 테스트는 여기에 정의된 변수에 액세스할 수 없습니다.

watchExclude*

• 타입: string[]
• 기본값: ['**/node_modules/**', '**/dist/**']

watch 모드에서 파일 변경을 감지하여 재실행을 트리거하지 않도록 제외할 파일 경로의 glob 패턴을 지정합니다.

forceRerunTriggers*

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

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

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

test('execute a script', async () => {
  // Vitest cannot rerun this test, if content of `dist/index.js` changes
  await execa('node', ['dist/index.js']);
});

TIP

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

isolate

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

각 테스트 파일을 격리된 환경에서 실행합니다. --threads 옵션이 비활성화된 경우 작동하지 않습니다.

이 옵션은 experimentalVmThreads에는 영향을 주지 않습니다.

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>

커버리지 수집 도구를 선택합니다.

coverage.enabled

• 타입: boolean
• 기본값: false
• 사용 가능한 provider: 'v8' | 'istanbul'
• CLI: --coverage.enabled, --coverage.enabled=false

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

coverage.include

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

커버리지 분석에 포함할 파일의 glob 패턴을 지정합니다.

coverage.extension

• 타입: string | string[]
• 기본값: ['.js', '.cjs', '.mjs', '.ts', '.mts', '.cts', '.tsx', '.jsx', '.vue', '.svelte']
• 사용 가능한 provider: 'v8' | 'istanbul'
• CLI: --coverage.extension=<extension>, --coverage.extension=<extension1> --coverage.extension=<extension2>

커버리지 분석에 포함할 파일 확장자를 지정합니다.

coverage.exclude

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

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

• 사용 가능한 provider: 'v8' | 'istanbul'
• CLI: --coverage.exclude=<path>, --coverage.exclude=<path1> --coverage.exclude=<path2>

커버리지 분석에서 제외할 파일의 glob 패턴을 지정합니다.

coverage.all

• 타입: boolean
• 기본값: false
• 사용 가능한 provider: 'v8' | 'istanbul'
• CLI: --coverage.all, --coverage.all=false

테스트되지 않은 파일도 커버리지 보고서에 포함할지 여부를 설정합니다.

coverage.clean

• 타입: boolean
• 기본값: true
• 사용 가능한 provider: 'v8' | 'istanbul'
• CLI: --coverage.clean, --coverage.clean=false

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

coverage.cleanOnRerun

• 타입: boolean
• 기본값: true
• 사용 가능한 provider: 'v8' | 'istanbul'
• CLI: --coverage.cleanOnRerun, --coverage.cleanOnRerun=false

watch 모드에서 재실행 시 커버리지 보고서를 초기화합니다.

coverage.reportsDirectory

• 타입: string
• 기본값: './coverage'
• 사용 가능한 provider: 'v8' | 'istanbul'
• CLI: --coverage.reportsDirectory=<path>

커버리지 보고서를 저장할 디렉터리를 지정합니다.

coverage.reporter

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

사용할 커버리지 리포터를 지정합니다. 사용 가능한 모든 리포터 목록은 istanbul documentation을 참조하십시오. 리포터별 옵션에 대한 자세한 내용은 @types/istanbul-reporter를 참조하십시오.

리포터는 다음과 같은 세 가지 유형으로 구성할 수 있습니다.

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

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

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

coverage.reportOnFailure

• 타입: boolean
• 기본값: false (Vitest 0.34.0부터)
• 사용 가능한 provider: 'v8' | 'istanbul'
• CLI: --coverage.reportOnFailure, --coverage.reportOnFailure=false
• 버전: Vitest 0.31.2부터

테스트 실패 시에도 커버리지 보고서를 생성합니다.

coverage.allowExternal

• 타입: boolean
• 기본값: false
• 사용 가능한 provider: 'v8' | 'istanbul'
• CLI: --coverage.allowExternal, --coverage.allowExternal=false

프로젝트 root 외부의 파일에 대한 커버리지 수집을 허용합니다.

coverage.skipFull

• 타입: boolean
• 기본값: false
• 사용 가능한 provider: 'v8' | 'istanbul'
• CLI: --coverage.skipFull, --coverage.skipFull=false

100% statement, branch 및 function 커버리지를 가진 파일을 보고서에서 제외합니다.

coverage.perFile

• 타입: boolean
• 기본값: false
• 사용 가능한 provider: 'v8' | 'istanbul'
• CLI: --coverage.perFile, --coverage.perFile=false

파일별 커버리지 임계값을 검사합니다. 실제 임계값은 lines, functions, branches 및 statements 옵션을 참조하십시오.

coverage.thresholdAutoUpdate

• 타입: boolean
• 기본값: false
• 사용 가능한 provider: 'v8' | 'istanbul'
• CLI: --coverage.thresholdAutoUpdate=<boolean>

현재 커버리지가 설정된 임계값보다 높을 경우, lines, functions, branches, statements 임계값을 자동으로 설정 파일에 업데이트합니다. 이 옵션은 커버리지 개선 시 임계값을 유지하는 데 유용합니다.

coverage.lines

• 타입: number
• 사용 가능한 provider: 'v8' | 'istanbul'
• CLI: --coverage.lines=<number>

lines 커버리지에 대한 임계값입니다. 자세한 내용은 istanbul documentation을 참조하십시오.

coverage.functions

• 타입: number
• 사용 가능한 provider: 'v8' | 'istanbul'
• CLI: --coverage.functions=<number>

functions 커버리지에 대한 임계값입니다. 자세한 내용은 istanbul documentation을 참조하십시오.

coverage.branches

• 타입: number
• 사용 가능한 provider: 'v8' | 'istanbul'
• CLI: --coverage.branches=<number>

branches 커버리지에 대한 임계값입니다. 자세한 내용은 istanbul documentation을 참조하십시오.

coverage.statements

• 타입: number
• 사용 가능한 provider: 'v8' | 'istanbul'
• CLI: --coverage.statements=<number>

statements 커버리지에 대한 임계값입니다. 자세한 내용은 istanbul documentation을 참조하십시오.

coverage.100

• 타입: boolean
• 기본값: false
• 사용 가능한 provider: 'v8' | 'istanbul'
• CLI: --coverage.100, --coverage.100=false

--coverage.lines 100 --coverage.functions 100 --coverage.branches 100 --coverage.statements 100 옵션을 한 번에 설정하는 단축키입니다.

coverage.ignoreClassMethods

• 타입: string[]
• 기본값: []
• 사용 가능한 provider: 'istanbul'
• CLI: --coverage.ignoreClassMethods=<method>

커버리지 측정에서 제외할 클래스 메서드 이름을 배열 형태로 지정합니다. 자세한 내용은 istanbul documentation을 참조하십시오.

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]
}

• 사용 가능한 provider: 'v8' | 'istanbul'

statements, lines, branches 및 functions에 대한 워터마크를 설정합니다. 자세한 내용은 istanbul documentation을 참조하십시오.

coverage.customProviderModule

• 타입: string
• 사용 가능한 provider: 'custom'
• CLI: --coverage.customProviderModule=<path or module name>

사용자 정의 커버리지 provider 모듈의 모듈 이름 또는 파일 경로를 지정합니다. 자세한 내용은 Guide - Custom Coverage Provider를 참조하십시오.

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
• 기본값: false
• CLI: --open, --open=false

Vitest UI (WIP)를 엽니다.

api

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

지정된 포트에서 API 서버를 실행합니다. true로 설정하면 기본 포트는 51204입니다.

browser

• 타입: { enabled?, name?, provider?, headless?, api?, slowHijackESM? }
• 기본값: { enabled: false, headless: process.env.CI, api: 63315 }
• 버전: Vitest 0.29.4부터
• CLI: --browser, --browser=<name>, --browser.name=chrome --browser.headless

브라우저 환경에서 Vitest 테스트를 실행합니다. 기본적으로 테스트 실행을 위해 WebdriverIO를 사용하지만, browser.provider 옵션을 통해 다른 provider로 구성할 수 있습니다.

NOTE

가이드 페이지에서 실제 브라우저에서 테스트하는 방법에 대한 자세한 내용을 확인하십시오.

WARNING

이 기능은 실험적인 기능입니다. 주요 변경 사항이 semver 규칙을 따르지 않을 수 있으므로, 사용할 때 Vitest 버전을 고정하는 것이 좋습니다.

browser.enabled

• 타입: boolean
• 기본값: false
• CLI: --browser, --browser.enabled=false

기본적으로 브라우저 안에서 모든 테스트를 실행합니다. poolMatchGlobs 옵션으로 재정의할 수 있습니다.

browser.name

• 타입: string
• CLI: --browser=safari

특정 브라우저에서 모든 테스트를 실행합니다. provider에 따라 사용 가능한 옵션은 다음과 같습니다.

• webdriverio: firefox, chrome, edge, safari
• playwright: firefox, webkit, chromium
• custom: provider에 전달될 모든 문자열

browser.headless

• 타입: boolean
• 기본값: process.env.CI
• CLI: --browser.headless, --brower.headless=false

브라우저를 헤드리스 모드로 실행합니다. CI 환경에서 Vitest를 실행하는 경우 기본적으로 활성화됩니다.

browser.api

• 타입: number | { port?, strictPort?, host? }
• 기본값: 63315
• CLI: --browser.api=63315, --browser.api.port=1234, --browser.api.host=example.com

브라우저에서 코드를 제공하는 Vite 서버의 옵션을 설정합니다. 이 옵션은 test.api 옵션에는 영향을 주지 않습니다.

browser.provider

• 타입: 'webdriverio' | 'playwright' | string
• 기본값: 'webdriverio'
• CLI: --browser.provider=playwright

브라우저 테스트 실행 시 사용할 provider의 경로를 지정합니다. Vitest는 webdriverio(기본값) 및 playwright 두 가지 provider를 기본적으로 제공합니다. 사용자 정의 provider는 default export를 통해 내보내야 하며, 아래와 같은 형태를 가져야 합니다.

export interface BrowserProvider {
  name: string;
  getSupportedBrowsers(): readonly string[];
  initialize(ctx: Vitest, options: { browser: string }): Awaitable<void>;
  openPage(url: string): Awaitable<void>;
  close(): Awaitable<void>;
}

WARNING

이것은 라이브러리 작성자를 위한 고급 API입니다. 브라우저에서 테스트를 실행하기만 하면 되는 경우 browser 옵션을 사용하십시오.

browser.slowHijackESM

• 타입: boolean
• 기본값: true
• 버전: Vitest 0.31.0 이후

Node.js에서 테스트를 실행할 때 Vitest는 자체 모듈 해석을 사용하여 vi.mock 구문으로 모듈을 쉽게 모의 처리할 수 있습니다. 하지만 브라우저에서는 ES 모듈 해석을 동일하게 구현하기 어렵기 때문에, 브라우저에서 파일을 사용하기 전에 소스 코드를 변환해야 합니다.

이 옵션은 Node.js 환경에서 실행되는 테스트에는 영향을 주지 않습니다.

기본적으로 브라우저 환경에서 실행할 때 활성화됩니다. vi.spyOn을 통해 ES 모듈을 감시하거나 vi.mock을 사용하지 않는 경우, 이 옵션을 비활성화하여 성능을 약간 향상시킬 수 있습니다.

clearMocks

• 타입: boolean
• 기본값: false

각 테스트를 실행하기 전에 모든 감시 대상에서 .mockClear()를 호출합니다. 이렇게 하면 모의(mock) 기록은 삭제되지만, 구현체는 기본값으로 초기화되지 않습니다.

mockReset

• 타입: boolean
• 기본값: false

각 테스트를 실행하기 전에 모든 감시 대상에서 .mockReset()를 호출합니다. 이렇게 하면 모의(mock) 기록이 삭제되고, 구현체는 빈 함수로 초기화됩니다 ( undefined 반환).

restoreMocks

• 타입: boolean
• 기본값: false

각 테스트를 실행하기 전에 모든 감시 대상에서 .mockRestore()를 호출합니다. 이렇게 하면 모의(mock) 기록이 삭제되고, 구현체는 원래 상태로 초기화됩니다.

unstubEnvs

• 타입: boolean
• 기본값: false
• 버전: Vitest 0.26.0 이후

각 테스트를 실행하기 전에 vi.unstubAllEnvs를 호출합니다.

unstubGlobals

• 타입: boolean
• 기본값: false
• 버전: Vitest 0.26.0 이후

각 테스트를 실행하기 전에 vi.unstubAllGlobals를 호출합니다.

testTransformMode

• 타입: { web?, ssr? }
• 버전: Vitest 0.34.0 이후

glob 패턴과 일치하는 테스트 내에서 import된 모든 모듈에 대해 변환 방식을 결정합니다. 기본적으로 실행 환경에 따라 달라집니다. 예를 들어 JSDOM 환경에서 실행되는 테스트는 ssr: false 플래그를 사용하여 모든 파일을 처리하고, Node 환경에서 실행되는 테스트는 ssr: true 플래그를 사용하여 모든 모듈을 처리합니다.

testTransformMode.ssr

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

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

testTransformMode.web

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

일반적인 변환 파이프라인(브라우저 대상)을 먼저 거친 후, SSR 재작성 과정을 통해 Node 환경에서 코드를 실행합니다. Vite 플러그인은 해당 파일을 처리할 때 ssr: false 플래그를 전달받습니다.

snapshotFormat*

• 타입: PrettyFormatOptions

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

resolveSnapshotPath*

• 타입: (testPath: string, snapExtension: string) => string
• 기본값: 스냅샷 파일을 __snapshots__ 디렉터리에 저장합니다.

기본 스냅샷 경로를 재정의합니다. 예를 들어 스냅샷을 테스트 파일 옆에 저장하려면 다음과 같이 설정합니다.

import { defineConfig } from 'vitest/config';

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

allowOnly

• 타입: boolean
• 기본값: false
• 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 파이프라인을 통해 처리될 파일에 대한 정규 표현식 패턴입니다.

TIP

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

css.exclude

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

빈 CSS 파일을 반환할 파일에 대한 정규 표현식 패턴입니다.

css.modules

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

css.modules.classNameStrategy

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

CSS 파일 처리를 활성화한 경우, CSS 모듈 내부 클래스 이름의 스코프 지정 여부를 설정할 수 있습니다. 다음 옵션 중 하나를 선택할 수 있습니다.

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

WARNING

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

maxConcurrency

• 타입: number
• 기본값: 5

test.concurrent로 지정된 테스트를 동시에 실행할 수 있는 최대 개수입니다.

이 제한을 초과하는 테스트는 사용 가능한 슬롯이 생길 때까지 대기합니다.

cache*

• 타입: false | { dir? }

Vitest 캐시 정책을 구성하는 옵션입니다. 현재 Vitest는 실행 시간이 길거나 실패했던 테스트를 먼저 실행하기 위해 테스트 결과에 대한 캐시를 저장합니다.

cache.dir

• 타입: string
• 기본값: node_modules/.vitest

캐시 디렉터리의 경로입니다.

sequence

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

테스트를 정렬하는 방법에 대한 옵션입니다.

점 표기법(dot notation)으로 CLI에 시퀀스 옵션을 제공할 수 있습니다.

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

sequence.sequencer*

• 타입: TestSequencerConstructor
• 기본값: BaseSequencer

샤딩(데이터 분할) 및 정렬 메서드를 정의하는 사용자 정의 클래스입니다. sort 및 shard 메서드 중 하나만 재정의해야 하는 경우 vitest/node에서 BaseSequencer를 확장할 수 있지만, 두 메서드 모두 존재해야 합니다.

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

sequence.shuffle

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

테스트를 임의 순서로 실행하려면 이 옵션 또는 CLI 인수 --sequence.shuffle를 통해 활성화할 수 있습니다.

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

sequence.concurrent

• 타입: boolean
• 기본값: false
• CLI: --sequence.concurrent, --sequence.concurrent=false
• 버전: Vitest 0.32.2 이후

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

sequence.seed*

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

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

sequence.hooks

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

훅 실행 순서를 변경합니다.

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

sequence.setupFiles

• 타입: 'list' | 'parallel'
• 기본값: 'parallel'
• CLI: --sequence.setupFiles=<value>
• 버전: Vitest 0.29.3 이후

설정 파일이 실행되는 순서를 변경합니다.

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

typecheck

타입 검사 테스트 환경 설정을 위한 옵션입니다.

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)']

테스트 파일로 간주할 파일의 glob 패턴입니다.

typecheck.exclude

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

테스트 파일로 간주하지 않을 파일의 glob 패턴입니다.

typecheck.allowJs

• 타입: boolean
• 기본값: false

@ts-check 주석이 있는 JS 파일을 확인합니다. tsconfig에서 활성화한 경우 이 설정은 적용되지 않습니다.

typecheck.ignoreSourceErrors

• 타입: boolean
• 기본값: false

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

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

typecheck.tsconfig

• 타입: string
• 기본값: 가장 가까운 tsconfig.json 파일을 찾습니다.

프로젝트 루트를 기준으로 사용자 정의 tsconfig 파일의 경로입니다.

slowTestThreshold*

• 타입: number
• 기본값: 300

테스트가 느리다고 판단되어 결과에 표시되는 기준 시간(밀리초)입니다.

chaiConfig

• 타입: { includeStack?, showDiff?, truncateThreshold? }
• 기본값: { includeStack: false, showDiff: true, truncateThreshold: 40 }
• 버전: Vitest 0.30.0 이후

Chai 구성과 동일합니다.

chaiConfig.includeStack

• 타입: boolean
• 기본값: false

Assertion 오류 메시지에 스택 트레이스가 포함될지 여부를 결정합니다. 기본값인 false는 오류 메시지에서 스택 추적을 숨깁니다.

chaiConfig.showDiff

• 타입: boolean
• 기본값: true

showDiff 플래그를 AssertionErrors에 포함할지 여부를 결정합니다. false는 항상 false입니다. true는 검증 시 차이점을 표시하도록 요청한 경우에 true가 됩니다.

chaiConfig.truncateThreshold

• 타입: number
• 기본값: 40

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

이 구성 옵션은 test.each 제목과 검증 오류 메시지의 값을 잘라내는 데 영향을 미칩니다.

bail

• 타입: number
• 기본값: 0
• CLI: --bail=<value>
• 버전: Vitest 0.31.0 이후

지정된 수의 테스트가 실패하면 테스트 실행을 중단합니다.

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

retry

• 타입: number
• 기본값: 0
• CLI: --retry=<value>
• 버전: Vitest 0.32.3 이후

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

onConsoleLog

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

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

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

import { defineConfig } from 'vitest/config';

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

diff

• 타입: string
• CLI: --diff=<value>
• 버전: Vitest 0.34.5 이후

diff 인터페이스를 생성하는 데 사용될 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;

vitest.config.js

import { defineConfig } from 'vitest/config';

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