测试运行器

WARNING

这是高级 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;
  /**
   * 在设置 result 和 state 之后被调用。
   */
  onAfterRunTask?: (test: TaskPopulated) => unknown;
  /**
   * 在运行测试函数之后立即被调用。此时还没有新的 state。如果测试函数抛出异常，则不会被调用。
   */
  onAfterTryTask?: (
    test: TaskPopulated,
    options: { retry: number; repeats: number }
  ) => unknown;

  /**
   * 在运行单个套件之前被调用。此时还没有 "result"。
   */
  onBeforeRunSuite?: (suite: Suite) => unknown;
  /**
   * 在运行单个套件之后被调用。此时有 state 和 result。
   */
  onAfterRunSuite?: (suite: Suite) => unknown;

  /**
   * 如果定义了此方法，将会替代 Vitest 默认的套件划分和处理逻辑。"before" 和 "after" 钩子不会被忽略。
   */
  runSuite?: (suite: Suite) => Promise<void>;
  /**
   * 如果定义了此方法，将会替代 Vitest 默认的处理逻辑。如果您有自定义的测试函数，这将非常有用。"before" 和 "after" 钩子不会被忽略。
   */
  runTask?: (test: TaskPopulated) => Promise<void>;

  /**
   * 当任务更新时被调用。与 reporter 中的 "onTaskUpdate" 相同，但此方法在与测试相同的线程中运行。
   */
  onTaskUpdate?: (task: [string, TaskResult | undefined][]) => Promise<void>;

  /**
   * 在收集路径中的所有测试运行之前被调用。
   */
  onBeforeRunFiles?: (files: File[]) => unknown;
  /**
   * 在收集路径中的所有测试运行之后立即被调用。
   */
  onAfterRunFiles?: (files: File[]) => unknown;
  /**
   * 当为测试定义新的上下文时被调用。如果您想向上下文中添加自定义属性，这将非常有用。
   * 如果您只想使用 runner 定义自定义上下文，请考虑在 "setupFiles" 中使用 "beforeAll" 代替。
   *
   * 此方法对 "test" 和 "custom" 处理程序都会调用。
   *
   * @see https://www.getbook.com/zh-cn/book/vitest-1/advanced/runner#your-task-function
   */
  extendTaskContext?: <T extends Test | Custom>(
    context: TaskContext<T>
  ) => TaskContext<T>;
  /**
   * 当导入某些文件时被调用。可以在两种情况下调用：收集测试时和导入 setup 文件时。
   */
  importFile: (filepath: string, source: VitestRunnerImportSource) => unknown;
  /**
   * 公开可用的配置。
   */
  config: VitestRunnerConfig;
}

在初始化这个类时，Vitest 会传递 Vitest 配置，您应该将其公开为 config 属性。

WARNING

Vitest 还会注入一个 ViteNodeRunner 的实例作为 __vitest_executor 属性。您可以使用它在 importFile 方法中处理文件（这是 TestRunner 和 BenchmarkRunner 的默认行为）。

ViteNodeRunner 公开了 executeId 方法，该方法用于在 Vite 友好的环境中导入测试文件，即在运行时解析导入并转换文件内容，以便 Node 可以理解它。

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();
  });
});

bash

vitest ./garden/tasks.test.js

WARNING

如果未使用自定义运行器或未定义 runTest 方法，Vitest 将尝试自动检索任务。如果未通过 setFn 添加函数，则执行将会失败。

TIP

自定义任务系统支持钩子和上下文功能。如果您希望支持属性链式调用（例如 only、skip 以及您自定义的属性），可以从 vitest/suite 导入 createChainable 并用它来包装您的函数。如果您决定这样做，您需要将 custom 作为 custom.call(this) 调用。

测试运行器 ​

自定义任务函数 ​

测试运行器

自定义任务函数