Add release documentation for v16

docs/_releases/latest.md

@@ -2,8 +2,8 @@
 layout: page
 title: API documentation - Sinon.JS
 skip_ad: true
-release_id: v15.2.0
-sort_id: v15
+release_id: v16.0.0
+sort_id: v16
 ---
 
 # {{page.title}} - `{{page.release_id}}`

docs/_releases/latest/sandbox.md

@@ -4,7 +4,7 @@ title: Sandboxes - Sinon.JS
 breadcrumb: sandbox
 ---
 
-Sandboxes removes the need to keep track of every fake created, which greatly simplifies cleanup.
+Sandboxes remove the need to keep track of every fake created, which greatly simplifies cleanup.
 
 ```javascript
 var sandbox = require("sinon").createSandbox();
@@ -181,6 +181,38 @@ A convenience reference for [`sinon.assert`](./assertions)
 
 _Since `sinon@2.0.0`_
 
+#### `sandbox.define(object, property, value);`
+
+Defines the `property` on `object` with the value `value`. Attempts to define an already defined value cause an exception.
+
+`value` can be any value except `undefined`, including `spies`, `stubs` and `fakes`.
+
+```js
+var myObject = {};
+
+sandbox.define(myObject, "myValue", "blackberry");
+
+sandbox.define(myObject, "myMethod", function () {
+  return "strawberry";
+});
+
+console.log(myObject.myValue);
+// blackberry
+
+console.log(myObject.myMethod());
+// strawberry
+
+sandbox.restore();
+
+console.log(myObject.myValue);
+// undefined
+
+console.log(myObject.myMethod);
+// undefined
+```
+
+_Since `sinon@15.3.0`_
+
 #### `sandbox.replace(object, property, replacement);`
 
 Replaces `property` on `object` with `replacement` argument. Attempts to replace an already replaced value cause an exception. Returns the `replacement`.

docs/_releases/v16.md

@@ -0,0 +1,40 @@
+---
+layout: page
+title: API documentation - Sinon.JS
+skip_ad: true
+release_id: v16.0.0
+sort_id: v16
+---
+
+# {{page.title}} - `{{page.release_id}}`
+
+This page contains the entire Sinon.JS API documentation along with brief introductions to the concepts Sinon implements.
+
+- [General setup](./general-setup)
+- [Fakes](./fakes)
+- [Spies](./spies)
+- [Stubs](./stubs)
+- [Mocks](./mocks)
+- [Spy calls](./spy-call)
+- [Promises](./promises)
+- [Fake timers](./fake-timers)
+- [Fake <code>XHR</code> and server](./fake-xhr-and-server)
+- [JSON-P](./json-p)
+- [Assertions](./assertions)
+- [Matchers](./matchers)
+- [Sandboxes](./sandbox)
+- [Utils](./utils)
+
+{% include docs/migration-guides.md %}
+
+## Compatibility and supported runtimes
+
+As of Sinon 10 we stopped maintaining compatibility with legacy browsers. Instead, we focus on compatibility with evergreen browsers, [Node.js LTS versions](https://github.com/nodejs/Release) and recent Safari versions.
+The most up-to-date reference on which runtimes and browsers we support can be found by looking at our [compatibility docs][compat-doc].
+
+If you need to support old runtimes you can try [Sinon 9][compat-doc-v9].
+
+{% include docs/contribute.md %}
+
+[compat-doc]: https://github.com/sinonjs/sinon/COMPATIBILITY.md
+[compat-doc-v9]: https://github.com/sinonjs/sinon/blob/v9.2.4/COMPATIBILITY.md

docs/_releases/v16/assertions.md

@@ -0,0 +1,196 @@
+---
+layout: page
+title: Assertions - Sinon.JS
+breadcrumb: assertions
+---
+
+Sinon.JS ships with a set of assertions that mirror most behavior verification methods and properties on spies and stubs. The advantage of using the assertions is that failed expectations on stubs and spies can be expressed directly as assertion failures with detailed and helpful error messages.
+
+To make sure assertions integrate nicely with your test framework, you should customize either `sinon.assert.fail` or `sinon.assert.failException` and look into `sinon.assert.expose` and `sinon.assert.pass`.
+
+The assertions can be used with either spies or stubs.
+
+```javascript
+"test 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");
+
+    sinon.assert.calledOnce(spy);
+    sinon.assert.calledWith(spy, message);
+}
+```
+
+## Assertions API
+
+#### `sinon.assert.fail(message)`
+
+Every assertion fails by calling this method.
+
+By default it throws an error of type `sinon.assert.failException`.
+
+If the test framework looks for assertion errors by checking for a specific exception, you can override the kind of exception thrown. If that does not fit with your testing framework of choice, override the `fail` method to do the right thing.
+
+#### `sinon.assert.failException;`
+
+Defaults to `AssertError`.
+
+#### `sinon.assert.pass(assertion);`
+
+Called every time `assertion` passes.
+
+Default implementation does nothing.
+
+#### `sinon.assert.notCalled(spy);`
+
+Passes if `spy` was never called
+
+#### `sinon.assert.called(spy);`
+
+Passes if `spy` was called at least once.
+
+#### `sinon.assert.calledOnce(spy);`
+
+Passes if `spy` was called once and only once.
+
+#### `sinon.assert.calledTwice(spy);`
+
+Passes if `spy` was called exactly twice.
+
+#### `sinon.assert.calledThrice(spy)`
+
+Passes if `spy` was called exactly three times.
+
+#### `sinon.assert.callCount(spy, num)`
+
+Passes if `spy` was called exactly `num` times.
+
+#### `sinon.assert.callOrder(spy1, spy2, ...)`
+
+Passes if provided spies were called in the specified order.
+
+#### `sinon.assert.calledOn(spyOrSpyCall, obj)`
+
+Passes if `spy` was ever called with `obj` as its `this` value.
+
+It's possible to assert on a dedicated spy call: `sinon.assert.calledOn(spy.firstCall, arg1, arg2, ...);`.
+
+#### `sinon.assert.alwaysCalledOn(spy, obj)`
+
+Passes if `spy` was always called with `obj` as its `this` value.
+
+#### `sinon.assert.calledWith(spyOrSpyCall, arg1, arg2, ...);`
+
+Passes if `spy` was called with the provided arguments.
+
+It's possible to assert on a dedicated spy call: `sinon.assert.calledWith(spy.firstCall, arg1, arg2, ...);`.
+
+#### `sinon.assert.alwaysCalledWith(spy, arg1, arg2, ...);`
+
+Passes if `spy` was always called with the provided arguments.
+
+#### `sinon.assert.neverCalledWith(spy, arg1, arg2, ...);`
+
+Passes if `spy` was never called with the provided arguments.
+
+#### `sinon.assert.calledWithExactly(spyOrSpyCall, arg1, arg2, ...);`
+
+Passes if `spy` was called with the provided arguments and no others.
+
+It's possible to assert on a dedicated spy call: `sinon.assert.calledWithExactly(spy.getCall(1), arg1, arg2, ...);`.
+
+#### `sinon.assert.calledOnceWithExactly(spyOrSpyCall, arg1, arg2, ...);`
+
+Passes if `spy` was called once and only once with the provided arguments and no others.
+
+It's possible to assert on a dedicated spy call: `sinon.assert.calledOnceWithExactly(spy.getCall(1), arg1, arg2, ...);`.
+
+#### `sinon.assert.alwaysCalledWithExactly(spy, arg1, arg2, ...);`
+
+Passes if `spy` was always called with the provided arguments and no others.
+
+#### `sinon.assert.calledWithMatch(spyOrSpyCall, arg1, arg2, ...)`
+
+Passes if `spy` was called with matching arguments.
+
+This behaves the same way as `sinon.assert.calledWith(spy, sinon.match(arg1), sinon.match(arg2), ...)`.
+
+It's possible to assert on a dedicated spy call: `sinon.assert.calledWithMatch(spy.secondCall, arg1, arg2, ...);`.
+
+#### `sinon.assert.calledOnceWithMatch(spyOrSpyCall, arg1, arg2, ...)`
+
+Passes if `spy` was called once and only once with matching arguments.
+
+It's possible to assert on a dedicated spy call: `sinon.assert.calledOnceWithMatch(spy.secondCall, arg1, arg2, ...);`.
+
+#### `sinon.assert.alwaysCalledWithMatch(spy, arg1, arg2, ...)`
+
+Passes if `spy` was always called with matching arguments.
+
+This behaves the same way as `sinon.assert.alwaysCalledWith(spy, sinon.match(arg1), sinon.match(arg2), ...)`.
+
+#### `sinon.assert.calledWithNew(spyOrSpyCall)`
+
+Passes if `spy` was called with the `new` operator.
+
+It's possible to assert on a dedicated spy call: `sinon.assert.calledWithNew(spy.secondCall, arg1, arg2, ...);`.
+
+#### `sinon.assert.neverCalledWithMatch(spy, arg1, arg2, ...)`
+
+Passes if `spy` was never called with matching arguments.
+
+This behaves the same way as `sinon.assert.neverCalledWith(spy, sinon.match(arg1), sinon.match(arg2), ...)`.
+
+#### `sinon.assert.threw(spyOrSpyCall, exception);`
+
+Passes if `spy` threw the given exception.
+
+The exception can be a `String` denoting its type, or an actual object.
+
+If only one argument is provided, the assertion passes if `spy` ever threw any exception.
+
+It's possible to assert on a dedicated spy call: `sinon.assert.threw(spy.thirdCall, exception);`.
+
+#### `sinon.assert.alwaysThrew(spy, exception);`
+
+Like above, only required for all calls to the spy.
+
+#### `sinon.assert.match(actual, expectation);`
+
+Uses [`sinon.match`](../matchers) to test if the arguments can be considered a match.
+
+```javascript
+var sinon = require("sinon");
+
+describe("example", function () {
+  it("should match on `x` property, and ignore `y` property", function () {
+    var expected = { x: 1 },
+      actual = { x: 1, y: 2 };
+
+    sinon.assert.match(actual, expected);
+  });
+});
+```
+
+#### `sinon.assert.expose(object, options);`
+
+Exposes assertions into another object, to better integrate with the test framework. For instance, JsTestDriver uses global assertions, and to make Sinon.JS assertions appear alongside them, you can do.
+
+```javascript
+sinon.assert.expose(this);
+```
+
+This will give you `assertCalled(spy)`,`assertCallOrder(spy1, spy2, ...)` and so on.
+
+The method accepts an optional options object with two options.
+
+<dl>
+    <dt>prefix</dt>
+    <dd>is a prefix to give assertions. By default it is "assert", so <code>sinon.assert.called</code> becomes <code>target.assertCalled</code>. By passing a blank string, the exposed method will be <code>target.called</code>.</dd>
+
+    <dt>includeFail</dt>
+    <dd><code>true</code> by default, copies over the <code>fail</code> and <code>failException</code> properties</dd>
+
+</dl>

docs/_releases/v16/examples/.eslintrc.yml

@@ -0,0 +1,17 @@
+env:
+  es6: true
+
+parserOptions:
+  ecmaVersion: 2017
+
+extends:
+  - ../../../../test/.eslintrc.yml
+
+rules:
+  no-underscore-dangle: off
+  no-console: off
+  no-empty-function: off
+  mocha/no-setup-in-describe: off
+  no-var: error
+  prefer-const: error
+  strict: off # cannot use strict mode in RunKit due to it using `with` tricks

docs/_releases/v16/examples/.gitignore

@@ -0,0 +1 @@
+package-lock.json

docs/_releases/v16/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
+});

docs/_releases/v16/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
+});

docs/_releases/v16/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
+});

docs/_releases/v16/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");
+});

docs/_releases/v16/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");
+});

docs/_releases/v16/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" });
+});