diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 32ad572aa..50de9a0d9 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -8,12 +8,6 @@ When you're contributing documentation changes for code in `master` branch, then If you're contributing documentation for an existing release, then your documentation changes should go into the documentation for that release in `_releases/` folder, and possibly several of the following releases also. -### Example: documenting a fixed bug - -Let us say that you are documenting a bug in `v1.17.1` that was fixed in `v1.17.4`. - -Then we would need to change the documentation for `v1.17.1`, `v1.17.2` and `v1.17.3` to mention the bug and that it was fixed in `v1.17.4`. - ## Running the documentation site locally For casual improvements to the documentation, this shouldn't really be necessary, as all the content documents are plain markdown files. diff --git a/docs/README.md b/docs/README.md index 1066378f2..8bcb344d0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,7 +6,7 @@ published: false This folder structure contains the markdown files that becomes the Sinon.JS documentation site published to GitHub Pages. Eventually this will replace the current site at https://sinonjs.org. -See [CONTRIBUTING.md](CONTRIBUTING.md) for details on contributing documentation to Sinon.JS. +See [CONTRIBUTING.md](CONTRIBUTING.md) for details on contributing documentation to Sinon.JS. This file also lists how to run the site locally. ## Documentation release process diff --git a/docs/release-source/release/examples/fakes-01-using-fakes-instead-of-spies.test.js b/docs/release-source/release/examples/fakes-01-using-fakes-instead-of-spies.test.js new file mode 100644 index 000000000..8329966ea --- /dev/null +++ b/docs/release-source/release/examples/fakes-01-using-fakes-instead-of-spies.test.js @@ -0,0 +1,15 @@ +require("@fatso83/mini-mocha").install(); +const sinon = require("sinon"); +const referee = require("@sinonjs/referee"); +const assert = referee.assert; + +it("should be able to be used instead of spies", function () { + const foo = { + bar: () => "baz", + }; + // wrap existing method without changing its behaviour + const fake = sinon.replace(foo, "bar", sinon.fake(foo.bar)); + + assert.equals(fake(), "baz"); // behaviour is the same + assert.equals(fake.callCount, 1); // calling information is saved +}); diff --git a/docs/release-source/release/examples/fakes-02-using-fakes-instead-of-stubs.test.js b/docs/release-source/release/examples/fakes-02-using-fakes-instead-of-stubs.test.js new file mode 100644 index 000000000..4373fbc2a --- /dev/null +++ b/docs/release-source/release/examples/fakes-02-using-fakes-instead-of-stubs.test.js @@ -0,0 +1,15 @@ +require("@fatso83/mini-mocha").install(); +const sinon = require("sinon"); +const referee = require("@sinonjs/referee"); +const assert = referee.assert; + +it("should be able to be used instead of stubs", function () { + const foo = { + bar: () => "baz", + }; + // replace method with a fake one + const fake = sinon.replace(foo, "bar", sinon.fake.returns("fake value")); + + assert.equals(fake(), "fake value"); // returns fake value + assert.equals(fake.callCount, 1); // saves calling information +}); diff --git a/docs/release-source/release/examples/fakes-03-creating-without-behaviour.test.js b/docs/release-source/release/examples/fakes-03-creating-without-behaviour.test.js new file mode 100644 index 000000000..0f83f1f22 --- /dev/null +++ b/docs/release-source/release/examples/fakes-03-creating-without-behaviour.test.js @@ -0,0 +1,12 @@ +require("@fatso83/mini-mocha").install(); +const sinon = require("sinon"); +const referee = require("@sinonjs/referee"); +const assert = referee.assert; + +it("should create fake without behaviour", function () { + // create a basic fake, with no behavior + const fake = sinon.fake(); + + assert.isUndefined(fake()); // by default returns undefined + assert.equals(fake.callCount, 1); // saves call information +}); diff --git a/docs/release-source/release/examples/fakes-04-creating-with-custom-behaviour.test.js b/docs/release-source/release/examples/fakes-04-creating-with-custom-behaviour.test.js new file mode 100644 index 000000000..debac1d61 --- /dev/null +++ b/docs/release-source/release/examples/fakes-04-creating-with-custom-behaviour.test.js @@ -0,0 +1,11 @@ +require("@fatso83/mini-mocha").install(); +const sinon = require("sinon"); +const referee = require("@sinonjs/referee"); +const assert = referee.assert; + +it("should create fake with custom behaviour", function () { + // create a fake that returns the text "foo" + const fake = sinon.fake.returns("foo"); + + assert.equals(fake(), "foo"); +}); diff --git a/docs/release-source/release/examples/fakes-05-returns.test.js b/docs/release-source/release/examples/fakes-05-returns.test.js new file mode 100644 index 000000000..f7524b2fd --- /dev/null +++ b/docs/release-source/release/examples/fakes-05-returns.test.js @@ -0,0 +1,10 @@ +require("@fatso83/mini-mocha").install(); +const sinon = require("sinon"); +const referee = require("@sinonjs/referee"); +const assert = referee.assert; + +it("should create a fake that 'returns'", function () { + const fake = sinon.fake.returns("apple pie"); + + assert.equals(fake(), "apple pie"); +}); diff --git a/docs/release-source/release/examples/fakes-06-throws.test.js b/docs/release-source/release/examples/fakes-06-throws.test.js new file mode 100644 index 000000000..823a09a96 --- /dev/null +++ b/docs/release-source/release/examples/fakes-06-throws.test.js @@ -0,0 +1,11 @@ +require("@fatso83/mini-mocha").install(); +const sinon = require("sinon"); +const referee = require("@sinonjs/referee"); +const assert = referee.assert; + +it("should create a fake that 'throws'", function () { + const fake = sinon.fake.throws(new Error("not apple pie")); + + // Expected to throw an error with message 'not apple pie' + assert.exception(fake, { name: "Error", message: "not apple pie" }); +}); diff --git a/docs/release-source/release/examples/fakes-07-yields.test.js b/docs/release-source/release/examples/fakes-07-yields.test.js new file mode 100644 index 000000000..75b217a84 --- /dev/null +++ b/docs/release-source/release/examples/fakes-07-yields.test.js @@ -0,0 +1,23 @@ +require("@fatso83/mini-mocha").install(); +const sinon = require("sinon"); +const referee = require("@sinonjs/referee"); +const assert = referee.assert; +const fs = require("fs"); + +it("should create a fake that 'yields'", function () { + const fake = sinon.fake.yields(null, "file content"); + const anotherFake = sinon.fake(); + + sinon.replace(fs, "readFile", fake); + fs.readFile("somefile", (err, data) => { + // called with fake values given to yields as arguments + assert.isNull(err); + assert.equals(data, "file content"); + // since yields is synchronous, anotherFake is not called yet + assert.isFalse(anotherFake.called); + + sinon.restore(); + }); + + anotherFake(); +}); diff --git a/docs/release-source/release/examples/fakes-08-yields-async.test.js b/docs/release-source/release/examples/fakes-08-yields-async.test.js new file mode 100644 index 000000000..7d16f643b --- /dev/null +++ b/docs/release-source/release/examples/fakes-08-yields-async.test.js @@ -0,0 +1,23 @@ +require("@fatso83/mini-mocha").install(); +const sinon = require("sinon"); +const referee = require("@sinonjs/referee"); +const assert = referee.assert; +const fs = require("fs"); + +it("should create a fake that 'yields asynchronously'", function () { + const fake = sinon.fake.yieldsAsync(null, "file content"); + const anotherFake = sinon.fake(); + + sinon.replace(fs, "readFile", fake); + fs.readFile("somefile", (err, data) => { + // called with fake values given to yields as arguments + assert.isNull(err); + assert.equals(data, "file content"); + // since yields is asynchronous, anotherFake is called first + assert.isTrue(anotherFake.called); + + sinon.restore(); + }); + + anotherFake(); +}); diff --git a/docs/release-source/release/examples/fakes-09-callback.test.js b/docs/release-source/release/examples/fakes-09-callback.test.js new file mode 100644 index 000000000..96be4aec6 --- /dev/null +++ b/docs/release-source/release/examples/fakes-09-callback.test.js @@ -0,0 +1,18 @@ +require("@fatso83/mini-mocha").install(); +const sinon = require("sinon"); +const referee = require("@sinonjs/referee"); +const assert = referee.assert; + +it("should have working callback", function () { + const f = sinon.fake(); + const cb1 = function () {}; + const cb2 = function () {}; + + f(1, 2, 3, cb1); + f(1, 2, 3, cb2); + + assert.isTrue(f.callback === cb2); + // spy call methods: + assert.isTrue(f.getCall(1).callback === cb2); + assert.isTrue(f.lastCall.callback === cb2); +}); diff --git a/docs/release-source/release/examples/fakes-1-using-fakes-instead-of-spies.test.js b/docs/release-source/release/examples/fakes-1-using-fakes-instead-of-spies.test.js deleted file mode 100644 index ee495dbca..000000000 --- a/docs/release-source/release/examples/fakes-1-using-fakes-instead-of-spies.test.js +++ /dev/null @@ -1,17 +0,0 @@ -require("@fatso83/mini-mocha").install(); -const sinon = require("sinon"); -const referee = require("@sinonjs/referee"); -const assert = referee.assert; - -describe("FakeTest", function () { - it("should be able to be used instead of spies", function () { - const foo = { - bar: () => "baz", - }; - // wrap existing method without changing its behaviour - const fake = sinon.replace(foo, "bar", sinon.fake(foo.bar)); - - assert.equals(fake(), "baz"); // behaviour is the same - assert.equals(fake.callCount, 1); // calling information is saved - }); -}); diff --git a/docs/release-source/release/examples/fakes-10-firstArg.test.js b/docs/release-source/release/examples/fakes-10-firstArg.test.js index 98ffae9a7..624050e74 100644 --- a/docs/release-source/release/examples/fakes-10-firstArg.test.js +++ b/docs/release-source/release/examples/fakes-10-firstArg.test.js @@ -3,15 +3,13 @@ const sinon = require("sinon"); const referee = require("@sinonjs/referee"); const assert = referee.assert; -describe("FakeTest", function () { - it("should have working firstArg", function () { - const f = sinon.fake(); - const date1 = new Date(); - const date2 = new Date(); +it("should have working firstArg", function () { + const f = sinon.fake(); + const date1 = new Date(); + const date2 = new Date(); - f(date1, 1, 2); - f(date2, 1, 2); + f(date1, 1, 2); + f(date2, 1, 2); - assert.isTrue(f.firstArg === date2); - }); + assert.isTrue(f.firstArg === date2); }); diff --git a/docs/release-source/release/examples/fakes-11-lastArg.test.js b/docs/release-source/release/examples/fakes-11-lastArg.test.js index 08aeae7a4..aac9aa225 100644 --- a/docs/release-source/release/examples/fakes-11-lastArg.test.js +++ b/docs/release-source/release/examples/fakes-11-lastArg.test.js @@ -3,19 +3,17 @@ const sinon = require("sinon"); const referee = require("@sinonjs/referee"); const assert = referee.assert; -describe("FakeTest", function () { - it("should have working lastArg", function () { - const f = sinon.fake(); - const date1 = new Date(); - const date2 = new Date(); +it("should have working lastArg", function () { + const f = sinon.fake(); + const date1 = new Date(); + const date2 = new Date(); - f(1, 2, date1); - f(1, 2, date2); + f(1, 2, date1); + f(1, 2, date2); - assert.isTrue(f.lastArg === date2); - // spy call methods: - assert.isTrue(f.getCall(0).lastArg === date1); - assert.isTrue(f.getCall(1).lastArg === date2); - assert.isTrue(f.lastCall.lastArg === date2); - }); + assert.isTrue(f.lastArg === date2); + // spy call methods: + assert.isTrue(f.getCall(0).lastArg === date1); + assert.isTrue(f.getCall(1).lastArg === date2); + assert.isTrue(f.lastCall.lastArg === date2); }); diff --git a/docs/release-source/release/examples/fakes-12-adding-fake-to-system-under-test.test.js b/docs/release-source/release/examples/fakes-12-adding-fake-to-system-under-test.test.js index 313a1a051..ebd65b43b 100644 --- a/docs/release-source/release/examples/fakes-12-adding-fake-to-system-under-test.test.js +++ b/docs/release-source/release/examples/fakes-12-adding-fake-to-system-under-test.test.js @@ -3,18 +3,16 @@ const sinon = require("sinon"); const referee = require("@sinonjs/referee"); const assert = referee.assert; -describe("FakeTest", function () { - it("should be able to be added to the system under test", function () { - const fake = sinon.fake.returns("42"); +it("should be able to be added to the system under test", function () { + const fake = sinon.fake.returns("42"); - sinon.replace(console, "log", fake); + sinon.replace(console, "log", fake); - assert.equals(console.log("apple pie"), 42); + assert.equals(console.log("apple pie"), "42"); - // restores all replaced properties set by sinon methods (replace, spy, stub) - sinon.restore(); + // restores all replaced properties set by sinon methods (replace, spy, stub) + sinon.restore(); - assert.equals(console.log("apple pie"), undefined); - assert.equals(fake.callCount, 1); - }); + assert.isUndefined(console.log("apple pie")); + assert.equals(fake.callCount, 1); }); diff --git a/docs/release-source/release/examples/fakes-2-using-fakes-instead-of-stubs.test.js b/docs/release-source/release/examples/fakes-2-using-fakes-instead-of-stubs.test.js deleted file mode 100644 index 04a272daf..000000000 --- a/docs/release-source/release/examples/fakes-2-using-fakes-instead-of-stubs.test.js +++ /dev/null @@ -1,21 +0,0 @@ -require("@fatso83/mini-mocha").install(); -const sinon = require("sinon"); -const referee = require("@sinonjs/referee"); -const assert = referee.assert; - -describe("FakeTest", function () { - it("should be able to be used instead of stubs", function () { - const foo = { - bar: () => "baz", - }; - // replace method with a fake one - const fake = sinon.replace( - foo, - "bar", - sinon.fake.returns("fake value") - ); - - assert.equals(fake(), "fake value"); // returns fake value - assert.equals(fake.callCount, 1); // saves calling information - }); -}); diff --git a/docs/release-source/release/examples/fakes-3-creating-without-behaviour.test.js b/docs/release-source/release/examples/fakes-3-creating-without-behaviour.test.js deleted file mode 100644 index 51879e0df..000000000 --- a/docs/release-source/release/examples/fakes-3-creating-without-behaviour.test.js +++ /dev/null @@ -1,14 +0,0 @@ -require("@fatso83/mini-mocha").install(); -const sinon = require("sinon"); -const referee = require("@sinonjs/referee"); -const assert = referee.assert; - -describe("FakeTest", function () { - it("should create fake without behaviour", function () { - // create a basic fake, with no behavior - const fake = sinon.fake(); - - assert.isUndefined(fake()); // by default returns undefined - assert.equals(fake.callCount, 1); // saves call information - }); -}); diff --git a/docs/release-source/release/examples/fakes-4-creating-with-custom-behaviour.test.js b/docs/release-source/release/examples/fakes-4-creating-with-custom-behaviour.test.js deleted file mode 100644 index ebb769a8a..000000000 --- a/docs/release-source/release/examples/fakes-4-creating-with-custom-behaviour.test.js +++ /dev/null @@ -1,13 +0,0 @@ -require("@fatso83/mini-mocha").install(); -const sinon = require("sinon"); -const referee = require("@sinonjs/referee"); -const assert = referee.assert; - -describe("FakeTest", function () { - it("should create fake with custom behaviour", function () { - // create a fake that returns the text "foo" - const fake = sinon.fake.returns("foo"); - - assert.equals(fake(), "foo"); - }); -}); diff --git a/docs/release-source/release/examples/fakes-5-returns.test.js b/docs/release-source/release/examples/fakes-5-returns.test.js deleted file mode 100644 index 838ca5268..000000000 --- a/docs/release-source/release/examples/fakes-5-returns.test.js +++ /dev/null @@ -1,12 +0,0 @@ -require("@fatso83/mini-mocha").install(); -const sinon = require("sinon"); -const referee = require("@sinonjs/referee"); -const assert = referee.assert; - -describe("FakeTest", function () { - it("should create a fake that 'returns'", function () { - const fake = sinon.fake.returns("apple pie"); - - assert.equals(fake(), "apple pie"); - }); -}); diff --git a/docs/release-source/release/examples/fakes-6-throws.test.js b/docs/release-source/release/examples/fakes-6-throws.test.js deleted file mode 100644 index 5dc71023c..000000000 --- a/docs/release-source/release/examples/fakes-6-throws.test.js +++ /dev/null @@ -1,13 +0,0 @@ -require("@fatso83/mini-mocha").install(); -const sinon = require("sinon"); -const referee = require("@sinonjs/referee"); -const assert = referee.assert; - -describe("FakeTest", function () { - it("should create a fake that 'throws'", function () { - const fake = sinon.fake.throws(new Error("not apple pie")); - - // Expected to throw an error with message 'not apple pie' - assert.exception(fake, { name: "Error", message: "not apple pie" }); - }); -}); diff --git a/docs/release-source/release/examples/fakes-7-yields.test.js b/docs/release-source/release/examples/fakes-7-yields.test.js deleted file mode 100644 index 70b7aa3e8..000000000 --- a/docs/release-source/release/examples/fakes-7-yields.test.js +++ /dev/null @@ -1,23 +0,0 @@ -require("@fatso83/mini-mocha").install(); -const sinon = require("sinon"); -const referee = require("@sinonjs/referee"); -const assert = referee.assert; -const fs = require("fs"); - -describe("FakeTest", function () { - it("should create a fake that 'yields'", function () { - const fake = sinon.fake.yields(null, "file content"); - const anotherFake = sinon.fake(); - - sinon.replace(fs, "readFile", fake); - fs.readFile("somefile", (err, data) => { - // called with fake values given to yields as arguments - assert.isNull(err); - assert.equals(data, "file content"); - // since yields is synchronous, anotherFake is not called yet - assert.isFalse(anotherFake.called); - }); - - anotherFake(); - }); -}); diff --git a/docs/release-source/release/examples/fakes-8-yields-async.test.js b/docs/release-source/release/examples/fakes-8-yields-async.test.js deleted file mode 100644 index 1c8d16822..000000000 --- a/docs/release-source/release/examples/fakes-8-yields-async.test.js +++ /dev/null @@ -1,23 +0,0 @@ -require("@fatso83/mini-mocha").install(); -const sinon = require("sinon"); -const referee = require("@sinonjs/referee"); -const assert = referee.assert; -const fs = require("fs"); - -describe("FakeTest", function () { - it("should create a fake that 'yields asynchronously'", function () { - const fake = sinon.fake.yieldsAsync(null, "file content"); - const anotherFake = sinon.fake(); - - sinon.replace(fs, "readFile", fake); - fs.readFile("somefile", (err, data) => { - // called with fake values given to yields as arguments - assert.isNull(err); - assert.equals(data, "file content"); - // since yields is asynchronous, anotherFake is called first - assert.isTrue(anotherFake.called); - }); - - anotherFake(); - }); -}); diff --git a/docs/release-source/release/examples/fakes-9-callback.test.js b/docs/release-source/release/examples/fakes-9-callback.test.js deleted file mode 100644 index a13b0d2e0..000000000 --- a/docs/release-source/release/examples/fakes-9-callback.test.js +++ /dev/null @@ -1,20 +0,0 @@ -require("@fatso83/mini-mocha").install(); -const sinon = require("sinon"); -const referee = require("@sinonjs/referee"); -const assert = referee.assert; - -describe("FakeTest", function () { - it("should have working callback", function () { - const f = sinon.fake(); - const cb1 = function () {}; - const cb2 = function () {}; - - f(1, 2, 3, cb1); - f(1, 2, 3, cb2); - - assert.isTrue(f.callback === cb2); - // spy call methods: - assert.isTrue(f.getCall(1).callback === cb2); - assert.isTrue(f.lastCall.callback === cb2); - }); -}); diff --git a/docs/release-source/release/fakes.md b/docs/release-source/release/fakes.md index 4c4863b89..2898e3d5a 100644 --- a/docs/release-source/release/fakes.md +++ b/docs/release-source/release/fakes.md @@ -3,15 +3,15 @@ layout: page title: Fakes - Sinon.JS breadcrumb: fakes examples: - - fakes-1-using-fakes-instead-of-spies - - fakes-2-using-fakes-instead-of-stubs - - fakes-3-creating-without-behaviour - - fakes-4-creating-with-custom-behaviour - - fakes-5-returns - - fakes-6-throws - - fakes-7-yields - - fakes-8-yields-async - - fakes-9-callback + - fakes-01-using-fakes-instead-of-spies + - fakes-02-using-fakes-instead-of-stubs + - fakes-03-creating-without-behaviour + - fakes-04-creating-with-custom-behaviour + - fakes-05-returns + - fakes-06-throws + - fakes-07-yields + - fakes-08-yields-async + - fakes-09-callback - fakes-10-firstArg - fakes-11-lastArg - fakes-12-adding-fake-to-system-under-test @@ -37,11 +37,11 @@ The created `fake` `Function`, with or without behavior has the same API as a (` #### Using fakes instead of spies -
+
#### Using fakes instead of stubs -
+
### Creating a fake @@ -49,11 +49,11 @@ Create a `fake` `Function` with or without [behavior](#fakes-with-behavior). The #### Creating a fake without behavior -
+
#### Creating a fake with custom behaviour -
+
### Fakes with behavior @@ -63,7 +63,7 @@ Fakes cannot change once created with behaviour. Creates a fake that returns the `value` argument. -
+
#### `sinon.fake.throws(value);` @@ -71,7 +71,7 @@ Creates a fake that throws an `Error` with the provided value as the `message` p If an `Error` is passed as the `value` argument, then that will be the thrown value. If any other value is passed, then that will be used for the `message` property of the thrown `Error`. -
+
#### `sinon.fake.resolves(value);` @@ -89,7 +89,7 @@ If an `Error` is passed as the `value` argument, then that will be the value of In code example below, the '[readFile](https://nodejs.org/api/fs.html#fs_fs_readfile_path_options_callback)' function of the 'fs' module is replaced with a fake function created by `sinon.fake.yields`. When the fake function is called, it always calls the last argument it received, which is expected to be a callback, with the values that the `yields` function previously took. -
+
#### `sinon.fake.yieldsAsync([value1, ..., valueN]);` @@ -97,7 +97,7 @@ Similar to `yields`, `yieldsAsync` also returns a function that when invoked, th Compare the code example below with the code example above for `yields` to see the difference. -
+
#### `sinon.fake(func);` @@ -116,7 +116,7 @@ The instance properties are the same as those of a [`sinon.spy`][spies]. The fol This property is a convenience to get a reference to the last callback passed in the last to the fake. The same convenience has been added to [spy calls](../spy-call#spycallcallback). -
+
#### `f.firstArg`