테스트 러너

WARNING

이것은 고급 API입니다. 테스트 실행만을 목적으로 한다면 필요하지 않을 수 있으며, 주로 라이브러리 개발자를 대상으로 합니다.

설정 파일의 runner 옵션을 사용하여 테스트 러너의 경로를 지정할 수 있습니다. 해당 파일은 다음 메서드를 구현한 클래스를 기본적으로 내보내야 합니다 (default export).

export interface VitestRunner {
  /**
   * 테스트를 수집하고 실행하기 직전에 가장 먼저 호출되는 함수입니다.
   */
  onBeforeCollect?(paths: string[]): unknown;
  /**
   * 테스트를 수집한 후, "onBeforeRun" 호출 전에 실행됩니다.
   */
  onCollected?(files: File[]): unknown;

  /**
   * 테스트 러너가 현재 테스트 실행을 취소해야 할 경우 호출됩니다.
   * 러너는 이 메서드 호출을 감지하여 "onBeforeRunSuite" 및 "onBeforeRunTest" 단계에서 해당 테스트 및 테스트 스위트를 건너뛰도록 처리해야 합니다.
   */
  onCancel?(reason: CancelReason): unknown;

  /**
   * 개별 테스트를 실행하기 직전에 호출됩니다. 아직 "result"는 존재하지 않습니다.
   */
  onBeforeRunTest?(test: Test): unknown;
  /**
   * 실제 테스트 함수를 실행하기 직전에 호출됩니다. "result"에는 이미 "state"와 "startTime"이 설정되어 있습니다.
   */
  onBeforeTryTest?(test: Test, retryCount: number): unknown;
  /**
   * 결과 및 상태가 설정된 후에 호출됩니다.
   */
  onAfterRunTest?(test: Test): unknown;
  /**
   * 테스트 함수를 실행한 직후에 호출됩니다. 아직 새로운 상태는 설정되지 않았습니다. 테스트 함수에서 예외가 발생하면 호출되지 않습니다.
   */
  onAfterTryTest?(test: Test, retryCount: number): unknown;

  /**
   * 개별 테스트 스위트를 실행하기 직전에 호출됩니다. 아직 "result"는 존재하지 않습니다.
   */
  onBeforeRunSuite?(suite: Suite): unknown;
  /**
   * 개별 테스트 스위트를 실행한 후 호출됩니다. 상태 및 결과가 설정되어 있습니다.
   */
  onAfterRunSuite?(suite: Suite): unknown;

  /**
   * 정의된 경우, 일반적인 Vitest 스위트 분할 및 처리 대신 이 함수가 호출됩니다.
   * "before" 및 "after" 훅은 무시되지 않습니다.
   */
  runSuite?(suite: Suite): Promise<void>;
  /**
   * 정의된 경우, 일반적인 Vitest 처리 대신 이 함수가 호출됩니다. 사용자 정의 테스트 함수를 사용하는 경우에 유용합니다.
   * "before" 및 "after" 훅은 무시되지 않습니다.
   */
  runTest?(test: Test): Promise<void>;

  /**
   * 작업이 업데이트될 때 호출됩니다. 리포터의 "onTaskUpdate"와 동일하지만, 테스트와 같은 스레드에서 실행됩니다.
   */
  onTaskUpdate?(task: [string, TaskResult | undefined][]): Promise<void>;

  /**
   * 수집된 경로의 모든 테스트를 실행하기 전에 호출됩니다.
   */
  onBeforeRun?(files: File[]): unknown;
  /**
   * 수집된 경로의 모든 테스트를 실행한 직후에 호출됩니다.
   */
  onAfterRun?(files: File[]): unknown;
  /**
   * 테스트에 대한 새로운 컨텍스트가 정의될 때 호출됩니다. 사용자 정의 속성을 컨텍스트에 추가할 때 유용합니다.
   * 러너를 통해 사용자 정의 컨텍스트만 정의하려는 경우, "setupFiles"에서 "beforeAll"을 사용하는 것을 권장합니다.
   */
  extendTestContext?(context: TestContext): TestContext;
  /**
   * 특정 파일을 가져올 때 호출됩니다. 테스트를 수집할 때와 설정 파일을 가져올 때, 두 가지 상황에서 호출될 수 있습니다.
   */
  importFile(filepath: string, source: VitestRunnerImportSource): unknown;
  /**
   * 공개적으로 사용할 수 있는 설정입니다.
   */
  config: VitestRunnerConfig;
}

이 클래스를 초기화할 때 Vitest는 Vitest 설정을 전달하며, 이를 config 속성으로 공개해야 합니다.

WARNING

Vitest는 ViteNodeRunner의 인스턴스를 __vitest_executor 속성으로 주입합니다. importFile 메서드에서 파일을 처리하는 데 사용할 수 있습니다 (이는 TestRunner 및 BenchmarkRunner의 기본 동작입니다).

ViteNodeRunner는 Vite 환경에 적합하게 테스트 파일을 가져오는 데 사용되는 executeId 메서드를 제공합니다. 즉, Node 환경에서 이해할 수 있도록 런타임 시 import를 처리하고 파일 내용을 변환합니다.

TIP

스냅샷 지원 및 기타 일부 기능은 러너에 따라 달라집니다. 이러한 기능을 유지하고 싶다면 vitest/runners에서 가져온 VitestTestRunner를 기반으로 러너를 확장할 수 있습니다. 벤치마크 기능을 확장하고 싶다면 BenchmarkNodeRunner도 제공됩니다.

사용자 정의 태스크 함수

Vitest 태스크 시스템을 사용자 정의 태스크로 확장할 수 있습니다. 작업은 테스트 스위트의 일부인 객체이며, suite.custom 메서드를 사용하여 현재 스위트에 자동으로 추가됩니다.

// ./utils/custom.js
import { getCurrentSuite, setFn } from 'vitest/suite';

export { describe, beforeAll, afterAll } from 'vitest';

// 이 함수는 Vitest가 작업을 수집하는 과정에서 호출됩니다.
export const myCustomTask = function (name, fn) {
  const task = getCurrentSuite().custom(name);
  task.meta = {
    customPropertyToDifferentiateTask: true,
  };
  setFn(task, fn || (() => {}));
};

// ./garden/tasks.test.js
import {
  afterAll,
  beforeAll,
  describe,
  myCustomTask,
} from '../utils/custom.js';
import { gardener } from './gardener.js';

describe('take care of the garden', () => {
  beforeAll(() => {
    gardener.putWorkingClothes();
  });

  myCustomTask('weed the grass', () => {
    gardener.weedTheGrass();
  });
  myCustomTask('water flowers', () => {
    gardener.waterFlowers();
  });

  afterAll(() => {
    gardener.goHome();
  });
});

vitest ./garden/tasks.test.js

WARNING

사용자 정의 러너가 없거나 runTest 메서드를 정의하지 않은 경우, Vitest는 작업을 자동으로 검색하려고 시도합니다. setFn으로 함수를 추가하지 않았다면 실패합니다.

TIP

사용자 정의 태스크 시스템은 훅과 컨텍스트를 지원합니다. 체이닝 속성(예: only, skip 및 사용자 정의 속성)을 지원하려면 vitest/suite에서 createChainable을 가져와 함수를 감싸면 됩니다. 이 때, custom을 custom.call(this) 형태로 호출해야 합니다.