マッチャーの拡張

VitestはChaiとJestの両方と互換性があるため、chai.use APIまたはexpect.extendのどちらか、お好みの方法でマッチャーを拡張できます。

このガイドでは、expect.extendを使ったマッチャーの拡張について説明します。ChaiのAPIに興味がある場合は、Chaiのガイドを参照してください。

デフォルトのマッチャーを拡張するには、マッチャーを定義したオブジェクトを引数にexpect.extendを呼び出します。

expect.extend({
  toBeFoo(received, expected) {
    const { isNot } = this;
    return {
      // isNotの値によって`pass`を変更する必要はありません。Vitestが自動的に処理します。
      pass: received === 'foo',
      message: () => `${received} is${isNot ? ' not' : ''} foo`,
    };
  },
});

TypeScriptを使用している場合、環境宣言ファイル（例: vitest.d.ts）で以下のコードを使用して、デフォルトのAssertionインターフェースを拡張できます。

import 'vitest';

interface CustomMatchers<R = unknown> {
  toBeFoo: () => R;
}

declare module 'vitest' {
  interface Assertion<T = any> extends CustomMatchers<T> {}
  interface AsymmetricMatchersContaining extends CustomMatchers {}
}

WARNING

環境宣言ファイルをtsconfig.jsonに含めることを忘れないでください。

マッチャーの戻り値は、以下のインターフェースと互換性がある必要があります。

interface ExpectationResult {
  pass: boolean;
  message: () => string;
  // これらを渡すと、マッチャーの検証が失敗した場合に差分が自動的に表示されるため、
  // 自分で差分を出力する必要はありません。
  actual?: unknown;
  expected?: unknown;
}

WARNING

非同期マッチャーを作成する場合、テスト内で結果をawaitするのを忘れないでください（例: await expect('foo').toBeFoo()）。

マッチャー関数の最初の引数は、受け取り値（expect(received)の中の値）です。残りの引数は、マッチャーに直接渡される引数です。

マッチャー関数は、thisコンテキストを通じて以下のプロパティにアクセスできます。

isNot
マッチャーがnotで呼び出された場合（例: expect(received).not.toBeFoo()）、trueとなります。
promise
マッチャーがresolvedまたはrejectedで呼び出された場合、この値には修飾子名が格納されます。それ以外の場合は、空の文字列となります。
equals
これは2つの値を比較するためのユーティリティ関数です。値が等しい場合はtrueを返し、それ以外の場合はfalseを返します。この関数は、ほとんどのマッチャーで内部的に利用されています。非対称マッチャーを含むオブジェクトもデフォルトでサポートしています。
utils
これには、メッセージ表示に利用できる一連のユーティリティ関数が含まれています。

thisコンテキストには、現在のテストに関する情報も含まれています。これはexpect.getState()を呼び出すことでも取得可能です。最も便利なプロパティは次のとおりです。

currentTestName
現在のテストのフルネーム（describeブロック名も含む）。
testPath
現在のテストファイルへのパス。

マッチャーの拡張 ​

マッチャーの拡張