擴充匹配器

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 介面：

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
這是一個實用函數，允許您比較兩個值。若值相等，它將回傳 true，否則回傳 false。此函數在內部幾乎用於每個匹配器，並預設支援帶有非對稱匹配器的物件比較。
utils
這包含一組實用函數，您可用於格式化訊息輸出。

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

currentTestName
當前測試的完整名稱（包含所有 describe 區塊）。
testPath
當前測試檔案的路徑。

擴充匹配器 ​

擴充匹配器