Migrating between versions

Sinon 19

All timers are stubbed by default

A breaking change is that Fake Timers 13 now fake all timers by default. Previously Node’s nextTick() and Window#queueMicroTask() were explicitly skipped, which was quite confusing to some. This typically might affect async tests where you rely on some Node function that invokes nextTick under the hood. See issue #2619 for such an example and a suggestion on how one could employ clock#runToLastAsync() in asynchronous tests that stopped resolving in Sinon 19.

If you want the old behavior, specify the timers you want to fake in the toFake option and leave out the name of the timers giving you trouble.

New implementation of the fake Date class

The new version of fake-timers also no longer creating dates using the original Date class, but a subclass (proxy). This should not matter unless you are doing some kind of identity checks on the constructor: functionally they are the same. See (fake-timers#504) for an example (which we ended up pushing a small fix for to make instanceof work as before).

Removal of `useFakeServer({legacyRoutes: true})`

The legacyRoutes option that was enabled in a previous version has been removed. An underlying library, path-to-regexp, had a fundamental change to its parsing that made the option a no-op. This should not affect most users of Sinon.

Sinon 18

Mostly removal of some deprecated exports related to sinon-test, such as sinon.defaultConfig and related modules.

Sinon 17

Drops support for Node 16

Sinon 15

Removes option to pass a custom formatter.

Sinon 7

For users upgrading to Sinon 7 the only known breaking API change is that negative ticks are not allowed in Sinon@7 due to updating to lolex 3 internally. This means you cannot use negative values in sinon.useFakeTimers().tick();

If you experience any issues moving from Sinon 6 to Sinon 7, please let us know! https://github.com/sinonjs/sinon/issues/new?template=Bug_report.md.

Sinon 6

There should be no reason for any code changes with the new Sinon 6. Usually, MAJOR releases should come with breaking changes, but there are no known breaking changes in sinon@6 at the time of this writing. We chose to release a new major version as a pragmatic solution to some noise related to releasing Sinon 5.1 https://github.com/sinonjs/sinon/pull/1829#issue- 193284761, which featured some breaking changes related to ESM (which since has been resolved).

If you should experience any issues moving from Sinon 5 to Sinon 6, please let us know! https://github.com/sinonjs/sinon/issues/new?template=Bug_report.md.

Sinon 5

As with all MAJOR releases in semver http://semver.org/, there are breaking changes in sinon@5. This guide will walk you through those changes.

`spy.reset()` is removed, use `spy.resetHistory()`

In a previous version we deprecated and aliased spy.reset in favour of using spy.resetHistory. spy.reset has now been removed, you should use spy.resetHistory.

`sinon` is now a (default) sandbox

Since sinon@5.0.0, the sinon object is a default sandbox. Unless you have a very advanced setup or need a special configuration, you probably want to only use that one.

The old sandbox API is still available, so you don’t have to do anything.

However, switching to using the default sandbox can help make your code more concise. Now would be a good opportunity to tidy up your tests.

Before `sinon@5.0.0`

In earlier versions, you would manually have to create sandboxes and keep references to them in order to restore them.

const sandbox = sinon.createSandbox();

describe(“myFunction”, function () { afterEach(function () { sandbox.restore(); });

it(“should make pie”); });

From `sinon@5.0.0`

describe(“myFunction”, function () { afterEach(function () { sinon.restore(); });

it(“should make pie”); });

Sinon 4

As with all MAJOR releases in semver http://semver.org/, there are breaking changes in sinon@4. This guide will walk you through those changes.

`sinon.stub(obj, 'nonExistingProperty')` - Throws

Trying to stub a non-existing property will now fail, to ensure you are creating less error-prone tests https://github.com/sinonjs/sinon/pull/1557.

Sinon 3

As with all MAJOR releases in semver http://semver.org/, there are breaking changes in sinon@3. This guide will walk you through those changes.

`sinon.stub(object, "method", func)` - Removed

Please use sinon.stub(obj, "method").callsFake(func) instead.

var stub = sinon.stub(obj, “stubbedMethod”).callsFake(function () { return 42; });

A codemod is available https://github.com/hurrymaplelad/sinon-codemod to upgrade your code

`sinon.stub(object, property, value)` - Removed

Calling sinon.stub with three arguments will throw an Error. This was deprecated with sinon@2 and has been removed with sinon@3

`sinon.useFakeTimers([now, ]prop1, prop2, ...)` - Removed

sinon.useFakeTimers() signature has changed To define which methods to fake, please use config.toFake. Other options are now available when configuring useFakeTimers. Please consult the documentation for more information.

`sinon.sandbox.create(config)` - Config changes

The changes in configuration for fake timers implicitly affect sandbox creation. If your config used to look like { useFaketimers: ["setTimeout", "setInterval"]}, you will now need to change it to { useFaketimers: { toFake: ["setTimeout", "setInterval"] }}.

`sandbox.stub(obj, 'nonExistingProperty')` - Throws

Trying to stub a non-existing property will now fail to ensure you are creating less error-prone tests https://github.com/sinonjs/sinon/issues/1537#issuecomment-323948482.

Removal of internal helpers

The following internal functions were deprecated as of sinon@1.x and have been removed in sinon@3:

• sinon.calledInOrder • sinon.create • sinon.deepEqual • sinon.format • sinon.functionName • sinon.functionToString • sinon.getConfig • sinon.getPropertyDescriptor • sinon.objectKeys • sinon.orderByFirstCall • sinon.restore • sinon.timesInWorlds • sinon.valueToString • sinon.walk • sinon.wrapMethod • sinon.Event • sinon.CustomEvent • sinon.EventTarget • sinon.ProgressEvent • sinon.typeOf • sinon.extend

Sinon 2

Sinon v2.0 is the second major release, we have made several breaking changes in this release as a result of modernising the internals of Sinon. This guide is intended to walk you through the changes.

sinon.log and sinon.logError Removed

sinon.log and sinon.logError were used in Sinon v1.x to globally configure FakeServer, FakeXMLHttpRequest and FakeXDomainRequest; these three functions now allow the logger to be configured on a per-use basis. In v1.x you may have written:

sinon.log = function (msg) { // your logging impl };

You would now individually import and configure the utility upon creation:

var sinon = require(“sinon”);

var myFakeServer = sinon.fakeServer.create({ logger: function (msg) { // your logging impl } });

sinon.test, sinon.testCase and sinon.config Removed

sinon.test and sinon.testCase have been extracted from the Sinon API and moved into their own node module, sinon-test https://www.npmjs.com/package/sinon-test. Please refer to the sinon-test README https://github.com/sinonjs/sinon-test/blob/master/README.md for migration examples.

stub.callsFake replaces stub(obj, ‘meth’, fn)

sinon.stub(obj, 'meth', fn) return a spy, not a full stub. Behavior could not be redefined. stub.callsFake now returns a full stub. Here’s a codemod script https://github.com/hurrymaplelad/sinon-codemod to help you migrate. See discussion https://github.com/sinonjs/sinon/pull/823.

// Old sinon.stub(obj, “meth”, fn); // New sinon.stub(obj, “meth”).callsFake(fn);

stub.resetHistory replaces stub.reset

stub.reset() now resets the history and the behaviour of the stub. Previously stub.reset() only reset the history of the stub. Stubs now have separate methods for resetting the history and the behaviour. To mimic the old behaviour replace all stub.reset() calls with stub.resetHistory().

// Old stub.reset(); // New stub.resetHistory();

Deprecation of internal helpers

The following utility functions are being marked as deprecated and are planned for removal in Sinon v3.0; please check your codebase for usage to ease future migrations:

`sandbox.useFakeXMLHttpRequest` no longer returns a “server”

In Sinon 1.x, the sandbox’ useFakeXMLHttpRequest was the same as its useFakeServer. In 2.x, it maps directly to sinon.useFakeXMLHttpRequest (but with sandboxing). If you use sandbox.useFakeXMLHttpRequest, replace it with sandbox.useFakeServer, and your tests should behave as they always did.

`sinon.behavior` is gone

The sinon.behavior object is no longer exposed for random modification. However, there is a new mechanism in place aided to add new behavior to stubs, sinon.addBehavior(name, fn), see the stub docs.