1. 模块定位

Expect 模块是 Vitest 的断言层,它面临一个独特的设计约束:同时兼容 Jest 的 expect API 和 Chai 的 assert 风格。这意味着它不能简单地包装 Chai,而需要建立一个桥接层来统一两种断言范式。

2. 双 API 设计

API 风格示例来源
Jest expectexpect(x).toBe(y)内置实现 + Chai 垫片
Chai assertassert.equal(x, y)直接暴露 chai 模块
Chai BDDexpect(x).to.equal(y)Chai 的 BDD 风格
packages/expect/src/index.tsIDE 打开
// ★ Expect 模块导出:Jest + Chai 双 API 统一暴露
export { ChaiStyleAssertions } from './chai-style-assertions'
export { JestChaiExpect }    from './jest-expect'        // Jest → Chai 适配器
export { JestExtend }        from './jest-extend'
export { JestAsymmetricMatchers } from './jest-asymmetric-matchers'
export * as chai           from 'chai'              // ★ 直接暴露 Chai

核心适配器:JestChaiExpect 是将 Jest 风格断言(如 expect(x).toBe(y))映射到 Chai 内部的桥梁。每个 Jest 风格的匹配器方法(toBe, toEqual, toContain 等)实际上调用 Chai 的底层断言机制。

3. 非对称匹配器

非对称匹配器(Asymmetric Matchers)允许在 expect 中做部分匹配——不要求完全相等,只验证值的部分属性。典型用法:

expect(user).toEqual(
  expect.objectContaining({ name: 'Alice' })
  // ★ 只验证 user.name,忽略其他属性
)
packages/expect/src/jest-asymmetric-matchers.ts
// ★ AsymmetricMatcher 基类:所有非对称匹配器的父类
export class AsymmetricMatcher<T> {
  $$typeof = Symbol.for('jest.asymmetricMatcher')
  constructor(protected sample: T) {}
  asymmetricMatch(other: unknown): boolean { /* 子类实现 */ }
}

export class ObjectContaining extends AsymmetricMatcher<Record<string, unknown>> {
  asymmetricMatch(other) {
    return Object.keys(this.sample)
      .every(key => equals(this.sample[key], other[key]))
  }
}

4. 自定义匹配器扩展

通过 expect.extend(matchers),用户可以向 expect 注入自定义断言方法。扩展的匹配器函数接收 received 值和参数,返回 { pass, message } 结构。

expect.extend({
  toBeWithinRange(received, floor, ceiling) {
    const pass = received >= floor && received <= ceiling
    return {
      pass,
      message: () => pass
        ? `expected ${received} not to be within range ${floor} - ${ceiling}`
        : `expected ${received} to be within range ${floor} - ${ceiling}`,
    }
  },
})

这个扩展 API 来自 packages/expect/src/jest-extend.ts,它动态地在 expect 对象上注册新的匹配器方法。

5. 断言状态管理

packages/expect/src/state.ts 管理断言的运行时状态,包括 isNot 标志(expect(x).not.toBe(y))和 promise 标志(expect(promise).resolves.toBe(y))。

packages/expect/src/state.ts
let currentState: ExpectState = {
  isNot: false,      // .not 修饰符
  promise: '',        // .resolves / .rejects
  actual: undefined,  // 当前值
  expected: undefined, // 期望值
}
export function getState(): ExpectState { return currentState }
export function setState(state: ExpectState) { currentState = state }

6. "如果我来写" 对比思考

🧠 问题:如何同时兼容 Jest 和 Chai?

直觉方案:选择其中一个 API,暴露所有方法。另一个用适配器层覆盖。

Vitest 的做法:Chai 是底层引擎(提供 assert / expect / should 风格),JestChaiExpect 是一个属性代理层——它将 Jest 风格的方法名(如 toBe)映射到 Chai 的内部属性(如 equal)。用户可以使用 import { assert } from 'vitest' 直接拿到 Chai 的 assert。

差异分析:这保证了 Jest 生态的兼容性(用户迁移成本极低)同时 保留了 Chai 的表达力(to.be.above、to.have.length 等链式调用)。

7. 学习要点

匹配器用途
expect.any(Constructor)匹配任意该类型的值
expect.anything()匹配任意非 null/undefined 值
expect.arrayContaining(arr)数组包含指定元素
expect.objectContaining(obj)对象包含指定属性
expect.stringContaining(str)字符串包含子串
expect.stringMatching(regexp)字符串匹配正则
expect.schemaMatching(schema)模式匹配(Vitest 扩展)
🏗️ 学习主题关键收获
双 API 桥接Chai 作引擎 + Jest 适配层——保持两个社区的兼容性
非对称匹配器继承 AsymmetricMatcher 基类 —— 部分匹配模式
自定义扩展expect.extend() 运行时注入——开放封闭原则
状态管理.not / .resolves / .rejects 通过状态标志实现