マッチャーの拡張

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} is${isNot ? ' not' : ''} foo`,
    };
  },
});

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

3.2.0+ 3.0.0+

import 'vitest';

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

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

import 'vitest';

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

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

TIP

Vitest 3.2以降では、Matchersインターフェースを拡張することで、expect.extend、expect().*、およびexpect.*メソッドで同時に型安全なアサーションを記述できるようになりました。以前は、それぞれに個別のインターフェースを定義する必要がありました。

WARNING

アンビエント宣言ファイルをtsconfig.jsonに含めるのを忘れないでください。

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

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

WARNING

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

expect.extend({
  async toBeAsyncAssertion() {
    // ...
  },
});

await expect().toBeAsyncAssertion();

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

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

`isNot`

マッチャーがnot修飾子と共に呼び出された場合（expect(received).not.toBeFoo()）、trueを返します。

`promise`

マッチャーがresolvedまたはrejected修飾子と共に呼び出された場合、この値には修飾子の名前が含まれます。それ以外の場合は空文字列になります。

`equals`

これは2つの値を比較するためのユーティリティ関数です。値が等しい場合はtrueを、そうでない場合はfalseを返します。この関数は、ほとんどのマッチャーで内部的に使用されています。非対称マッチャーを含むオブジェクトもデフォルトでサポートしています。

`utils`

これには、メッセージ表示に利用できる一連のユーティリティ関数が含まれています。

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

`currentTestName`

現在のテストの完全な名前（describeブロック名を含む）。

`testPath`

現在のテストファイルへのパス。

マッチャーの拡張 ​

isNot ​

promise ​

equals ​

utils ​

currentTestName ​

testPath ​