테스트 러너

WARNING

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

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

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

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

  /**
   * 개별 테스트를 실행하기 직전에 호출됩니다. 아직 "result"는 존재하지 않습니다.
   */
  onBeforeRunTask?: (test: TaskPopulated) => unknown;
  /**
   * 실제 테스트 함수를 실행하기 직전에 호출됩니다. "result"에는 이미 "state"와 "startTime"이 설정되어 있습니다.
   */
  onBeforeTryTask?: (
    test: TaskPopulated,
    options: { retry: number; repeats: number }
  ) => unknown;
  /**
   * 결과 및 상태가 설정된 후에 호출됩니다.
   */
  onAfterRunTask?: (test: TaskPopulated) => unknown;
  /**
   * 테스트 함수를 실행한 직후에 호출됩니다. 아직 새로운 상태는 설정되지 않았습니다. 테스트 함수에서 예외가 발생하면 호출되지 않습니다.
   */
  onAfterTryTask?: (
    test: TaskPopulated,
    options: { retry: number; repeats: number }
  ) => unknown;

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

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

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

  /**
   * 수집된 경로의 모든 테스트를 실행하기 전에 호출됩니다.
   */
  onBeforeRunFiles?: (files: File[]) => unknown;
  /**
   * 수집된 경로의 모든 테스트를 실행한 직후에 호출됩니다.
   */
  onAfterRunFiles?: (files: File[]) => unknown;
  /**
   * 테스트에 대한 새로운 컨텍스트가 정의될 때 호출됩니다. 사용자 정의 속성을 컨텍스트에 추가할 때 유용합니다.
   * 러너를 통해 사용자 정의 컨텍스트만 정의하려는 경우, "setupFiles"에서 "beforeAll"을 사용하는 것을 권장합니다.
   *
   * 이 메서드는 "test" 및 "custom" 핸들러 모두에 대해 호출됩니다.
   *
   * @see https://www.getbook.com/ko/book/vitest-1/advanced/runner#your-task-function
   */
  extendTaskContext?: <T extends Test | Custom>(
    context: TaskContext<T>
  ) => TaskContext<T>;
  /**
   * 특정 파일을 가져올 때 호출됩니다. 테스트를 수집할 때와 설정 파일을 가져올 때, 두 가지 상황에서 호출될 수 있습니다.
   */
  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.task 메서드를 사용하여 현재 스위트에 자동으로 추가됩니다.

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

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

// 이 함수는 수집 단계에서 호출됩니다.
// 여기서 함수 핸들러를 호출하지 말고 "getCurrentSuite().task()" 메서드를 사용하여 스위트 작업에 추가하십시오.
// 참고: createTaskCollector는 "todo"/"each"/...를 지원합니다.
export const myCustomTask = createTaskCollector(function (name, fn, timeout) {
  getCurrentSuite().task(name, {
    ...this, // so "todo"/"skip"/... is tracked correctly
    meta: {
      customPropertyToDifferentiateTask: true,
    },
    handler: fn,
    timeout,
  });
});

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

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

  myCustomTask('weed the grass', () => {
    gardener.weedTheGrass();
  });
  myCustomTask.todo('mow the lawn', () => {
    gardener.mowerTheLawn();
  });
  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) 형태로 호출해야 합니다.