扩展匹配器

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
当前测试文件的路径。

扩展匹配器 ​

扩展匹配器