커버리지

Vitest는 v8을 통한 네이티브 코드 커버리지와 istanbul을 통한 계측 코드 커버리지를 모두 지원합니다.

커버리지 프로바이더

v8과 istanbul은 모두 선택적으로 지원됩니다. 기본적으로 v8이 사용됩니다.

test.coverage.provider를 v8 또는 istanbul로 설정하여 커버리지 도구를 선택할 수 있습니다.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      provider: 'istanbul', // 또는 'v8'
    },
  },
});

Vitest 프로세스를 시작하면 해당 지원 패키지를 자동으로 설치하라는 메시지가 나타납니다.

또는 수동으로 설치하려면 다음 명령어를 사용하십시오:

v8

npm i -D @vitest/coverage-v8

istanbul

npm i -D @vitest/coverage-istanbul

V8 프로바이더

INFO

아래 V8 커버리지에 대한 설명은 Vitest에 특화된 내용으로, 다른 테스트 러너에는 적용되지 않습니다. v3.2.0부터 Vitest는 V8 커버리지에 AST 기반 커버리지 리매핑을 사용하여 Istanbul과 동일한 커버리지 보고서를 생성합니다.

이를 통해 사용자는 V8 커버리지의 속도와 Istanbul 커버리지의 정확성을 동시에 얻을 수 있습니다.

기본적으로 Vitest는 'v8' 커버리지 프로바이더를 사용합니다. 이 프로바이더는 NodeJS, Deno 또는 Google Chrome과 같은 Chromium 기반 브라우저와 같이 V8 엔진 위에 구현된 Javascript 런타임이 필요합니다.

커버리지 수집은 런타임 중에 node:inspector를 사용하여 V8에 지시하고, 브라우저에서는 Chrome DevTools Protocol을 사용하여 수행됩니다. 사용자의 소스 파일은 사전 계측 단계 없이 그대로 실행할 수 있습니다.

• ✅ 권장되는 사용 옵션
• ✅ 사전 변환 단계 없음. 테스트 파일은 그대로 실행할 수 있습니다.
• ✅ Istanbul보다 실행 시간이 더 빠릅니다.
• ✅ Istanbul보다 메모리 사용량이 적습니다.
• ✅ 커버리지 보고서 정확도는 Istanbul과 동일합니다(Vitest v3.2.0부터).
• ⚠️ 경우에 따라 Istanbul보다 느릴 수 있습니다. 예를 들어, 많은 다른 모듈을 로드할 때. V8은 특정 모듈에 대한 커버리지 수집을 제한할 수 없습니다.
• ⚠️ V8 엔진에 의해 설정된 몇 가지 사소한 제한 사항이 있습니다. ast-v8-to-istanbl | 제한 사항을 참조하십시오.
• ❌ Firefox 또는 Bun과 같이 V8을 사용하지 않는 환경에서는 작동하지 않습니다. 또는 Cloudflare Workers와 같이 프로파일러를 통해 V8 커버리지를 노출하지 않는 환경에서는 작동하지 않습니다.

Istanbul 프로바이더

Istanbul 코드 커버리지 도구는 2012년부터 존재했으며 매우 잘 검증되었습니다. 이 프로바이더는 사용자 소스 파일을 계측하여 커버리지 추적을 수행하므로 모든 Javascript 런타임에서 작동합니다.

실제로 소스 파일을 계측한다는 것은 사용자 파일에 추가적인 자바스크립트 코드를 삽입하는 것을 의미합니다.

// 브랜치 및 함수 커버리지 카운터의 간소화된 예시
const coverage = { 
  branches: { 1: [0, 0] }, 
  functions: { 1: 0 }, 
} 

export function getUsername(id) {
  // 이 함수가 호출될 때 함수 커버리지가 증가합니다
  coverage.functions['1']++; 

  if (id == null) {
    // 이 브랜치가 실행될 때 브랜치 커버리지가 증가합니다
    coverage.branches['1'][0]++; 

    throw new Error('User ID is required');
  }
  // if-문 조건이 충족되지 않을 때 암시적 else 커버리지 증가
  coverage.branches['1'][1]++; 

  return database.getUser(id);
}

globalThis.__VITEST_COVERAGE__ ||= {}; 
globalThis.__VITEST_COVERAGE__[filename] = coverage; 

• ✅ 모든 Javascript 런타임에서 작동
• ✅ 13년 이상 널리 사용되고 검증됨.
• ✅ 경우에 따라 V8보다 빠릅니다. V8과 달리 커버리지 계측을 특정 파일로 제한할 수 있습니다.
• ❌ 사전 계측 단계 필요
• ❌ 계측 오버헤드로 인해 실행 속도가 V8보다 느립니다.
• ❌ 계측으로 인해 파일 크기가 증가합니다.
• ❌ 메모리 사용량이 V8보다 높습니다.

커버리지 설정

TIP

설정 파일에 항상 coverage.include를 정의할 것을 권장합니다. 이렇게 하면 Vitest가 coverage.all에 의해 선택되는 파일 수를 줄이는 데 도움이 됩니다.

커버리지를 활성화하여 테스트하려면 CLI에서 --coverage 플래그를 전달할 수 있습니다. 기본적으로 ['text', 'html', 'clover', 'json'] 리포터가 사용됩니다.

{
  "scripts": {
    "test": "vitest",
    "coverage": "vitest run --coverage"
  }
}

구성하려면 구성 파일에서 test.coverage 옵션을 설정해야 합니다.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      reporter: ['text', 'json', 'html'],
    },
  },
});

사용자 정의 커버리지 리포터

test.coverage.reporter에 패키지 이름 또는 절대 경로를 전달하여 사용자 정의 커버리지 리포터를 사용할 수 있습니다.

import { defineConfig } from 'vitest/config';

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

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

사용자 정의 리포터는 Istanbul에 의해 로드되며, 해당 리포터 인터페이스와 일치해야 합니다. 참조를 위해 내장 리포터 구현을 참조하십시오.

const { ReportBase } = require('istanbul-lib-report');

module.exports = class CustomReporter extends ReportBase {
  constructor(opts) {
    super();

    // 구성에서 전달된 옵션은 여기에서 사용할 수 있습니다.
    this.file = opts.file;
  }

  onStart(root, context) {
    this.contentWriter = context.writer.writeFile(this.file);
    this.contentWriter.println('Start of custom coverage report');
  }

  onEnd() {
    this.contentWriter.println('End of custom coverage report');
    this.contentWriter.close();
  }
};

사용자 정의 커버리지 프로바이더

test.coverage.provider에 'custom'을 전달하여 사용자 정의 커버리지 프로바이더를 제공할 수도 있습니다.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      provider: 'custom',
      customProviderModule: 'my-custom-coverage-provider',
    },
  },
});

사용자 정의 프로바이더는 customProviderModule 옵션을 필요로 하며, 이는 CoverageProviderModule을 로드할 모듈 이름 또는 경로입니다. CoverageProviderModule을 기본 내보내기로 구현하는 객체를 내보내야 합니다.

import type {
  CoverageProvider,
  CoverageProviderModule,
  ResolvedCoverageOptions,
  Vitest,
} from 'vitest';

const CustomCoverageProviderModule: CoverageProviderModule = {
  getProvider(): CoverageProvider {
    return new CustomCoverageProvider();
  },

  // CoverageProviderModule의 나머지 구현...
};

class CustomCoverageProvider implements CoverageProvider {
  name = 'custom-coverage-provider';
  options!: ResolvedCoverageOptions;

  initialize(ctx: Vitest) {
    this.options = ctx.config.coverage;
  }

  // CoverageProvider의 나머지 구현...
}

export default CustomCoverageProviderModule;

자세한 내용은 타입 정의를 확인하십시오.

기본 커버리지 폴더 위치 변경

커버리지 보고서를 실행하면 프로젝트의 루트 디렉토리에 coverage 폴더가 생성됩니다. 다른 디렉토리로 이동하려면 vitest.config.js 파일에서 test.coverage.reportsDirectory 속성을 설정해야 합니다.

import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    coverage: {
      reportsDirectory: './tests/unit/coverage',
    },
  },
});

코드 무시

두 커버리지 프로바이더는 모두 커버리지 보고서에서 코드를 무시하는 방법을 제공합니다.

• v8
• ìstanbul
• v8 with experimentalAstAwareRemapping: true의 경우 ast-v8-to-istanbul | 코드 무시를 참조하십시오.

TypeScript를 사용할 때 소스 코드는 esbuild를 사용하여 트랜스파일되며, 이 과정에서 소스 코드의 모든 주석이 제거됩니다(esbuild#516). 법적 주석으로 간주되는 주석은 보존됩니다.

무시 힌트에 @preserve 키워드를 포함할 수 있습니다. 이러한 무시 힌트가 최종 프로덕션 빌드에도 포함될 수 있다는 점에 유의하십시오.

-/* istanbul ignore if */
+/* istanbul ignore if -- @preserve */
if (condition) {

-/* v8 ignore if */
+/* v8 ignore if -- @preserve */
if (condition) {

기타 옵션

커버리지에 대한 모든 구성 가능한 옵션을 보려면 커버리지 구성 참조를 참조하십시오.

커버리지 성능

프로젝트에서 코드 커버리지 생성이 느리다면 테스트 성능 프로파일링 | 코드 커버리지를 참조하십시오.

Vitest UI

Vitest UI에서 커버리지 보고서를 확인할 수 있습니다.

Vitest UI는 커버리지 보고서가 명시적으로 활성화되고 HTML 커버리지 리포터가 존재할 경우에만 커버리지 보고서를 활성화하며, 그렇지 않으면 사용할 수 없습니다.

• 구성 파일에서 coverage.enabled=true를 활성화하거나 --coverage.enabled=true 플래그로 Vitest를 실행합니다.
• coverage.reporter 목록에 html을 추가합니다. subdir 옵션을 활성화하여 커버리지 보고서를 하위 디렉토리에 넣을 수도 있습니다.