テストランナー

警告

これは高度なAPIです。テストを実行するだけなら、おそらく必要ありません。ライブラリの作成者に主に使用されます。

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

export interface VitestRunner {
  /**
   * First thing that's getting called before actually collecting and running tests.
   */
  onBeforeCollect?: (paths: string[]) => unknown
  /**
   * Called after collecting tests and before "onBeforeRun".
   */
  onCollected?: (files: File[]) => unknown

  /**
   * Called when test runner should cancel next test runs.
   * Runner should listen for this method and mark tests and suites as skipped in
   * "onBeforeRunSuite" and "onBeforeRunTask" when called.
   */
  onCancel?: (reason: CancelReason) => unknown

  /**
   * Called before running a single test. Doesn't have "result" yet.
   */
  onBeforeRunTask?: (test: TaskPopulated) => unknown
  /**
   * Called before actually running the test function. Already has "result" with "state" and "startTime".
   */
  onBeforeTryTask?: (test: TaskPopulated, options: { retry: number; repeats: number }) => unknown
  /**
   * Called after result and state are set.
   */
  onAfterRunTask?: (test: TaskPopulated) => unknown
  /**
   * Called right after running the test function. Doesn't have new state yet. Will not be called, if the test function throws.
   */
  onAfterTryTask?: (test: TaskPopulated, options: { retry: number; repeats: number }) => unknown

  /**
   * Called before running a single suite. Doesn't have "result" yet.
   */
  onBeforeRunSuite?: (suite: Suite) => unknown
  /**
   * Called after running a single suite. Has state and result.
   */
  onAfterRunSuite?: (suite: Suite) => unknown

  /**
   * If defined, will be called instead of usual Vitest suite partition and handling.
   * "before" and "after" hooks will not be ignored.
   */
  runSuite?: (suite: Suite) => Promise<void>
  /**
   * If defined, will be called instead of usual Vitest handling. Useful, if you have your custom test function.
   * "before" and "after" hooks will not be ignored.
   */
  runTask?: (test: TaskPopulated) => Promise<void>

  /**
   * Called, when a task is updated. The same as "onTaskUpdate" in a reporter, but this is running in the same thread as tests.
   */
  onTaskUpdate?: (task: [string, TaskResult | undefined][]) => Promise<void>

  /**
   * Called before running all tests in collected paths.
   */
  onBeforeRunFiles?: (files: File[]) => unknown
  /**
   * Called right after running all tests in collected paths.
   */
  onAfterRunFiles?: (files: File[]) => unknown
  /**
   * Called when new context for a test is defined. Useful, if you want to add custom properties to the context.
   * If you only want to define custom context with a runner, consider using "beforeAll" in "setupFiles" instead.
   *
   * This method is called for both "test" and "custom" handlers.
   *
   * @see https://vitest.dokyumento.jp/advanced/runner.html#your-task-function
   */
  extendTaskContext?: <T extends Test | Custom>(context: TaskContext<T>) => TaskContext<T>
  /**
   * Called, when certain files are imported. Can be called in two situations: when collecting tests and when importing setup files.
   */
  importFile: (filepath: string, source: VitestRunnerImportSource) => unknown
  /**
   * Publicly available configuration.
   */
  config: VitestRunnerConfig
}

このクラスを開始すると、VitestはVitest設定を渡します。configプロパティとして公開する必要があります。

警告

Vitestはまた、ViteNodeRunnerのインスタンスを__vitest_executorプロパティとして挿入します。importFileメソッドでファイルの処理に使用できます（これは、TestRunnerとBenchmarkRunnerの既定の動作です）。

ViteNodeRunnerは、Viteに適した環境でテストファイルをインポートするために使用されるexecuteIdメソッドを公開します。つまり、インポートを解決し、実行時にファイルの内容を変換して、Nodeが理解できるようにします。

ヒント

スナップショットサポートと他の機能はランナーに依存します。失いたくない場合は、vitest/runnersからインポートしたVitestTestRunnerからランナーを拡張できます。ベンチマーク機能を拡張する場合は、BenchmarkNodeRunnerも公開します。

タスク関数

タスクでVitestタスクシステムを拡張できます。タスクは、スイートの一部であるオブジェクトです。suite.taskメソッドで自動的に現在のスイートに追加されます。

// ./utils/custom.js
import { , ,  } from 'vitest/suite'

export { , ,  } from 'vitest'

// this function will be called during collection phase:
// don't call function handler here, add it to suite tasks
// with "getCurrentSuite().task()" method
// note: createTaskCollector provides support for "todo"/"each"/...
export const  = (
  function (, , ) {
    ().(, {
      ...this, // so "todo"/"skip"/... is tracked correctly
      : {
        : true
      },
      : ,
      ,
    })
  }
)

// ./garden/tasks.test.js
import { , , ,  } from '../custom.js'
import {  } from './gardener.js'

('take care of the garden', () => {
  (() => {
    .putWorkingClothes()
  })

  ('weed the grass', () => {
    .weedTheGrass()
  })
  .todo('mow the lawn', () => {
    .mowerTheLawn()
  })
  ('water flowers', () => {
    .waterFlowers()
  })

  (() => {
    .goHome()
  })
})

vitest ./garden/tasks.test.js

警告

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

ヒント

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