CHANGES.md

@@ -1,5 +1,14 @@
 # Changes
 
+## 19.0.5
+
+- [`67d19ff0`](https://github.com/sinonjs/sinon/commit/67d19ff01541fd76dceb1b753e5110b4375fb819)
+  chore: deprecate usingPromise (#2651) (Morgan Roderick)
+- [`598dddb6`](https://github.com/sinonjs/sinon/commit/598dddb6e1d65187f6410a1b7f270858ce45c857)
+  chore: deprecate useFakeXMLHttpRequest and useFakeServer (Morgan Roderick)
+
+_Released by Morgan Roderick on 2025-03-23._
+
 ## 19.0.4
 
 The release script failed half-way in 19.0.3, so re-releasing.

docs/_config.yml

@@ -5,7 +5,7 @@ description: >-
 url: 'https://sinonjs.org'
 github_username: sinonjs
 sinon:
-  current_release: v19.0.4
+  current_release: v19.0.5
   current_major_version: 19
 markdown: kramdown
 kramdown:

docs/changelog.md

@@ -6,6 +6,15 @@ permalink: /releases/changelog
 
 # Changelog
 
+## 19.0.5
+
+- [`67d19ff0`](https://github.com/sinonjs/sinon/commit/67d19ff01541fd76dceb1b753e5110b4375fb819)
+  chore: deprecate usingPromise (#2651) (Morgan Roderick)
+- [`598dddb6`](https://github.com/sinonjs/sinon/commit/598dddb6e1d65187f6410a1b7f270858ce45c857)
+  chore: deprecate useFakeXMLHttpRequest and useFakeServer (Morgan Roderick)
+
+_Released by Morgan Roderick on 2025-03-23._
+
 ## 19.0.4
 
 The release script failed half-way in 19.0.3, so re-releasing.

docs/guides/migration-guide.md

@@ -57,31 +57,28 @@ 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
+**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();
+`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.
+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
+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.
+[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`.
+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()`
@@ -108,63 +105,67 @@ Now would be a good opportunity to tidy up your tests.
 In earlier versions, you would manually have to create sandboxes and keep
 references to them in order to restore them.
 
+```js
 const sandbox = sinon.createSandbox();
 
 describe("myFunction", function () {
-afterEach(function () {
-sandbox.restore();
-});
+  afterEach(function () {
+    sandbox.restore();
+  });
 
-it("should make pie");
+  it("should make pie");
 });
+```
 
 ### From `sinon@5.0.0`
 
+```js
 describe("myFunction", function () {
-afterEach(function () {
-sinon.restore();
-});
+  afterEach(function () {
+    sinon.restore();
+  });
 
-it("should make pie");
+  it("should make pie");
 });
+```
 
 ## Sinon 4
 
-As with all `MAJOR` releases in semver http://semver.org/, there are
-breaking changes in `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.
+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
+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.
 
+```js
 var stub = sinon.stub(obj, "stubbedMethod").callsFake(function () {
-return 42;
+  return 42;
 });
+```
 
-A codemod is available https://github.com/hurrymaplelad/sinon-codemod to
+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`
+deprecated with `sinon@2` and has been removed with `sinon@3`.
 
 ## `sinon.useFakeTimers([now, ]prop1, prop2, ...)` - Removed
 
-`sinon.useFakeTimers()` signature has changed
+`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.
@@ -174,15 +175,13 @@ please use `config.toFake`. Other options are now available when configuring
 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"] }}`.
+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.
+[less error-prone tests](https://github.com/sinonjs/sinon/issues/1537#issuecomment-323948482).
 
 ## Removal of internal helpers
 
@@ -224,36 +223,39 @@ 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:
 
+```js
 sinon.log = function (msg) { // your logging impl };
+```
 
 You would now individually import and configure the utility upon creation:
 
+```js
 var sinon = require("sinon");
 
 var myFakeServer = sinon.fakeServer.create({
-logger: function (msg) { // your logging impl }
+ 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.
+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.
+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).
 
+```js
 // Old
 sinon.stub(obj, "meth", fn);
 // New
 sinon.stub(obj, "meth").callsFake(fn);
+```
 
 ## stub.resetHistory replaces stub.reset
 
@@ -262,10 +264,12 @@ 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()`.
 
+```js
 // Old
 stub.reset();
 // New
 stub.resetHistory();
+```
 
 ## Deprecation of internal helpers
 

docs/index.md

@@ -283,11 +283,11 @@ You've seen the most common tasks people tackle with Sinon.JS, yet we've only sc
 - [Testing Backbone applications with Jasmine and Sinon](https://tinnedfruit.com/writing/testing-backbone-apps-with-jasmine-sinon.html)
 - [Sinon.JS fake server live demo](https://github.com/ducin/sinon-backend-less-demo)
 
-Christian Johansen's book [Test-Driven JavaScript Development][tddjs] covers some of the design philosophy and initial sketches for Sinon.JS.
+Sinon's "father", Christian Johansen, wrote the book on [Test-Driven JavaScript Development][tddjs], which covers some of the design philosophy and initial sketches for Sinon.JS.
 
 [fakes]: /releases/v{{current_major}}/fakes
 [fakexhr]: /releases/v{{current_major}}/fake-xhr-and-server
 [fakeserver]: /releases/v{{current_major}}/fake-xhr-and-server#fake-server
 [clock]: /releases/v{{current_major}}/fake-timers
 [api-docs]: /releases/v{{current_major}}
-[tddjs]: http://tddjs.com/
+[tddjs]: https://www.oreilly.com/library/view/test-driven-javascript-development/9780321684097/

lib/sinon/default-behaviors.js

@@ -10,6 +10,9 @@ const slice = arrayProto.slice;
 const useLeftMostCallback = -1;
 const useRightMostCallback = -2;
 
+const logger = require("@sinonjs/commons").deprecated;
+const wrap = logger.wrap;
+
 function throwsException(fake, error, message) {
     if (typeof error === "function") {
         fake.exceptionCreator = error;
@@ -90,9 +93,9 @@ const defaultBehaviors = {
         fake.callsThrough = false;
     },
 
-    usingPromise: function usingPromise(fake, promiseLibrary) {
+    usingPromise: wrap(function usingPromise(fake, promiseLibrary) {
         fake.promiseLibrary = promiseLibrary;
-    },
+    }, "usingPromise has been deprecated, and will be removed in the next major version"),
 
     yields: function (fake) {
         fake.callArgAt = useLeftMostCallback;

lib/sinon/fake.js

@@ -3,6 +3,8 @@
 const arrayProto = require("@sinonjs/commons").prototypes.array;
 const createProxy = require("./proxy");
 const nextTick = require("./util/core/next-tick");
+const logger = require("@sinonjs/commons").deprecated;
+const wrap = logger.wrap;
 
 const slice = arrayProto.slice;
 let promiseLib = Promise;
@@ -165,10 +167,10 @@ fake.rejects = function rejects(value) {
  * @param {*} promiseLibrary
  * @returns {Function}
  */
-fake.usingPromise = function usingPromise(promiseLibrary) {
+fake.usingPromise = wrap(function usingPromise(promiseLibrary) {
     promiseLib = promiseLibrary;
     return fake;
-};
+}, "usingPromise has been deprecated, and will be removed in the next major version");
 
 /**
  * Returns a `fake` that calls the callback with the defined arguments.

lib/sinon/mock.js

@@ -17,6 +17,9 @@ const push = arrayProto.push;
 const slice = arrayProto.slice;
 const unshift = arrayProto.unshift;
 
+const logger = require("@sinonjs/commons").deprecated;
+const wrap = logger.wrap;
+
 function mock(object) {
     if (!object || typeof object === "string") {
         return mockExpectation.create(object ? object : "Anonymous mock");
@@ -119,11 +122,11 @@ extend(mock, {
         return true;
     },
 
-    usingPromise: function usingPromise(promiseLibrary) {
+    usingPromise: wrap(function usingPromise(promiseLibrary) {
         this.promiseLibrary = promiseLibrary;
 
         return this;
-    },
+    }, "usingPromise has been deprecated, and will be removed in the next major version"),
 
     invokeMethod: function invokeMethod(method, thisValue, args) {
         /* if we cannot find any matching files we will explicitly call mockExpection#fail with error messages */

lib/sinon/sandbox.js

@@ -2,6 +2,7 @@
 
 const arrayProto = require("@sinonjs/commons").prototypes.array;
 const logger = require("@sinonjs/commons").deprecated;
+const wrap = logger.wrap;
 const collectOwnMethods = require("./collect-own-methods");
 const getPropertyDescriptor = require("./util/core/get-property-descriptor");
 const isPropertyConfigurable = require("./util/core/is-property-configurable");
@@ -506,7 +507,7 @@ function Sandbox(opts = {}) {
         }
     };
 
-    sandbox.useFakeServer = function useFakeServer() {
+    function useFakeServer() {
         const proto = sandbox.serverPrototype || fakeServer;
 
         if (!proto || !proto.create) {
@@ -517,20 +518,35 @@ function Sandbox(opts = {}) {
         addToCollection(sandbox.server);
 
         return sandbox.server;
-    };
+    }
+
+    sandbox.useFakeServer = wrap(
+        useFakeServer,
+        "useFakeServer has been deprecated, and will be removed in the next major version",
+    );
 
-    sandbox.useFakeXMLHttpRequest = function useFakeXMLHttpRequest() {
+    function useFakeXMLHttpRequest() {
         const xhr = fakeXhr.useFakeXMLHttpRequest();
         addToCollection(xhr);
         return xhr;
-    };
+    }
 
-    sandbox.usingPromise = function usingPromise(promiseLibrary) {
+    sandbox.useFakeXMLHttpRequest = wrap(
+        useFakeXMLHttpRequest,
+        "useFakeXMLHttpRequest has been deprecated, and will be removed in the next major version",
+    );
+
+    function usingPromise(promiseLibrary) {
         promiseLib = promiseLibrary;
         collection.promiseLibrary = promiseLibrary;
 
         return sandbox;
-    };
+    }
+
+    sandbox.usingPromise = wrap(
+        usingPromise,
+        "usingPromise has been deprecated, and will be removed in the next major version",
+    );
 }
 
 Sandbox.prototype.match = match;