` 与测试框架对接)
Sinon 断言集成指南：深入解析assert.expose(target, options)与测试框架对接
【免费下载链接】sinonTest spies, stubs and mocks for JavaScript.项目地址: https://gitcode.com/gh_mirrors/si/sinon
assert.expose是 Sinon 断言模块提供的一个集成性 API，用于将 sinon.assert 上全部断言方法"镜像"到任意目标对象上，从而与第三方测试框架（如 sinon-chai、jest-sinon、referee-sinon）无缝衔接。读完本文，你将掌握expose的完整签名、prefix与includeFail两个选项的精确行为、底层源码实现原理，以及如何在自己的测试工具或断言库中复用它。
为什么需要assert.expose
Sinon 内置的 断言集合 覆盖了called、calledWith、threw、callOrder等几乎所有 spy/stub/fake 行为验证，与直接在 fake 上读取属性相比，断言失败时会抛出带有详细信息的AssertError。但sinon.assert的方法都挂在sinon.assert命名空间下，调用形式固定为sinon.assert.called(spy)。
当你想把断言集成进自己团队的断言库，或者像 sinon-chai 那样在 Chai 上暴露spy.should.have.been.called风格的链式断言时，就需要把sinon.assert的方法整体"移植"到另一个对象上——这正是assert.expose的职责：将断言暴露到另一个对象中，以便与测试框架集成。
API 签名与两个关键选项
assert.expose的调用形式为：
assert.expose(target, options);它接收一个必填的目标对象target和可选的options对象，并返回该target（便于链式调用）。options支持两个选项：
| 选项 | 默认值 | 作用 |
|---|---|---|
prefix | "assert" | 暴露到目标对象上的方法名前缀 |
includeFail | true | 是否同时复制fail和failException属性 |
prefix：控制暴露方法的命名
默认情况下，sinon.assert.called会变成target.assertCalled——即把assert作为前缀，并将原方法名首字母大写后拼接。通过传入空字符串""，可以去掉前缀，使暴露出来的方法名与原断言方法名一致：sinon.assert.called变成target.called。
const myAssert = {}; sinon.assert.expose(myAssert, { prefix: "" }); // 此时 myAssert 上可以直接使用： myAssert.called(fake); myAssert.calledOnce(fake); myAssert.calledWith(fake, "arg");includeFail：控制失败相关属性
该选项默认为true，会把fail和failException这两个与"断言失败"直接相关的属性一并复制到目标对象。断言框架通常需要拦截失败信号来终止测试（详见下文"与断言失败机制的联动"），因此默认开启。当你明确不希望目标对象携带fail相关能力时，可显式传入false。
源码视角：expose到底做了什么
在 src/sinon/assert.js 中，expose的实现非常直白，核心逻辑分四步：
- 空值保护：
target为null或undefined时，直接抛出TypeError("target is null or undefined")，避免静默失败。 - 解析选项：
prefix缺省时取"assert"；includeFail缺省时取true。 - 遍历自身断言方法：通过
Object.keys(instance)枚举断言对象上的所有方法，跳过expose自身，并在includeFail为false时跳过所有以fail开头的方法（正则/^(fail)/判断）。 - 计算暴露名并赋值：调用内部工具函数
exposedName（见 src/sinon/assert.js）计算目标属性名，然后赋值并返回target。
exposedName的命名规则与文档描述完全一致：
function exposedName(prefix, prop) { return !prefix || /^fail/.test(prop) ? prop : prefix + prop[0].toUpperCase() + prop.slice(1); }- 未指定
prefix时，保留原始方法名（如fail、pass、match、callOrder）； - 指定
prefix时，将首字母大写后拼接前缀（如called→assertCalled）； - 以
fail开头的方法（fail、failException）不受 prefix 影响，始终使用原名，这是为了让断言框架能稳定地通过target.fail拦截失败。
从源码结构看，expose是在 createAssertObject 工厂函数内部与fail、pass、callOrder、callCount、match等一起定义，随后经由mirrorPropAsAssertion批量生成的called、calledWith、threw等二十余个断言方法也全部在同一对象上，因此一次Object.keys即可完整复制整个断言集合。
完整可运行示例
仓库中的测试 docs/tests/docs/assertions/api/expose.test.js 给出了最典型的用法：把断言以无前缀形式暴露到空对象上，再验证断言真实可用。
import t from "tap"; import sinon from "sinon"; t.test("assert.expose integrates assertions into another object", (t) => { // 创建目标对象 const myAssert = {}; // 以空前缀暴露全部断言 sinon.assert.expose(myAssert, { prefix: "" }); // 断言方法已被正确暴露 t.ok(myAssert.called, "should have 'called' assertion"); t.ok(myAssert.calledOnce, "should have 'calledOnce' assertion"); t.ok(myAssert.calledWith, "should have 'calledWith' assertion"); // 暴露出来的断言与原生 sinon.assert 行为一致 const fake = sinon.fake(); fake("arg"); t.doesNotThrow(() => myAssert.called(fake), "exposed assertion should work"); t.end(); });另一个贴近真实场景的示例——用默认前缀暴露并验证spy.should.have.been.called风格的链式能力：
import * as sinon from "sinon"; const target = {}; sinon.assert.expose(target); // 默认前缀下： target.assertCalled(spy); // 等价于 sinon.assert.called(spy) target.assertCalledWith(spy, "arg"); // 链式风格（类似 sinon-chai 的 should 接口）： // spy.should.have.been.called // 这类用法需要进一步在目标对象上叠加 should 风格 API， // 而 expose 负责提供底层的 called / calledWith 等断言能力与测试框架集成的完整链路
expose只是把断言方法搬运到目标对象上，真正让断言在框架中"生效"还需要配合失败处理。Sinon 给出的集成建议（见 断言概念文档）是：
为了让断言与你的断言框架优雅集成，应当定制
sinon.assert.fail，并关注sinon.assert.expose与sinon.assert.pass。
与fail的联动
sinon.assert.fail是每一个断言在失败时都会调用的方法，默认行为是抛出一个name为AssertError的 Error 对象。由于includeFail默认把fail原样暴露到目标对象上，测试框架可以：
- 若框架按错误类型识别断言失败：保留默认的
AssertError抛出行为即可； - 若框架需要自定义失败信号：覆盖
target.fail或sinon.assert.fail，把消息交给框架自身的失败通道（如assert.fail()、t.fail()、expect(...).fail()）。
从源码看，所有断言最终都汇聚到内部的failAssertion（见 src/sinon/assert.js），它会优先调用断言调用方对象上的fail方法，否则回退到assert.fail。这就是expose后目标对象上的fail能被断言调用到的机制基础。
生态中的既有集成
Sinon 生态中已有多个基于类似思路的集成项目，可作为参考：
- sinon-chai：在 Chai 上暴露
spy.should.have.been.called等链式断言（即文档开头提到的例子）； - jest-sinon：为 Jest 提供
expect(spy).toHaveBeenCalled()风格的匹配器； - referee-sinon：由 Sinon 官方维护者开发的 referee 断言集成。
这些项目正是assert.expose设计初衷的落地案例——把 Sinon 的断言能力"注入"宿主框架的断言体系。
注意事项与边界情况
- 目标对象必填：传入
null或undefined会抛出TypeError，请确保调用前target已初始化。 expose自身不会被复制：源码中通过method !== "expose"显式排除，避免无限递归式暴露。fail相关属性不受前缀影响：无论prefix取何值，fail与failException都以原名暴露，保证框架侧引用稳定。- 返回值为
target：可链式使用，也可在返回后继续向目标对象追加自定义方法。 includeFail: false的过滤粒度：实现层面用正则/^(fail)/匹配，所有以fail开头的属性都会被排除，而不仅是fail与failException两个。
小结
assert.expose(target, options)是 Sinon 面向测试框架生态开放的关键接口：通过prefix定制暴露命名、通过includeFail控制失败机制的迁移，一次调用即可把完整的断言集合镜像到目标对象。理解其源码实现（空值校验、exposedName命名规则、/^(fail)/过滤逻辑）后，你既可以按默认方式接入既有框架，也可以据此构建自己的轻量断言集成层。
进一步阅读：Assertions API 索引、断言概念总览、assert.fail详解、assert.pass详解、断言核心实现。
【免费下载链接】sinonTest spies, stubs and mocks for JavaScript.项目地址: https://gitcode.com/gh_mirrors/si/sinon
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
