Sinon.js Mock 测试速查表 - Sinon spy/stub/mock 测试替身大全
这张速查给写单元测试时想把被测代码与它依赖的环境隔离开的 JS 开发者。内容涵盖用于观察调用的 spy、用固定返回值或抛错或异步结果去替换行为的 stub、带严格期望与 verify 的 mock、用 fake timer 快进 setTimeout 的时间控制，以及一次 restore 全部替身的 sandbox。后面章节补充了 sinon.assert 配套断言与实用模式，比如 sinon.replace 和参数匹配器。读完你应能监听某个依赖、桩掉外部调用、在测试里操控时钟，并在 teardown 时把所有替身一次性复位。
Spy 间谍 8
sinon.spy(obj, "method")包住对象方法，保留原行为同时记录每次调用信息
sinon.spy(fn)包装成 spy 函数，可统计调用次数与参数
spy.calledOnce布尔值，判断该 spy 是否恰好被调用 1 次
spy.calledWith(arg1, arg2)布尔值，判断是否曾以这些参数被调用
spy.returned(value)判断是否曾返回过指定值
spy.callCount返回累计调用次数，配合循环/重试测试用
spy.args[0]取出第一次调用传入的参数数组
spy.restore()把被包装的原方法恢复回去
Stub 桩函数 9
sinon.stub(obj, "method")替换方法为可编程的空函数，原行为被丢弃
stub.returns(value)指定每次调用都返回的固定值
stub.throws(Error)指定触发调用时抛出异常，测错误分支
stub.callsFake(fn)用自定义实现替换原函数，保留复杂逻辑
stub.resolves(value)返回 resolved 的 Promise，桩掉异步方法
stub.rejects(Error)返回 rejected 的 Promise，测异步失败路径
stub.callsArg(0)调用传入的第一个参数作为回调，模拟回调风格 API
stub.onCall(0).returns(value)按调用次序返回不同值，头几次和后续可分开配
stub.restore()恢复被替换的原方法
Mock 模拟 7
sinon.mock(obj)创建 mock 对象
mock.expects("method")期望方法被调用
expects.once()期望调用一次
expects.withArgs(arg)期望传入参数
expects.never()期望不被调用
mock.verify()验证所有期望
mock.restore()恢复并清除所有期望
Fake Timer 时间控制 6
sinon.useFakeTimers()接管 setTimeout/setInterval
clock.tick(1000)快进 1000 毫秒
clock.runAll()跑完所有已排队的定时器
clock.restore()恢复真实时间
sinon.useFakeTimers({ now: 1000 })设置初始时间
sinon.useFakeTimers({ toFake: ["setTimeout", "Date"] })仅伪造指定 API
断言与验证 6
sinon.assert.called(spy)断言 spy 被调用
sinon.assert.calledOnce(spy)断言调用一次
sinon.assert.calledWith(spy, arg)断言传入参数
sinon.assert.notCalled(spy)断言未被调用
sinon.assert.callCount(spy, 3)断言调用次数
sinon.assert.calledWithExactly(spy, arg)断言严格匹配参数
Sandbox 沙箱 5
sinon.createSandbox()创建独立沙箱（推荐 beforeEach 创建）
sandbox.spy(obj, "method")在沙箱中创建 spy
sandbox.stub(obj, "method")在沙箱中创建 stub
sandbox.useFakeTimers()在沙箱中使用假定时器
sandbox.restore()一次性恢复沙箱内所有 mock
实用模式 5
sinon.replace(obj, "method", fn)替换方法（推荐，优于直接 stub）
sinon.replaceGetter(obj, "prop", fn)替换对象 getter
sinon.replaceSetter(obj, "prop", fn)替换对象 setter
sinon.fake()创建不改变行为的 fake 函数
sinon.match({ id: sinon.match.number })参数匹配器（类型/结构匹配）
提示
- Spy 监听调用但不改变行为，Stub 替换行为，Mock 结合两者并验证期望。
- 测试后必须 restore() 恢复原方法，或用 sandbox 自动管理（推荐 afterEach 调 sandbox.restore）。
- Fake Timer 用于测试定时任务，避免真实等待，记得 tick 后 restore。
- sinon.assert 抛出错误，适合在测试框架中使用；也可直接读取 spy 属性断言。
- stub.resolves/rejects 处理 Promise，比 callsFake 包装 async 函数更简洁。
由 巧匠 维护
公开更新于 2026年7月21日，内容持续校对官方文档。