Add release documentation for v12.0.0

Author: fatso83

docs/_releases/latest.md

@@ -2,7 +2,7 @@
 layout: page
 title: API documentation - Sinon.JS
 skip_ad: true
-release_id: v11.1.2
+release_id: v12.0.0
 ---
 
 # {{page.title}} - `{{page.release_id}}`

docs/_releases/latest/fake-xhr-and-server.md

@@ -284,7 +284,7 @@ Causes all queued asynchronous requests to receive a response.
 
 If none of the responses added through `respondWith()` match, the default response is `[404, {}, ""]`.
 
-Synchronous requests are responded to immediately so make sure to call `respondWith()` to configure the server response before calling `respond()`. If not, you will recieve the default `404 NOT FOUND` response.
+Synchronous requests are responded to immediately so make sure to call `respondWith()` to configure the server response before calling `respond()`. If not, you will receive the default `404 NOT FOUND` response.
 
 If called with arguments, `respondWith()` will be called with those arguments before responding to requests.
 

docs/_releases/latest/spy-call.md

@@ -6,7 +6,7 @@ breadcrumb: spy-call
 
 ## Spy call
 
-A spy call is an object representation of an invididual call to a _spied_ function, which could be a [fake](../fakes), [spy](../spies), [stub](../stubs) or [mock method](../mocks).
+A spy call is an object representation of an individual call to a _spied_ function, which could be a [fake](../fakes), [spy](../spies), [stub](../stubs) or [mock method](../mocks).
 
 ### `var spyCall = spy.getCall(n)`
 

docs/_releases/latest/utils.md

@@ -10,7 +10,7 @@ Sinon.JS has a few utilities used internally in `lib/sinon.js`. Unless the metho
 
 #### `sinon.createStubInstance(constructor);`
 
-Creates a new object with the given function as the protoype and stubs all implemented functions.
+Creates a new object with the given function as the prototype and stubs all implemented functions.
 
 ```javascript
 class Container {

docs/_releases/v12.0.0.md

@@ -0,0 +1,39 @@
+---
+layout: page
+title: API documentation - Sinon.JS
+skip_ad: true
+release_id: v12.0.0
+---
+
+# {{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/v12.0.0/assertions.md

@@ -0,0 +1,190 @@
+---
+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.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/v12.0.0/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/v12.0.0/examples/.gitignore

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

docs/_releases/v12.0.0/examples/fakes-1-using-fakes-instead-of-spies.test.js

@@ -0,0 +1,17 @@
+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
+    });
+});

docs/_releases/v12.0.0/examples/fakes-10-firstArg.test.js

@@ -0,0 +1,17 @@
+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 firstArg", function () {
+        const f = sinon.fake();
+        const date1 = new Date();
+        const date2 = new Date();
+
+        f(date1, 1, 2);
+        f(date2, 1, 2);
+
+        assert.isTrue(f.firstArg === date2);
+    });
+});

docs/_releases/v12.0.0/examples/fakes-11-lastArg.test.js

@@ -0,0 +1,21 @@
+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 lastArg", function () {
+        const f = sinon.fake();
+        const date1 = new Date();
+        const date2 = new Date();
+
+        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);
+    });
+});

docs/_releases/v12.0.0/examples/fakes-12-adding-fake-to-system-under-test.test.js

@@ -0,0 +1,20 @@
+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 added to the system under test", function () {
+        const fake = sinon.fake.returns("42");
+
+        sinon.replace(console, "log", fake);
+
+        assert.equals(console.log("apple pie"), 42);
+
+        // 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);
+    });
+});

docs/_releases/v12.0.0/examples/fakes-2-using-fakes-instead-of-stubs.test.js

@@ -0,0 +1,21 @@
+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
+    });
+});