리포터

WARNING

이것은 고급 API입니다. 내장 리포터를 구성하려면 "리포터" 가이드를 읽어보세요.

Vitest는 자체 테스트 실행 라이프사이클을 가지고 있으며, 이는 리포터의 메서드로 표현됩니다:

onInit
onTestRunStart
onTestRunEnd

단일 모듈 내의 테스트 및 스위트는 건너뛰지 않는 한 순서대로 보고됩니다. 건너뛴 모든 테스트는 스위트 또는 모듈이 끝날 때 보고됩니다.

테스트 모듈은 병렬로 실행될 수 있으므로 Vitest는 이를 병렬로 보고합니다.

이 가이드는 지원되는 모든 리포터 메서드를 나열합니다. 하지만 자신만의 리포터를 새로 만드는 대신 기존 리포터를 확장할 수 있다는 점을 기억하세요:

import { BaseReporter } from 'vitest/reporters';

export default class CustomReporter extends BaseReporter {
  onTestRunEnd(testModules, errors) {
    console.log(testModules.length, 'tests finished running');
    super.onTestRunEnd(testModules, errors);
  }
}

onInit

function onInit(vitest: Vitest): Awaitable<void>;

이 메서드는 Vitest가 초기화되거나 시작되었지만, 테스트가 필터링되기 전에 호출됩니다.

INFO

내부적으로 이 메서드는 vitest.start, vitest.init 또는 vitest.mergeReports 내에서 호출됩니다. 프로그래밍 방식 API를 사용하는 경우, 예를 들어 vitest.runTestSpecifications를 호출하기 전에 필요에 따라 이 중 하나를 호출해야 합니다. 내장 CLI는 항상 올바른 순서로 메서드를 실행합니다.

테스트 케이스, 스위트 및 테스트 모듈에서 project 속성을 통해 vitest 인스턴스에 접근할 수도 있습니다. 하지만 이 메서드에서 vitest 인스턴스에 대한 참조를 저장하는 것도 유용할 수 있습니다.

예시

import type { Reporter, TestSpecification, Vitest } from 'vitest/node';

class MyReporter implements Reporter {
  private vitest!: Vitest;

  onInit(vitest: Vitest) {
    this.vitest = vitest;
  }

  onTestRunStart(specifications: TestSpecification[]) {
    console.log(
      specifications.length,
      '테스트 파일이 실행됩니다',
      this.vitest.config.root
    );
  }
}

export default new MyReporter();

onBrowserInit 실험적

function onBrowserInit(project: TestProject): Awaitable<void>;

이 메서드는 브라우저 인스턴스가 시작될 때 호출됩니다. 브라우저가 초기화되는 프로젝트의 인스턴스를 받습니다. 이 메서드가 호출될 때 project.browser는 항상 정의됩니다.

onTestRunStart

function onTestRunStart(specifications: TestSpecification[]): Awaitable<void>;

이 메서드는 새 테스트 실행이 시작될 때 호출됩니다. 실행될 테스트 사양 배열을 받습니다. 이 배열은 읽기 전용이며 정보 제공 목적으로만 사용됩니다.

Vitest가 실행할 테스트 파일을 찾지 못하면 이 이벤트는 빈 배열과 함께 호출된 다음, onTestRunEnd가 즉시 호출됩니다.

예시

import type { Reporter, TestSpecification } from 'vitest/node';

class MyReporter implements Reporter {
  onTestRunStart(specifications: TestSpecification[]) {
    console.log(specifications.length, 'test files will run');
  }
}

export default new MyReporter();

사용 중단 알림

이 메서드는 Vitest 3에 추가되었으며, 이제 사용 중단된 onPathsCollected 및 onSpecsCollected를 대체합니다.

onTestRunEnd

function onTestRunEnd(
  testModules: ReadonlyArray<TestModule>,
  unhandledErrors: ReadonlyArray<SerializedError>,
  reason: TestRunEndReason
): Awaitable<void>;

이 메서드는 모든 테스트 실행이 완료된 후 호출됩니다. 커버리지 기능이 활성화된 경우, 모든 보고서가 병합된 후에 호출됩니다. 커버리지 정보는 onCoverage 훅에서 얻을 수 있습니다.

읽기 전용 테스트 모듈 목록을 받습니다. testModule.children 속성을 통해 반복하여 상태 및 오류(있는 경우)를 보고할 수 있습니다.

두 번째 인수는 Vitest가 특정 테스트에 귀속시킬 수 없었던 처리되지 않은 오류의 읽기 전용 목록입니다. 이러한 오류는 플러그인 오류로 인해 테스트 실행 외부에서 발생하거나, 비동기 함수(예: 테스트 실행이 완료된 후 오류를 발생시킨 타임아웃)의 부작용으로 테스트 실행 중에 발생할 수 있습니다.

세 번째 인수는 테스트 실행이 완료된 이유를 나타냅니다:

passed: 테스트 실행이 정상적으로 완료되었고 오류 없이 완료되었습니다.
failed: 테스트 실행에 하나 이상의 오류가 있습니다 (수집 중 구문 오류 또는 테스트 실행 중 발생한 실제 오류로 인해).
interrupted: vitest.cancelCurrentRun 호출 또는 터미널에서 Ctrl+C가 눌러져 테스트 실행이 중단되었습니다 (이 경우에도 실패한 테스트가 있을 수 있습니다).

Vitest가 실행할 테스트 파일을 찾지 못하면 이 이벤트는 모듈과 오류의 빈 배열과 함께 호출되며, 상태는 config.passWithNoTests 값에 따라 달라집니다.

예시

import type {
  Reporter,
  SerializedError,
  TestModule,
  TestRunEndReason,
  TestSpecification,
} from 'vitest/node';

class MyReporter implements Reporter {
  onTestRunEnd(
    testModules: ReadonlyArray<TestModule>,
    unhandledErrors: ReadonlyArray<SerializedError>,
    reason: TestRunEndReason
  ) {
    if (reason === 'passed') {
      testModules.forEach(module => console.log(module.moduleId, 'succeeded'));
    } else if (reason === 'failed') {
      // 스위트의 가능한 오류는 건너뛸 수 있습니다.
      // testSuite.errors()에서 얻을 수 있습니다.
      for (const testCase of testModules.children.allTests()) {
        if (testCase.result().state === 'failed') {
          console.log(
            testCase.fullName,
            'in',
            testCase.module.moduleId,
            'failed'
          );
          console.log(testCase.result().errors);
        }
      }
    } else {
      console.log('test run was interrupted, skipping report');
    }
  }
}

export default new MyReporter();

사용 중단 알림

이 메서드는 Vitest 3에 추가되었으며, 이제 사용 중단된 onFinished를 대체합니다.

onCoverage

function onCoverage(coverage: unknown): Awaitable<void>;

이 훅은 커버리지 결과가 처리된 후에 호출됩니다. 이 훅이 호출된 후에는 커버리지 제공자의 리포터가 호출됩니다. coverage의 타입은 coverage.provider에 따라 달라집니다. Vitest의 기본 내장 제공자의 경우 istanbul-lib-coverage 패키지에서 타입을 가져올 수 있습니다:

import type { CoverageMap } from 'istanbul-lib-coverage';

declare function onCoverage(coverage: CoverageMap): Awaitable<void>;

Vitest가 커버리지를 수행하지 않은 경우 이 훅은 호출되지 않습니다.

onTestModuleQueued

function onTestModuleQueued(testModule: TestModule): Awaitable<void>;

이 메서드는 Vitest가 설정 파일과 테스트 모듈 자체를 가져오기 전에 호출됩니다. 즉, testModule에는 아직 children이 없지만, 다음으로 실행될 테스트에 대한 보고를 시작할 수 있습니다.

onTestModuleCollected

function onTestModuleCollected(testModule: TestModule): Awaitable<void>;

이 메서드는 파일 내의 모든 테스트가 수집된 후에 호출됩니다. 즉, testModule.children 컬렉션이 채워졌지만, 테스트에는 아직 결과가 없습니다.

onTestModuleStart

function onTestModuleStart(testModule: TestModule): Awaitable<void>;

이 메서드는 onTestModuleCollected 직후에 호출됩니다. Vitest가 수집 모드(vitest.collect() 또는 CLI의 vitest collect)로 실행되는 경우에는 실행할 테스트가 없으므로 이 메서드는 전혀 호출되지 않습니다.

onTestModuleEnd

function onTestModuleEnd(testModule: TestModule): Awaitable<void>;

이 메서드는 모듈 내의 모든 테스트 실행이 완료되었을 때 호출됩니다. 즉, testModule.children 내의 모든 테스트는 pending 상태가 아닌 test.result()를 가집니다.

onHookStart

function onHookStart(context: ReportedHookContext): Awaitable<void>;

이 메서드는 다음 훅 중 하나가 실행을 시작할 때 호출됩니다:

beforeAll
afterAll
beforeEach
afterEach

beforeAll 또는 afterAll이 시작될 경우 entity는 TestSuite 또는 TestModule이 됩니다.

beforeEach 또는 afterEach가 시작될 경우 entity는 항상 TestCase가 됩니다.

WARNING

해당 훅이 테스트 실행 중에 실행되지 않은 경우 onHookStart 메서드는 호출되지 않습니다.

onHookEnd

function onHookEnd(context: ReportedHookContext): Awaitable<void>;

이 메서드는 다음 훅 중 하나가 실행을 마쳤을 때 호출됩니다:

beforeAll
afterAll
beforeEach
afterEach

beforeAll 또는 afterAll이 완료될 경우 entity는 TestSuite 또는 TestModule이 됩니다.

beforeEach 또는 afterEach가 완료될 경우 entity는 항상 TestCase가 됩니다.

WARNING

해당 훅이 테스트 실행 중에 실행되지 않은 경우 onHookEnd 메서드는 호출되지 않습니다.

onTestSuiteReady

function onTestSuiteReady(testSuite: TestSuite): Awaitable<void>;

이 메서드는 스위트가 테스트 실행을 시작하기 전에 호출됩니다. 이 메서드는 스위트가 건너뛰어질 경우에도 호출됩니다.

파일에 스위트가 없으면 이 메서드는 호출되지 않습니다. 이러한 경우를 처리하려면 onTestModuleStart를 사용하는 것을 고려하세요.

onTestSuiteResult

function onTestSuiteResult(testSuite: TestSuite): Awaitable<void>;

이 메서드는 스위트가 테스트 실행을 완료한 후에 호출됩니다. 이 메서드는 스위트가 건너뛰어진 경우에도 호출됩니다.

파일에 스위트가 없으면 이 메서드는 호출되지 않습니다. 이러한 경우를 처리하려면 onTestModuleEnd를 사용하는 것을 고려하세요.

onTestCaseReady

function onTestCaseReady(testCase: TestCase): Awaitable<void>;

이 메서드는 테스트가 실행을 시작하기 전이나 건너뛰어졌을 때 호출됩니다. beforeEach 및 afterEach 훅은 결과에 영향을 미칠 수 있으므로 테스트의 일부로 간주됩니다.

WARNING

onTestCaseReady가 호출될 때 testCase.result()가 이미 passed 또는 failed 상태일 수 있다는 점에 유의하세요. 이는 테스트가 너무 빨리 실행되어 onTestCaseReady와 onTestCaseResult가 동일한 마이크로태스크에서 실행되도록 예약되었을 때 발생할 수 있습니다.

onTestCaseResult

function onTestCaseResult(testCase: TestCase): Awaitable<void>;

이 메서드는 테스트 실행이 완료되거나 건너뛰어졌을 때 호출됩니다. 이 메서드는 afterEach 훅이 있는 경우 해당 훅이 완료된 후에 호출됩니다.

이 시점에서 testCase.result()는 대기 상태가 아닌 값을 가집니다.

onTestAnnotate 3.2.0+

function onTestAnnotate(
  testCase: TestCase,
  annotation: TestAnnotation
): Awaitable<void>;

onTestAnnotate 훅은 context.annotate 메서드와 관련이 있습니다. annotate가 호출되면 Vitest는 이를 직렬화하여 리포터가 상호 작용할 수 있도록 동일한 첨부 파일을 메인 스레드로 보냅니다.

경로가 지정되면 Vitest는 이를 별도의 디렉토리( attachmentsDir로 구성됨)에 저장하고, path 속성을 수정하여 해당 디렉토리를 참조하도록 합니다.

리포터 ​

onInit ​

onBrowserInit 실험적 ​

onTestRunStart ​

onTestRunEnd ​

onCoverage ​

onTestModuleQueued ​

onTestModuleCollected ​

onTestModuleStart ​

onTestModuleEnd ​

onHookStart ​

onHookEnd ​

onTestSuiteReady ​

onTestSuiteResult ​

onTestCaseReady ​

onTestCaseResult ​

onTestAnnotate 3.2.0+ ​

리포터

onInit

onBrowserInit 실험적

onTestRunStart

onTestRunEnd

onCoverage

onTestModuleQueued

onTestModuleCollected

onTestModuleStart

onTestModuleEnd

onHookStart

onHookEnd

onTestSuiteReady

onTestSuiteResult

onTestCaseReady

onTestCaseResult

onTestAnnotate 3.2.0+