Vitest v3 与 jest-image-snapshot 兼容性问题解析

在 Vitest v3 版本中，由于快照状态管理的内部重构，导致与流行的 jest-image-snapshot 库出现兼容性问题。这个问题主要表现为当开发者尝试使用图像快照测试时，会抛出"this.matched.total is not a function"的错误。

问题根源

Vitest v3 对快照状态管理进行了重大重构，将原本的数值型计数器改为了对象结构。具体来说，原本的matched属性是一个简单的数字计数器，现在变成了一个包含多个属性的对象。这种改变虽然提供了更丰富的功能，但却破坏了与 jest-image-snapshot 的兼容性。

jest-image-snapshot 库内部会对matched属性进行数值运算（如matched + 1），当这个属性变为对象后，JavaScript 会将其隐式转换为字符串"[object Object]"，然后与数字1进行字符串连接，最终得到"[object Object]1"这样的无效值。

技术细节分析

在 Vitest 的旧版本中，快照状态管理采用简单的数值计数器：

• added: 记录新增的快照数量
• matched: 记录匹配的快照数量
• unmatched: 记录不匹配的快照数量

而在 v3 版本中，这些属性被重构为对象结构，每个对象包含更详细的统计信息。这种改变虽然提供了更好的可扩展性，但却导致了与现有生态系统的兼容性问题。

临时解决方案

Vitest 团队已经提出了一个临时解决方案，通过特殊的包版本可以解决这个问题。开发者可以通过以下方式尝试这个修复：

1. 修改项目的 package.json 文件
2. 将 vitest 的依赖版本指定为特殊构建版本

这个临时方案通过一些技巧性的处理，使得对象类型的matched属性能够兼容数值运算，从而解决了与 jest-image-snapshot 的兼容性问题。

长期建议

对于长期项目，建议考虑以下几种方案：

1. 等待官方修复：Vitest 团队正在评估是否将这种兼容性修复合并到正式版本中

2. 迁移到浏览器模式：考虑使用专门为浏览器环境设计的可视化测试工具，如 storybook-addon-vis

3. 自定义适配器：为 jest-image-snapshot 编写 Vitest 专用的适配层

总结

Vitest v3 的快照状态重构虽然带来了架构上的改进，但也导致了与现有生态工具的兼容性问题。开发者在使用图像快照测试时需要特别注意这一点。目前已有临时解决方案可用，长期来看，Vitest 团队可能会提供更完善的兼容性支持，或者开发者可以考虑迁移到更适合的工具链。

这个问题也提醒我们，在进行重大架构变更时，需要考虑对生态系统的影响，特别是对那些广泛使用的第三方库的兼容性。