測試執行器

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;
  /**
   * 當定義測試的新上下文時被呼叫。如果您想將自訂屬性新增到上下文中，這會很有用。
   * 如果您只想使用執行器定義自訂上下文，請考慮改用 "setupFiles" 中的 "beforeAll"。
   *
   * 此方法對 "test" 和 "custom" 處理程序都會調用。
   *
   * @see https://www.getbook.com/zh-tw/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 公開了 executeId 方法，該方法用於在 Vite 友善的環境中匯入測試檔案。這表示它將解析匯入，並在執行時轉換檔案內容，以便 Node.js 可以理解。

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.call(this) 的方式來呼叫 custom。

測試執行器 ​

您的任務函式 ​

測試執行器

您的任務函式