Sinon: stub doc omission about how to restore whole-object methods was confusing

[dmose]

From the current website docs:

var stub = sinon.stub(obj);
Stubs all the object's methods.

I tried to use stub.restore, and was confused to not find it there. Adding a sentence to the docs that explicitly stated that the way forward here is to use sandboxes or sinon.test() would have been very helpful.

That said, Sinon is great; thanks for all the hard work!

[mantoni]

Uhm, stub.restore() should've worked. Using Sandboxes is an alternative, but you should also be able to restore it yourself. Can you provide more details on how you used it? Maybe a small test case demonstrating the issue?

[dmose]

Interesting; I'll try to put together a minimal test case.

[mantoni]

Ah no! My bad - there is no restore on the returned object. Stubbing an entire object simply stubs out all the functions and resturns the object again. So obj.someFunction.restore() works, but you would have to do that for all of them.

Using a sanbox is what you want in your case.

Maybe we should provide a utility sinon.restore(obj) function or something that works like restore in collection.js.

[dmose]

Documenting the current lack of a restore and aiming people at the sandbox seems like the smallest amount of work to unconfuse people today. That said, adding a restore interface might well be a good idea too.

[jonnyreeves]

:+1 for a sinon.restore(obj) method, I was looking for it today :)

[mantoni]

@jonnyreeves Fancy adding it in? Look at the restore function in collection.js. It's pretty much that.

[Pyrolistical]

This is not part of the documentation http://sinonjs.org/docs/#stubs

Without reading the docs I tried stub.restore(). Should we add the method restore if doesn't already exist? It would avoid clobbering and existing restore method.

[mroderick]

This is not part of the documentation http://sinonjs.org/docs/#stubs

You're right, it isn't. I've created #810 to keep it on the radar. It should be a fairly easy contribution to make.

If you find other gaps in the documentation, please don't hesitate to create an issue for them.

Should we add the method restore if doesn't already exist? It would avoid clobbering an existing restore method.

Nobody likes surprises (in code). Where possible, the behaviour should be consistent, not conditional.