Add release documentation for v8.0.0

docs/_releases/latest.md

@@ -1,7 +1,8 @@
 ---
 layout: page
 title: API documentation - Sinon.JS
-release_id: v7.5.0
+skip_ad: true
+release_id: v8.0.0
 ---
 
 # {{page.title}} - `{{page.release_id}}`

docs/_releases/latest/examples/spies-1-pubsub.stub

@@ -0,0 +1,16 @@
+require("@fatso83/mini-mocha").install();
+var sinon = require("sinon");
+var PubSub = require("pubsub-js");
+var referee = require("@sinonjs/referee");
+var assertTrue = referee.assert;
+
+describe('PubSub', function() {
+    it("should call subscribers on publish", function () {
+        var callback = sinon.spy();
+
+        PubSub.subscribe("message", callback);
+        PubSub.publishSync("message");
+
+        assertTrue(callback.called);
+    })
+});

docs/_releases/latest/examples/spies-2-wrap-object-methods.stub

@@ -0,0 +1,31 @@
+require("@fatso83/mini-mocha").install();
+var sinon = require("sinon");
+var referee = require("@sinonjs/referee");
+var assert = referee.assert;
+var jsdom = require('jsdom');
+var JSDOM = jsdom.JSDOM;
+var window = (new JSDOM()).window;
+var document = (new JSDOM('')).window;
+var jQuery = require('jquery')(window);
+global.document = document;
+
+describe('Wrap all object method', function() {
+    var sandbox = sinon.createSandbox();
+
+    beforeEach(function() {
+        sandbox.spy(jQuery);
+    });
+
+    afterEach(function() {
+        sandbox.restore();
+    });
+
+    it("should inspect jQuery.getJSON's usage of jQuery.ajax", function () {
+        var url = "https://jsonplaceholder.typicode.com/todos/1";
+        jQuery.getJSON(url);
+
+        assert(jQuery.ajax.calledOnce);
+        assert.equals(url, jQuery.ajax.getCall(0).args[0].url);
+        assert.equals("json", jQuery.ajax.getCall(0).args[0].dataType);
+    })
+});

docs/_releases/latest/examples/spies-3-wrap-existing-method.stub

@@ -0,0 +1,31 @@
+require("@fatso83/mini-mocha").install();
+var sinon = require("sinon");
+var referee = require("@sinonjs/referee");
+var assert = referee.assert;
+var jsdom = require('jsdom');
+var JSDOM = jsdom.JSDOM;
+var window = (new JSDOM()).window;
+var document = (new JSDOM('')).window;
+var jQuery = require('jquery')(window);
+global.document = document;
+
+describe('Wrap existing method', function() {
+    var sandbox = sinon.createSandbox();
+
+    beforeEach(function() {
+        sandbox.spy(jQuery, "ajax");
+    });
+
+    afterEach(function() {
+        sandbox.restore();
+    });
+
+    it("should inspect jQuery.getJSON's usage of jQuery.ajax", function () {
+        var url = "https://jsonplaceholder.typicode.com/todos/1";
+        jQuery.getJSON(url);
+
+        assert(jQuery.ajax.calledOnce);
+        assert.equals(url, jQuery.ajax.getCall(0).args[0].url);
+        assert.equals("json", jQuery.ajax.getCall(0).args[0].dataType);
+    })
+});

docs/_releases/latest/examples/spies-4-pubsub-message-1.stub

@@ -0,0 +1,17 @@
+require("@fatso83/mini-mocha").install();
+var sinon = require("sinon");
+var PubSub = require("pubsub-js");
+var referee = require("@sinonjs/referee");
+var assert = referee.assert;
+
+describe('PubSub', function() {
+    it("should call subscribers with message as first argument", function () {
+        var message = 'an example message';
+        var spy = sinon.spy();
+
+        PubSub.subscribe(message, spy);
+        PubSub.publishSync(message, "some payload");
+
+        assert(spy.calledWith(message));
+    })
+});

docs/_releases/latest/examples/spies-5-pubsub-message-2.stub

@@ -0,0 +1,17 @@
+require("@fatso83/mini-mocha").install();
+var sinon = require("sinon");
+var PubSub = require("pubsub-js");
+var referee = require("@sinonjs/referee");
+var assert = referee.assert;
+
+describe('PubSub', function() {
+    it("should call subscribers with message as first argument", function () {
+        var message = 'an example message';
+        var spy = sinon.spy();
+
+        PubSub.subscribe(message, spy);
+        PubSub.publishSync(message, "some payload");
+
+        assert.equals(message, spy.args[0][0]);
+    })
+});

docs/_releases/latest/examples/spies-6-pubsub-message-3.stub

@@ -0,0 +1,17 @@
+require("@fatso83/mini-mocha").install();
+var sinon = require("sinon");
+var PubSub = require("pubsub-js");
+var referee = require("@sinonjs/referee");
+var assert = referee.assert;
+
+describe('PubSub', function() {
+    it("should call subscribers with message as first argument", function () {
+        var message = 'an example message';
+        var spy = sinon.spy();
+
+        PubSub.subscribe(message, spy);
+        PubSub.publishSync(message, "some payload");
+
+        assert.equals(message, spy.getCall(0).args[0]);
+    })
+});

docs/_releases/latest/examples/spies-7-with-args.stub

@@ -0,0 +1,17 @@
+require("@fatso83/mini-mocha").install();
+var sinon = require("sinon");
+var referee = require("@sinonjs/referee");
+var assert = referee.assert;
+
+describe('withArgs', function() {
+    it("should call method once with each argument", function () {
+        var object = { method: function () {} };
+        var spy = sinon.spy(object, "method");
+
+        object.method(42);
+        object.method(1);
+
+        assert(spy.withArgs(42).calledOnce);
+        assert(spy.withArgs(1).calledOnce);
+    })
+});

docs/_releases/latest/examples/spies-8-spy-call.stub

@@ -0,0 +1,30 @@
+require("@fatso83/mini-mocha").install();
+var sinon = require("sinon");
+var referee = require("@sinonjs/referee");
+var assert = referee.assert;
+var jsdom = require('jsdom');
+var JSDOM = jsdom.JSDOM;
+var window = (new JSDOM()).window;
+var document = (new JSDOM('')).window;
+var jQuery = require('jquery')(window);
+global.document = document;
+
+describe('Return nth call', function() {
+    var sandbox = sinon.createSandbox();
+
+    beforeEach(function() {
+        sandbox.spy(jQuery, "ajax");
+    });
+
+    afterEach(function() {
+        sandbox.restore();
+    });
+
+    it("should inspect jQuery.getJSON's usage of jQuery.ajax", function () {
+        var url = "https://jsonplaceholder.typicode.com/todos/1";
+        jQuery.ajax(url);
+        var spyCall = jQuery.ajax.getCall(0);
+
+        assert.equals(url, spyCall.args[0]);
+    })
+});

docs/_releases/latest/fakes.md

@@ -6,36 +6,49 @@ breadcrumb: fakes
 
 ### Introduction
 
-`fake` was introduced with Sinon with v5. It simplifies and merges concepts from [`spies`][spies] and [`stubs`][stubs].
+`fake` is available in Sinon from v5 onwards. It allows creation of a `fake` `Function` with the ability to set a default [behavior](#fakes-with-behavior). Set the [behavior](#fakes-with-behavior) using `Functions` with the same API as those in a [`sinon.stub`][stubs]. The created `fake` `Function`, with or without behavior has the same API as a (`sinon.spy`)[spies].
 
 In Sinon, a `fake` is a `Function` that records arguments, return value, the value of `this` and exception thrown (if any) for all of its calls.
 
-It can be created with or without behavior; it can wrap an existing function.
-
 A fake is immutable: once created, the behavior will not change.
 
 Unlike [`sinon.spy`][spies] and [`sinon.stub`][stubs] methods, the `sinon.fake` API knows only how to create fakes, and doesn't concern itself with plugging them into the system under test. To plug the fakes into the system under test, you can use the [`sinon.replace*`](../sandbox#sandboxreplaceobject-property-replacement) methods.
 
-
 ### Creating a fake
 
+Create a `fake` `Function` with or without [behavior](#fakes-with-behavior). The created `Function` has the same API as a [`sinon.spy`][spies].
+
+#### Creating a fake without behavior
+
 ```js
 // create a basic fake, with no behavior
 var fake = sinon.fake();
 
 fake();
+// undefined
 
-console.log(fake.callCount);
+fake.callCount;
 // 1
 ```
 
+#### Creating a fake with custom behaviour
+
+```js
+// create a fake that returns the text "foo"
+var fake = sinon.fake.returns('foo');
+
+fake()
+// foo
+```
+
 ### Fakes with behavior
 
-Fakes can be created with behavior, which cannot be changed once the fake has been created.
+Fakes cannot change once created with behaviour.
 
 #### `sinon.fake.returns(value);`
 
-Creates a fake that returns the `value` argument
+Creates a fake that returns the `value` argument.
+
 
 ```js
 var fake = sinon.fake.returns('apple pie');
@@ -48,6 +61,7 @@ fake();
 
 Creates a fake that throws an `Error` with the provided value as the `message` property.
 
+
 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`.
 
 ```js
@@ -61,16 +75,19 @@ fake();
 
 Creates a fake that returns a resolved `Promise` for the passed value.
 
+
 #### `sinon.fake.rejects(value);`
 
 Creates a fake that returns a rejected `Promise` for the passed value.
 
+
 If an `Error` is passed as the `value` argument, then that will be the value of the promise. If any other value is passed, then that will be used for the `message` property of the `Error` returned by the promise.
 
 #### `sinon.fake.yields([value1, ..., valueN]);`
 
 `sinon.fake.yields` takes some values, and returns a function that when being called, expects the last argument to be a callback and invokes that callback with the same previously given values. The returned function is normally used to fake a service function that takes a callback as the last argument.
 
+
  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.
 
 ```js
@@ -85,6 +102,7 @@ console.log('end of this event loop');
 
 Similar to `yields`, `yieldsAsync` also returns a function that when invoked, the function expects the last argument to be a callback and invokes that callback with the same previously given values. However, the returned function invokes that callback asynchronously rather than immediately, i.e. in the next event loop.
 
+
 Compare the output of the code example below with the output of the code example above for `yields` to see the difference.
 
 ```js
@@ -100,10 +118,14 @@ console.log('end of this event loop');
 
 Wraps an existing `Function` to record all interactions, while leaving it up to the `func` to provide the behavior.
 
+The created `fake` `Function` has the same API as a [`sinon.spy`][spies].
+
 This is useful when complex behavior not covered by the `sinon.fake.*` methods is required or when wrapping an existing function or method.
 
 ### Instance properties
 
+The instance properties are the same as a [`sinon.spy`][spies].
+
 #### `f.callback`
 
 This property is a convenience to get a reference to the last callback passed in the last to the fake.

docs/_releases/latest/sandbox.md

@@ -64,6 +64,7 @@ Creates a new sandbox object with spies, stubs, and mocks.
 
 The `sinon.createSandbox(config)` method is often an integration feature, and can be used for scenarios including a global object to coordinate all fakes through.
 
+
 Sandboxes are partially configured by default such that calling:
 
 ```javascript
@@ -82,7 +83,7 @@ var sandbox = sinon.createSandbox({
 });
 ```
 
-The `useFakeTimers` and `useFakeServers` are **false** as opposed to the defaults in `sinon.defaultConfig`:
+The `useFakeTimers` and `useFakeServers` are **false** as opposed to the [defaults in `sinon.defaultConfig`](https://github.com/sinonjs/sinon/blob/master/lib/sinon/util/core/default-config.js):
 
 ```javascript
 sinon.defaultConfig = {
@@ -118,6 +119,19 @@ What properties to inject. Note that only naming "server" here is not
 sufficient to have a `server` property show up in the target object, you also
 have to set `useFakeServer` to `true`.
 
+The list of properties that can be injected are the ones exposed by the object
+returned by the function `inject`, namely:
+
+```javascript
+{
+    //...
+    properties: [
+        "spy", "stub", "mock", "createStubInstance", "fake", "replace",
+        "replaceSetter", "replaceGetter", "clock", "server", "requests", "match"
+    ]
+}
+```
+
 ##### useFakeTimers
 
 If set to `true`, the sandbox will have a `clock` property. You can optionally pass
@@ -137,6 +151,22 @@ sinon.config = {
 };
 ```
 
+##### exposing sandbox example
+
+To create an object `sandboxFacade` which gets the method `spy` injected, you
+can code:
+
+```javascript
+// object that will have the spy method injected into it
+var sandboxFacade = {};
+
+// create sandbox and inject properties (in this case spy) into sandboxFacade
+var sandbox = sinon.createSandbox({
+    injectInto: sandboxFacade,
+    properties: ["spy"]
+});
+```
+
 #### `sandbox.assert();`
 
 A convenience reference for [`sinon.assert`](./assertions)