擴展匹配器

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`

這是一個工具函數，允許您比較兩個值。若值相等，則回傳 true，否則回傳 false。此函數在內部幾乎用於所有匹配器，並預設支援帶有非對稱匹配器的物件。

`utils`

這包含一組工具函數，您可以用來顯示訊息。

this 上下文也包含有關當前測試的資訊。您也可以透過呼叫 expect.getState() 來取得它。最有用的屬性是：

`currentTestName`

當前測試的完整名稱（包括 describe 區塊）。

`testPath`

當前測試檔案的路徑。

擴展匹配器 ​

isNot ​

promise ​

equals ​

utils ​

currentTestName ​

testPath ​