러너 API

WARNING

이것은 고급 API입니다. 단순히 테스트를 실행하고자 하는 경우, 이 API는 필요 없을 수도 있습니다. 주로 라이브러리 작성자가 사용합니다.

구성 파일의 runner 옵션을 사용하여 테스트 러너의 경로를 지정할 수 있습니다. 이 파일은 다음 메서드를 구현하는 클래스 생성자를 기본으로 내보내야 합니다.

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

  /**
   * 테스트 러너가 다음 테스트 실행을 취소해야 할 때 호출됩니다.
   * 러너는 이 메서드를 수신하여, 호출될 때 "onBeforeRunSuite" 및 "onBeforeRunTask"에서 테스트와 수트를 건너뛴 것으로 표시해야 합니다.
   */
  onCancel?: (reason: CancelReason) => unknown;

  /**
   * 단일 테스트를 실행하기 전에 호출됩니다. 아직 "result"를 가지고 있지 않습니다.
   */
  onBeforeRunTask?: (test: TaskPopulated) => unknown;
  /**
   * 실제로 테스트 함수를 실행하기 전에 호출됩니다. 이미 "state"와 "startTime"을 포함하는 "result"를 가지고 있습니다.
   */
  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, TaskMeta | undefined][]
  ) => Promise<void>;

  /**
   * 수집된 경로의 모든 테스트를 실행하기 전에 호출됩니다.
   */
  onBeforeRunFiles?: (files: File[]) => unknown;
  /**
   * 수집된 경로의 모든 테스트를 실행한 직후 호출됩니다.
   */
  onAfterRunFiles?: (files: File[]) => unknown;
  /**
   * 테스트에 대한 새로운 컨텍스트가 정의될 때 호출됩니다. 컨텍스트에 사용자 정의 속성을 추가하고자 할 경우 유용합니다.
   * 러너와 함께 사용자 정의 컨텍스트만 정의하려는 경우, "setupFiles"에서 "beforeAll"을 사용하는 것을 고려하십시오.
   */
  extendTaskContext?: (context: TestContext) => TestContext;
  /**
   * 특정 파일이 임포트될 때 호출됩니다. 두 가지 상황에서 호출될 수 있습니다: 테스트를 수집할 때와 설정 파일을 임포트할 때.
   */
  importFile: (filepath: string, source: VitestRunnerImportSource) => unknown;
  /**
   * `test.extend`가 `{ injected: true }`와 함께 사용될 때 러너가 값을 가져오려고 시도할 때 호출되는 함수입니다.
   */
  injectValue?: (key: string) => unknown;
  /**
   * 공개적으로 사용 가능한 구성입니다.
   */
  config: VitestRunnerConfig;
  /**
   * 현재 풀의 이름입니다. 서버 측에서 스택 트레이스가 추론되는 방식에 영향을 줄 수 있습니다.
   */
  pool?: string;
}

이 클래스를 초기화할 때 Vitest는 Vitest 구성을 전달합니다. 이 구성을 config 속성으로 노출해야 합니다.

import type { RunnerTestFile } from 'vitest';
import type { VitestRunner, VitestRunnerConfig } from 'vitest/suite';
import { VitestTestRunner } from 'vitest/runners';

class CustomRunner extends VitestTestRunner implements VitestRunner {
  public config: VitestRunnerConfig;

  constructor(config: VitestRunnerConfig) {
    this.config = config;
  }

  onAfterRunFiles(files: RunnerTestFile[]) {
    console.log('finished running', files);
  }
}

export default CustomRunner;

WARNING

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

ViteNodeRunner는 executeId 메서드를 노출하며, 이는 Vite 친화적인 환경에서 테스트 파일을 임포트하는 데 사용됩니다. 즉, 런타임에 임포트를 해결하고 파일 내용을 변환하여 Node가 이해할 수 있도록 합니다.

export default class Runner {
  async importFile(filepath: string) {
    await this.__vitest_executor.executeId(filepath);
  }
}

WARNING

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

TIP

스냅샷 지원 및 다른 기능들은 러너에 따라 달라집니다. 이 기능을 잃고 싶지 않다면 vitest/runners에서 임포트한 VitestTestRunner에서 러너를 확장할 수 있습니다. 벤치마크 기능을 확장하고자 한다면 BenchmarkNodeRunner도 노출합니다.

작업

WARNING

"러너 작업 API"는 실험적이며 주로 테스트 런타임에서만 사용해야 합니다. Vitest는 또한 "보고된 작업 API"를 노출하며, 이는 메인 스레드(예: 리포터 내부)에서 작업할 때 선호되어야 합니다.

팀은 현재 "러너 작업"을 미래에 "보고된 작업"으로 대체해야 할지 논의 중입니다.

수트와 테스트는 내부적으로 tasks라고 불립니다. Vitest 러너는 테스트를 수집하기 전에 File 작업을 초기화합니다. 이는 몇 가지 추가 속성을 가진 Suite의 상위 집합입니다. 모든 작업( File 포함)에 file 속성으로 사용할 수 있습니다.

interface File extends Suite {
  /**
   * 파일이 속하는 풀의 이름입니다.
   * @default 'forks'
   */
  pool?: string;
  /**
   * UNIX 형식의 파일 경로입니다.
   */
  filepath: string;
  /**
   * 파일이 속하는 테스트 프로젝트의 이름입니다.
   */
  projectName: string | undefined;
  /**
   * 파일 내의 모든 테스트를 수집하는 데 걸린 시간입니다.
   * 이 시간은 모든 파일 종속성을 임포트하는 시간도 포함됩니다.
   */
  collectDuration?: number;
  /**
   * 설정 파일을 임포트하는 데 걸린 시간입니다.
   */
  setupDuration?: number;
}

모든 수트는 수집 단계에서 채워지는 tasks 속성을 가집니다. 작업 트리를 상위에서 하위로 탐색하는 데 유용합니다.

interface Suite extends TaskBase {
  type: 'suite';
  /**
   * 파일 작업입니다. 파일의 루트 작업입니다.
   */
  file: File;
  /**
   * 수트의 일부인 작업 배열입니다.
   */
  tasks: Task[];
}

모든 작업은 자신이 위치한 수트를 참조하는 suite 속성을 가집니다. test 또는 describe가 최상위 수준에서 초기화될 경우, suite 속성을 가지지 않습니다 ( file과 같지 않습니다!). File도 suite 속성을 가지지 않습니다. 작업을 하위에서 상위로 탐색하는 데 유용합니다.

interface Test<ExtraContext = object> extends TaskBase {
  type: 'test';
  /**
   * 테스트 함수에 전달될 테스트 컨텍스트입니다.
   */
  context: TestContext & ExtraContext;
  /**
   * 파일 작업입니다. 파일의 루트 작업입니다.
   */
  file: File;
  /**
   * `context.skip()` 호출로 인해 작업이 건너뛰어졌는지 여부입니다.
   */
  pending?: boolean;
  /**
   * 작업이 실패하더라도 성공으로 처리되어야 하는지 여부입니다. 작업이 실패하면 통과로 표시됩니다.
   */
  fails?: boolean;
  /**
   * 테스트 완료 전에 기다려야 할 비동기 예상(async expects)의 프로미스를 저장합니다.
   */
  promises?: Promise<any>[];
}

모든 작업은 result 필드를 가질 수 있습니다. 수트는 수트 콜백 또는 beforeAll/afterAll 콜백 내에서 오류가 발생하여 테스트 수집이 방해받는 경우에만 이 필드를 가질 수 있습니다. 테스트는 콜백 호출 후 항상 이 필드를 가집니다. state 및 errors 필드는 결과에 따라 존재합니다. beforeEach 또는 afterEach 콜백에서 오류가 발생한 경우, 해당 오류는 task.result.errors에 존재합니다.

export interface TaskResult {
  /**
   * 작업의 상태입니다. 수집 시 `task.mode`를 상속합니다.
   * 작업이 완료되면 `pass` 또는 `fail`로 변경됩니다.
   * - **pass**: 작업이 성공적으로 실행됨
   * - **fail**: 작업이 실패함
   */
  state: TaskState;
  /**
   * 작업 실행 중 발생한 오류입니다. `expect.soft()`가 여러 번 실패하면 여러 오류가 발생할 수 있습니다.
   */
  errors?: ErrorWithDiff[];
  /**
   * 작업 실행에 걸린 시간(밀리초)입니다.
   */
  duration?: number;
  /**
   * 작업 실행이 시작된 시간(밀리초)입니다.
   */
  startTime?: number;
  /**
   * 작업 완료 후 힙 크기(바이트)입니다.
   * `logHeapUsage` 옵션이 설정되어 있고 `process.memoryUsage`가 정의된 경우에만 사용 가능합니다.
   */
  heap?: number;
  /**
   * 이 작업과 관련된 훅들의 상태입니다. 보고 시 유용합니다.
   */
  hooks?: Partial<
    Record<'afterAll' | 'beforeAll' | 'beforeEach' | 'afterEach', TaskState>
  >;
  /**
   * 작업의 재시도 횟수입니다. 작업은 실패하고 `retry` 옵션이 설정된 경우에만 재시도됩니다.
   */
  retryCount?: number;
  /**
   * 작업이 반복된 횟수입니다. 작업은 `repeats` 옵션이 설정된 경우에만 반복됩니다. 이 수치에는 `retryCount`도 포함됩니다.
   */
  repeatCount?: number;
}

사용자 정의 작업 함수

Vitest는 사용자 정의 test 메서드를 생성하기 위해 createTaskCollector 유틸리티를 노출합니다. 이는 테스트와 동일하게 동작하며, 수집 중에 사용자 정의 메서드를 호출합니다.

작업은 수트에 속하는 객체입니다. suite.task 메서드를 통해 현재 수트에 자동으로 추가됩니다.

import { createTaskCollector, getCurrentSuite } from 'vitest/suite';

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

// 이 함수는 수집 단계에서 호출됩니다:
// 여기서 함수 핸들러를 호출하지 않고, 수트 작업에 추가하십시오.
// "getCurrentSuite().task()" 메서드를 사용하십시오.
// 참고: createTaskCollector는 "todo"/"each"/... 기능을 지원합니다.
export const myCustomTask = createTaskCollector(function (name, fn, timeout) {
  getCurrentSuite().task(name, {
    ...this, // "todo"/"skip"/...가 올바르게 추적될 수 있도록
    meta: {
      customPropertyToDifferentiateTask: true,
    },
    handler: fn,
    timeout,
  });
});

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