Sinon.js Mock 测试速查表 - Sinon spy/stub/mock 测试替身大全

按「要不要改变行为、要不要写死期望」分。sinon.spy(obj, "method") 包住原方法但保留原行为，只记录调用，之后读 calledOnce、calledWith(arg1, arg2)、returned(value)、callCount、args[0] 即可，适合验证「有没有被正确调用」。sinon.stub(obj, "method") 把方法替换成可编程的空函数，原行为被丢弃，再用 returns / throws / resolves / rejects 决定返回什么，适合隔离依赖。sinon.mock(obj) 则是把两者合一：先 expects("method") 声明调用次数（once、never）与参数，最后 mock.verify() 统一校验，语法更重，只在期望密集时值得。

典型原因是替身没有还原，全局污染了后续用例。本表给出的正解是沙箱：在 beforeEach 里 sinon.createSandbox()，之后一律用 sandbox.spy / sandbox.stub / sandbox.useFakeTimers 创建替身，afterEach 里调 sandbox.restore() 一次性还原全部 spy、stub 和假定时器。手动方式则是每个 spy/stub 单独调 restore()。fake timer 尤其容易漏：clock.tick(1000) 快进之后如果不 clock.restore()，后面所有依赖真实时间的逻辑都会停在原地。判断依据很直接：如果失败用例依赖某个全局对象（Date、setTimeout、被替换的方法），就先去查前一个用例是否遗留了替身。

用 sinon.useFakeTimers() 接管 setTimeout 和 setInterval，然后靠 clock 操作虚拟时间：clock.tick(1000) 快进 1000 毫秒，只触发这段时间内到期的回调；clock.runAll() 一次跑完所有已排队的定时器，适合把循环调度一次跑干净。要固定起点时间就用 sinon.useFakeTimers({ now: 1000 })；只想伪造部分 API 以免影响其它代码，用 sinon.useFakeTimers({ toFake: ["setTimeout", "Date"] }) 精确指定。测完必须 clock.restore()，或者交给沙箱统一还原。整套下来毫秒级完成，且断言的是回调真正执行后的状态。

优先用 resolves 和 rejects：stub.resolves(value) 直接返回一个 resolved 的 Promise，stub.rejects(Error) 返回 rejected 的 Promise，专测异步成功与失败路径，比用 callsFake 手写一个 async 函数再 await 要短得多。只有当被替换的方法不是返回 Promise、或者你需要保留复杂多步逻辑时，才用 stub.callsFake(fn) 提供自定义实现。旧式回调风格 API 则用 stub.callsArg(0) 触发传入的第一个参数当作回调。同一方法的多次调用需要不同结果时，用 stub.onCall(0).returns(value) 按调用次序配置。

先确认三件事：期望是不是真没被调用（expects.never() 被违反），还是调用次数对了但参数对不上（expects.withArgs(arg) 不匹配）——后者应换成更宽的 sinon.match({ id: sinon.match.number }) 这类按类型或结构匹配的匹配器，只在关键字段上收紧。还要检查传入值是不是被前面的测试替身污染了。若根本不需要严格的「期望式」校验，mock 的语法负担不划算，改用 spy 加断言更直接：sinon.assert.called(spy)、sinon.assert.calledOnce(spy)、sinon.assert.calledWith(spy, arg)、sinon.assert.notCalled(spy)、sinon.assert.callCount(spy, 3)、sinon.assert.calledWithExactly(spy, arg)，失败信息会指向具体的调用记录。