Vitest 中自定义匹配器类型声明的最佳实践

问题背景

在 Vitest 测试框架中，开发者经常需要扩展自定义匹配器(matcher)来增强测试表达能力。近期从 Vitest 2.1.2 升级到 2.1.3 版本后，一些开发者遇到了自定义匹配器类型声明失效的问题。

核心变化分析

在 Vitest 2.1.3 中，框架将 Assertion<T> 类型从主包移动到了 @vitest/expect 子包中。这一架构调整导致了以下影响：

1. 原有基于 vitest 模块的类型声明不再生效
2. 需要显式导入 @vitest/expect 才能正确扩展类型
3. 文档中的示例代码需要相应更新

解决方案

正确的类型扩展方式应调整为：

import '@vitest/expect'

interface CustomMatchers<R = unknown> {
  toBeFoo: () => R
}

declare module '@vitest/expect' {
  interface Assertion<T = any> extends CustomMatchers<T> {}
  interface AsymmetricMatchersContaining extends CustomMatchers {}
}

常见陷阱与解决方案

在实际项目中，开发者可能会遇到以下复杂情况：

1. 测试工具链冲突：当同时使用 @testing-library/jest-dom 等扩展库时，类型声明可能产生冲突。解决方案是将这些库的导入移到配置文件中。

2. 文件导入问题：从 setupTests.ts 文件中导入辅助函数可能导致类型系统混乱。最佳实践是将测试辅助工具与类型声明分离到不同文件。

3. 模块解析顺序：确保类型声明文件在测试代码之前被正确处理，可以通过调整 import 顺序或使用单独的类型声明文件(.d.ts)解决。

最佳实践建议

1. 将自定义匹配器类型声明集中管理在单独的类型声明文件中
2. 避免从测试设置文件中导出可复用工具函数
3. 在复杂项目中，考虑使用类型断言确保测试代码的类型安全
4. 定期检查 Vitest 官方文档的更新，特别是类型系统相关变更

总结

Vitest 的类型系统在 2.1.3 版本进行了合理化调整，将匹配器相关类型集中到 @vitest/expect 包中。开发者需要相应调整类型扩展方式，并注意避免在复杂测试环境中可能出现的类型冲突问题。通过遵循上述最佳实践，可以确保自定义匹配器在项目中稳定工作。