テストランナー

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;
  /**
   * 結果と状態が設定された後に呼び出されます。
   */
  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/ja/book/vitest-1/advanced/runner#your-task-function
   */
  extendTaskContext?: <T extends Test | Custom>(
    context: TaskContext<T>
  ) => TaskContext<T>;
  /**
   * 特定のファイルがインポートされたときに呼び出されます。テストの収集時とセットアップファイルのインポート時の 2 つの状況で呼び出すことができます。
   */
  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) として呼び出す必要があります。

テストランナー ​

カスタムタスク関数 ​

テストランナー

カスタムタスク関数