テストランナー

WARNING

これは高度な API です。テストを実行するだけであれば、通常は不要です。主にライブラリ作者が使用します。

設定ファイルの runner オプションで、テストランナーへのパスを指定できます。このファイルは、以下のメソッドを実装したクラスをデフォルトエクスポートする必要があります。

export interface VitestRunner {
  /**
   * 実際にテストを収集・実行する前に最初に呼び出されるメソッドです。
   * @param paths テスト対象のファイルパスの配列
   */
  onBeforeCollect?(paths: string[]): unknown;
  /**
   * テストの収集後、"onBeforeRun" の前に呼び出されます。
   * @param files 収集されたテストファイルの情報
   */
  onCollected?(files: File[]): unknown;

  /**
   * テストランナーが次のテスト実行をキャンセルする必要がある場合に呼び出されます。
   * ランナーはこのメソッドを監視し、このメソッドが呼び出された場合、"onBeforeRunSuite" および "onBeforeRunTest" 内でテストとスイートをスキップとしてマークする必要があります。
   * @param reason キャンセルの理由
   */
  onCancel?(reason: CancelReason): unknown;

  /**
   * 単一のテストを実行する前に呼び出されます。"result" はまだ設定されていません。
   * @param test 実行されるテストの情報
   */
  onBeforeRunTest?(test: Test): unknown;
  /**
   * 実際にテスト関数を実行する前に呼び出されます。"state" と "startTime" を持つ "result" がすでに存在します。
   * @param test 実行されるテストの情報
   * @param retryCount リトライ回数
   */
  onBeforeTryTest?(test: Test, retryCount: number): unknown;
  /**
   * 結果と状態が設定された後に呼び出されます。
   * @param test 実行されたテストの情報
   */
  onAfterRunTest?(test: Test): unknown;
  /**
   * テスト関数を実行した後すぐに呼び出されます。新しい状態はまだ設定されていません。テスト関数が例外を投げた場合は呼び出されません。
   * @param test 実行されたテストの情報
   * @param retryCount リトライ回数
   */
  onAfterTryTest?(test: Test, retryCount: number): unknown;

  /**
   * 単一のスイートを実行する前に呼び出されます。"result" はまだ設定されていません。
   * @param suite 実行されるスイートの情報
   */
  onBeforeRunSuite?(suite: Suite): unknown;
  /**
   * 単一のスイートを実行した後に呼び出されます。状態と結果が設定されています。
   * @param suite 実行されたスイートの情報
   */
  onAfterRunSuite?(suite: Suite): unknown;

  /**
   * 定義されている場合、通常の Vitest スイートの分割と処理の代わりに呼び出されます。
   * "before" および "after" フックは無視されません。
   * @param suite 実行されるスイートの情報
   */
  runSuite?(suite: Suite): Promise<void>;
  /**
   * 定義されている場合、通常の Vitest 処理の代わりに呼び出されます。カスタムテスト関数がある場合に便利です。
   * "before" および "after" フックは無視されません。
   * @param test 実行されるテストの情報
   */
  runTest?(test: Test): Promise<void>;

  /**
   * タスクが更新されたときに呼び出されます。レポーターの "onTaskUpdate" と同じですが、これはテストと同じスレッドで実行されます。
   * @param task 更新されたタスクの情報
   */
  onTaskUpdate?(task: [string, TaskResult | undefined][]): Promise<void>;

  /**
   * 収集されたパス内のすべてのテストを実行する前に呼び出されます。
   * @param files 収集されたテストファイルの情報
   */
  onBeforeRun?(files: File[]): unknown;
  /**
   * 収集されたパス内のすべてのテストを実行した直後に呼び出されます。
   * @param files 収集されたテストファイルの情報
   */
  onAfterRun?(files: File[]): unknown;
  /**
   * テストの新しいコンテキストが定義されたときに呼び出されます。カスタムプロパティをコンテキストに追加する場合に便利です。
   * ランナーでカスタムコンテキストのみを定義する場合は、代わりに "setupFiles" で "beforeAll" を使用することを検討してください。
   * @param context テストコンテキスト
   */
  extendTestContext?(context: TestContext): TestContext;
  /**
   * 特定のファイルがインポートされたときに呼び出されます。テストの収集時とセットアップファイルのインポート時の 2 つの状況で呼び出すことができます。
   * @param filepath インポートされたファイルのパス
   * @param source インポート元
   */
  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.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();
  });
});

bash

vitest ./garden/tasks.test.js

WARNING

カスタムランナーがない場合や runTest メソッドを定義していない場合、Vitest はタスクを自動的に実行しようとします。setFn で関数を追加しなかった場合、実行に失敗します。

TIP

カスタムタスクシステムはフックとコンテキストをサポートしています。プロパティチェーン（only、skip、およびカスタムのものなど）をサポートする場合は、vitest/suite から createChainable をインポートし、関数をそれでラップすることが可能です。これを行う場合は、custom を custom.call(this) として呼び出す必要があります。

テストランナー ​

カスタムタスク関数 ​

テストランナー

カスタムタスク関数