Add release documentation for v8.0.3

Author: mroderick

docs/_releases/latest.md

@@ -2,7 +2,7 @@
 layout: page
 title: API documentation - Sinon.JS
 skip_ad: true
-release_id: v8.0.2
+release_id: v8.0.3
 ---
 
 # {{page.title}} - `{{page.release_id}}`

docs/_releases/latest/fake-timers.md

@@ -63,7 +63,11 @@ As above, but allows further configuration options, some of which are:
 - `config.toFake` - *String[ ]* - an array with explicit function names to fake. By default lolex will automatically fake all methods *except* `process.nextTick`. You could, however, still fake `nextTick` by providing it explicitly
 - `config.shouldAdvanceTime` - *Boolean* - tells lolex to increment mocked time automatically based on the real system time shift (default: false)
 
-Please visit the `lolex.install` [documentation](https://github.com/sinonjs/lolex#var-clock--lolexinstallconfig) for the full feature set.
+Please refer to the `lolex.install` [documentation](https://github.com/sinonjs/lolex#var-clock--lolexinstallconfig) for the full set of features available and more elaborate explanations.
+
+*Since `sinon@3.0.0`*
+
+`var clock = sinon.useFakeTimers([now, ]prop1, prop2, ...)` is no longer supported. To define which methods to fake, please use `config.toFake`.
 
 **Important note:** when faking `nextTick`, normal calls to `process.nextTick()` would not execute automatically as they would during normal event-loop phases. You would have to call either `clock.next()`, `clock.tick()`, `clock.runAll()` or `clock.runToLast()` (see example below). Please refer to the [lolex](https://github.com/sinonjs/lolex) documentation for more information.
 
@@ -108,31 +112,62 @@ setTimeout(function () {
 }, 35);
 ```
 
-Please refer to the `lolex.install` [documentation](https://github.com/sinonjs/lolex#var-clock--lolexinstallconfig) for the full set of features available and more elaborate explanations.
+Using fake timers with `async` / `await`:
 
-*Since `sinon@3.0.0`*
+```
+async function asyncFn() {
 
-`var clock = sinon.useFakeTimers([now, ]prop1, prop2, ...)` is no longer supported. To define which methods to fake, please use `config.toFake`.
+ await wait(100);
+
+ console.log('resolved 1', Date.now());
+
+ await wait(10);
+
+ console.log('resolved 2', Date.now());
+}
+
+async function test() {
+
+ const clock = sinon.useFakeTimers();
+
+ setTimeout(() => console.log('timeout', Date.now()), 200);
+
+ asyncFn(); // NOTE: no `await` here - it would hang, as the clock is stopped
+
+ await clock.tickAsync(200);
+}
+
+// test() prints:
+// - resolved 1 100
+// - resolved 2 110
+// - timeout 200
+```
 
+Note that in the above example, the synchronous `clock.tick(200)` would only print `timeout 200` and `resolved 1 200`.
 
-#### `clock.tick(time);`
+
+#### `clock.tick(time);` / `await clock.tickAsync(time)`
 
 Tick the clock ahead `time` milliseconds.
 
 Causes all timers scheduled within the affected time range to be called. `time` may be the number of milliseconds to advance the clock by or a human-readable string. Valid string formats are "08" for eight seconds, "01:00" for one minute and "02:34:10" for two hours, 34 minutes and ten seconds.
 
-time may be negative, which causes the clock to change but won't fire any callbacks.
+The `tickAsync()` will also break the event loop, allowing any scheduled promise callbacks to execute _before_ running the timers.
 
-#### `clock.next();`
+#### `clock.next();` / `await clock.nextAsync()`
 
 Advances the clock to the the moment of the first scheduled timer, firing it.
 
-#### `clock.runAll();`
+The `nextAsync()` will also break the event loop, allowing any scheduled promise callbacks to execute _before_ running the timers.
+
+#### `clock.runAll();` / `await clock.runAllAsync()`
 
 This runs all pending timers until there are none remaining. If new timers are added while it is executing they will be run as well.
 
 This makes it easier to run asynchronous tests to completion without worrying about the number of timers they use, or the delays in those timers.
 
+The `runAllAsync()` will also break the event loop, allowing any scheduled promise callbacks to execute _before_ running the timers.
+
 #### `clock.restore();`
 
 Restore the faked methods.

docs/_releases/v8.0.3.md

@@ -0,0 +1,52 @@
+---
+layout: page
+title: API documentation - Sinon.JS
+skip_ad: true
+release_id: v8.0.3
+---
+
+# {{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)
+* [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
+
+### ES5.1
+
+Sinon `{{page.release_id}}` is written as [ES5.1][ES5] and requires no transpiler or polyfills to run in the runtimes listed below.
+
+### Supported runtimes
+
+`{{page.release_id}}` has been verified in these runtimes:
+
+* Firefox 45
+* Chrome 48
+* Internet Explorer 11
+* Edge 14
+* Safari 9
+* [Node.js LTS versions](https://github.com/nodejs/Release)
+
+There should not be any issues with using Sinon `{{page.release_id}}` in newer versions of the same runtimes.
+
+If you need to support very old runtimes that have incomplete support for [ES5.1][ES5] you might get away with using loading [`es5-shim`][es5-shim] in your test environment.
+
+{% include docs/contribute.md %}
+
+[ES5]: http://www.ecma-international.org/ecma-262/5.1/
+[es5-shim]: https://github.com/es-shims/es5-shim

docs/_releases/v8.0.3/assertions.md

@@ -0,0 +1,202 @@
+---
+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.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/v8.0.3/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/v8.0.3/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);
+ })
+});