マッチャー拡張

Vitest は Chai と Jest の両方と互換性があるため、chai.use API または expect.extend のどちらか好きな方を使用できます。

このガイドでは、expect.extend を使用したマッチャー拡張について説明します。Chai の API については、公式ガイドを参照してください。

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

expect.extend({
  toBeFoo(received, expected) {
    const { isNot } = this;
    return {
      // isNot に基づいて pass 値を変更しないでください。Vitest が自動的に処理します。
      pass: received === 'foo',
      message: () => `${received} は${isNot ? 'ではない' : ''} foo です。`,
    };
  },
});

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

import type { Assertion, AsymmetricMatchersContaining } from '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 MatcherResult {
  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
現在のテストのパス。

マッチャー拡張 ​

マッチャー拡張