参数断言终极指南：sinon-chai 的 calledWith、calledWithExactly 与 calledWithMatch 如何选？
【免费下载链接】sinon-chaiExtends Chai with assertions for the Sinon.JS mocking framework.项目地址: https://gitcode.com/gh_mirrors/si/sinon-chai
在单元测试中，"被测函数究竟用什么样的参数调用了依赖"是最值得验证的核心行为，而这正是参数断言的用武之地。sinon-chai是一个为 Chai 断言库扩展 Sinon.JS 模拟框架能力的开源插件，它让前端与 Node.js 开发者可以用spy.should.have.been.calledWith(...)这样一行自然流畅的语句完成 spy/stub 的参数验证。今天这篇文章，我们就聚焦参数断言中最容易混淆的三个方法——calledWith、calledWithExactly与calledWithMatch，用一张表、几段代码帮你彻底选对。
一分钟上手：安装 sinon-chai 参数断言
使用前请先确认项目已安装 Chai 与 Sinon.JS（二者是 peerDependencies），然后执行：
npm install --save-dev sinon-chai在测试入口（例如 Mocha 的 fixture 文件）中注册插件即可，参考项目测试代码 test/common.js 的写法：
import * as chai from "chai"; import sinonChai from "sinon-chai"; chai.use(sinonChai);之后无论是expect还是should风格，都能直接调用 Sinon.JS 的全部 spy 断言，包括今天的主角：三个参数断言方法。
一张表看懂：三个参数断言的本质区别
| 断言方法 | 匹配规则 | 允许"多余参数"吗 | 对象参数如何比较 | 典型用途 |
|---|---|---|---|---|
calledWith | 从第一个参数起前缀匹配 | ✅ 允许 | 深度比较（deep equal） | 只想验证关键前几个参数 |
calledWithExactly | 参数个数与值完全一致 | ❌ 不允许 | 深度比较（deep equal） | 严格校验整次调用的完整参数 |
calledWithMatch | 支持sinon.match匹配器 | ✅ 允许 | 由匹配器决定 | 参数不确定、只想验证类型或部分字段 |
三个方法都遵循同一句法：spy.should.have.been.calledWith(args...)或expect(spy).to.have.been.calledWith(args...)。它们的实现统一封装在 lib/sinon-chai.js 中，通过createSinonMethodHandler动态绑定到 Chai 的断言原型上，行为与 Sinon.JS 原生 spy 方法一一对应。
calledWith：最常用的宽松参数断言
calledWith的语义是"曾经有一次调用，其参数以你给定的参数开头"。它只关心前缀，后面多传了参数完全不影响判定，对对象参数则做深度比较。
const cb = sinon.spy(); cb("hello", "world", "extra"); cb.should.have.been.calledWith("hello", "world"); // ✅ 通过这在回调场景中非常实用：你通常只关心回调携带的关键信息（比如第一个参数是错误对象、第二个是数据），而不关心是否还夹带了其他内容。在 test/callArguments.js 的测试里可以清楚看到：spy("A", "B", "C")后断言calledWith("A", "B")不会抛错，而把两个参数顺序写反则立即失败。
calledWithExactly：精确到每一个参数的严格断言
当调用链的安全取决于"参数个数也不能多"时，就该换calledWithExactly上场。它要求某一次调用的参数个数和值都与你给定的完全一致，多一个参数都会让断言失败。
const spy = sinon.spy(); spy("hello", "world", "extra"); spy.should.have.been.calledWithExactly("hello", "world"); // ❌ 参数多了，失败！如果你的函数内部对参数个数有严格要求（例如arguments.length参与逻辑），或调用约定明确"就传两个参数"，请用calledWithExactly把约定钉死在测试里，防止未来重构时悄悄多传参数而不自知。
calledWithMatch：配合 sinon.match 的通配断言
现实测试里参数常常是"动态的"：时间戳、随机 ID、由异步返回的对象……此时calledWithMatch与 Sinon.JS 的匹配器（matcher）组合，是参数断言的最强形态。它支持sinon.match.any、sinon.match.string、sinon.match.number、sinon.match.object等内置匹配器，甚至自定义函数：
const spy = sinon.spy(); spy("Alice", 42, { role: "admin" }); spy.should.have.been.calledWithMatch( sinon.match.string, // 第一个参数是任意字符串 sinon.match.number, // 第二个参数是任意数字 sinon.match({ role: "admin" }) // 第三个参数包含该字段 ); // ✅ 全部匹配这一招尤其适合断言"参数符合某种形状"而非"参数等于某个值"，让测试在数据变动时依然稳定，避免脆弱的快照式断言。注意：sinon-chai 仅实现 spy 的方法，Sinon.assert.match的独立接口并不在范围内，匹配器本身来自 Sinon.JS 内置的 samsam 库。
加严一档：always 与 calledOnceWith 变体
上面三个方法默认是"至少有一次调用满足即可"。如果要求每一次调用都满足，可以在断言链中加入always：
spy.should.always.have.been.calledWith("A", "B"); spy.should.always.have.been.calledWithExactly("A", "B"); spy.should.always.have.been.calledWithMatch(sinon.match.string);如果要求"恰好调用一次且参数满足"，还有calledOnceWith与calledOnceWithExactly两个组合变体（实现见 lib/sinon-chai.js），一次性同时约束调用次数与参数内容，比分开写calledOnce加calledWith更清晰。此外所有断言都支持 Chai 的.not取反，例如spy.should.have.not.been.calledWith("bad")。
实战速查：到底该选哪一个？
纠结时按这个思路走一遍即可：
- 参数里有非确定值（随机数、时间、对象实例）？→ 用
calledWithMatch+sinon.match； - 调用约定要求参数个数一个不多一个不少？→ 用
calledWithExactly； - 只关心前几个关键参数，允许有多余参数？→ 用
calledWith； - 需要约束"每次都这样"或"恰好一次"？→ 叠加
always或改用calledOnceWith*变体。
三个避坑提示 🚧
calledWith不是calledWithExactly：写宽松断言时，未来若参数个数语义收紧，测试不会替你报警，请根据约定主动升级为精确断言。- 对象参数是深度比较：
calledWith与calledWithExactly对对象参数都做深度相等比较，传一个字段相同的新对象也能通过（详见 test/callArguments.js 中的对象用例），这正是我们想要的。 always的位置有讲究：必须写成spy.should.always.have.been.calledWith(...)，而不是...have.been.alwaysCalledWith(...)，否则断言链无效。
总结
calledWith、calledWithExactly、calledWithMatch构成了 sinon-chai 参数断言的三级"光谱"：从宽松的前缀匹配，到严格的完全一致，再到以匹配器为核心的形状匹配。记住一个口诀——宽匹配用 calledWith，严校验用 calledWithExactly，参数不确定用 calledWithMatch，再配合always与calledOnceWith变体，你就能把参数断言写得既准确又不脆弱。希望这份参数断言终极指南，能让你在下次写 spy 测试时少一份纠结、多一分从容！🎯
【免费下载链接】sinon-chaiExtends Chai with assertions for the Sinon.JS mocking framework.项目地址: https://gitcode.com/gh_mirrors/si/sinon-chai
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
