扩展断言(Matchers)

由于 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
  // 如果你传了这些参数，它们将自动出现在 diff 信息中，
  // 所以即便断言不通过，你也不必自己输出 diff
  actual?: unknown
  expected?: unknown
}

WARNING

如果你实现了一个异步匹配器，记得在测试里对它的结果使用 await （例如：await expect('foo').toBeFoo() ），否则可能不会按预期执行：

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

await expect().toBeAsyncAssertion()

断言的第一个参数是接收值(即 expect(received) 中的 received )，其余参数将直接传给断言。

断言方法可以访问上下文 this 对象中的这些属性:

`isNot`

如果断言是在 not 方法上调用的( expect(received).not.toBeFoo() )，则返回 true。

`promise`

如果断言是在 resolved/rejected 中调用的，它的值将包含此断言的名称。否则，它将是一个空字符串。

`equals`

这是一个工具函数，他可以帮助你比较两个值。如果是相同的则返回 true，反之返回 false。这个方法几乎在每个断言内部都有使用。默认情况下，它支持非对称的断言。

`utils`

它包含了一系列工具函数，你可以使用它们来显示信息。

this 上下文也包含了当前测试的信息，你可以通过调用 expect.getState() 来获取它，其中最有用的属性是：

`currentTestName`

当前测试的全称(包括 describe 块)。

`testPath`

当前正在执行的测试文件路径。

扩展断言(Matchers) ​

isNot ​

promise ​

equals ​

utils ​

currentTestName ​

testPath ​