{{ page.title }}
-{{ page.title }}
+
- {{ content }}
-
+
+ {{ content }}
+
+ {% include banner.html %}
+
{{ content }}
XHR 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
diff --git a/docs/_releases/latest/assertions.md b/docs/_releases/latest/assertions.md
new file mode 100644
index 000000000..1d0302be1
--- /dev/null
+++ b/docs/_releases/latest/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 simply 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.
+
+sinon.assert.called becomes target.assertCalled. By passing a blank string, the exposed method will be target.called.true by default, copies over the fail and failException propertiesvar spy = sinon.spy();this value,
+ exceptions and return values for all calls.
+ var spy = sinon.spy(myFunc);var spy = sinon.spy(object, "method");object.method and
+ replaces the original method with the spy. An exception is thrown if the property
+ is not already a function. The spy acts exactly like the original method in
+ all cases. The original method can be restored by calling
+ object.method.restore(). The returned spy is the function
+ object which replaced the original method. spy === object.method.
+ %n%c%C%tthis values the spy was called on%nprintf%*printf%Dthis value.
+
+Useful for stubbing jQuery-style fluent APIs.
+
+#### `stub.resolves(value);`
+
+Causes the stub to return a Promise which resolves to the provided value.
+
+When constructing the Promise, sinon uses the `Promise.resolve` method. You are
+responsible for providing a polyfill in environments which do not provide `Promise`.
+The Promise library can be overwritten using the `usingPromise` method.
+
+*Since `sinon@2.0.0`*
+
+#### `stub.resolvesArg(index);`
+
+Causes the stub to return a Promise which resolves to the argument at the
+provided index.
+
+`stub.resolvesArg(0);` causes the stub to return a Promise which resolves to the
+first argument.
+
+If the argument at the provided index is not available, a `TypeError` will be
+thrown.
+
+*Since `sinon@6.1.1`*
+
+#### `stub.throws();`
+
+Causes the stub to throw an exception (`Error`).
+
+
+#### `stub.throws("name"[, "optional message"]);`
+
+Causes the stub to throw an exception with the `name` property set to the provided string. The message parameter is optional and will set the `message` property of the exception.
+
+
+#### `stub.throws(obj);`
+
+Causes the stub to throw the provided exception object.
+
+
+#### `stub.throws(function() { return new Error(); });`
+
+Causes the stub to throw the exception returned by the function.
+
+
+### `stub.throwsArg(index);`
+
+Causes the stub to throw the argument at the provided index.
+
+`stub.throwsArg(0);` causes the stub to throw the first argument as the
+exception.
+
+If the argument at the provided index is not available, a `TypeError` will be
+thrown.
+
+*Since `sinon@2.3.0`*
+
+#### `stub.rejects();`
+
+Causes the stub to return a Promise which rejects with an exception (`Error`).
+
+When constructing the Promise, sinon uses the `Promise.reject` method. You are
+responsible for providing a polyfill in environments which do not provide `Promise`.
+The Promise library can be overwritten using the `usingPromise` method.
+
+*Since `sinon@2.0.0`*
+
+
+#### `stub.rejects("TypeError");`
+
+Causes the stub to return a Promise which rejects with an exception of the provided type.
+
+*Since `sinon@2.0.0`*
+
+
+#### `stub.rejects(value);`
+
+Causes the stub to return a Promise which rejects with the provided exception object.
+
+*Since `sinon@2.0.0`*
+
+
+#### `stub.callsArg(index);`
+
+Causes the stub to call the argument at the provided index as a callback function.
+
+`stub.callsArg(0);` causes the stub to call the first argument as a callback.
+
+If the argument at the provided index is not available or is not a function,
+a `TypeError` will be thrown.
+
+
+#### `stub.callThrough();`
+
+Causes the original method wrapped into the stub to be called when none of the conditional stubs are matched.
+
+```javascript
+var stub = sinon.stub();
+
+var obj = {};
+
+obj.sum = function sum(a, b) {
+ return a + b;
+};
+
+stub(obj, 'sum');
+
+obj.sum.withArgs(2, 2).callsFake(function foo() {
+ return 'bar';
+});
+
+obj.sum.callThrough();
+
+obj.sum(2, 2); // 'bar'
+obj.sum(1, 2); // 3
+```
+
+
+#### `stub.callsArgOn(index, context);`
+
+Like `stub.callsArg(index);` but with an additional parameter to pass the `this` context.
+
+
+#### `stub.callsArgWith(index, arg1, arg2, ...);`
+
+Like `callsArg`, but with arguments to pass to the callback.
+
+
+#### `stub.callsArgOnWith(index, context, arg1, arg2, ...);`
+
+Like above but with an additional parameter to pass the `this` context.
+
+#### `stub.usingPromise(promiseLibrary);`
+
+Causes the stub to return promises using a specific Promise library instead of
+the global one when using `stub.rejects` or `stub.resolves`. Returns the stub
+to allow chaining.
+
+```javascript
+var myObj = {
+ saveSomething: sinon.stub().usingPromise(bluebird.Promise).resolves("baz");
+}
+
+myObj.saveSomething()
+ .tap(function(actual) {
+ console.log(actual); // baz
+ });
+```
+
+*Since `sinon@2.0.0`*
+
+#### `stub.yields([arg1, arg2, ...])`
+
+Similar to `callsArg`.
+
+Causes the stub to call the first callback it receives with the provided arguments (if any).
+
+If a method accepts more than one callback, you need to use `yieldsRight` to call the last callback or `callsArg` to have the stub invoke other callbacks than the first or last one.
+
+
+#### `stub.yieldsRight([arg1, arg2, ...])`
+
+Like `yields` but calls the last callback it receives.
+
+
+#### `stub.yieldsOn(context, [arg1, arg2, ...])`
+
+Like `yields` but with an additional parameter to pass the `this` context.
+
+
+#### `stub.yieldsTo(property, [arg1, arg2, ...])`
+
+Causes the spy to invoke a callback passed as a property of an object to the spy.
+
+Like `yields`, `yieldsTo` grabs the first matching argument, finds the callback and calls it with the (optional) arguments.
+
+
+#### `stub.yieldsToOn(property, context, [arg1, arg2, ...])`
+
+Like above but with an additional parameter to pass the `this` context.
+
+```javascript
+"test should fake successful ajax request": function () {
+ sinon.stub(jQuery, "ajax").yieldsTo("success", [1, 2, 3]);
+
+ jQuery.ajax({
+ success: function (data) {
+ assertEquals([1, 2, 3], data);
+ }
+ });
+}
+```
+
+
+#### `stub.yield([arg1, arg2, ...])`
+
+Invoke callbacks passed to the `stub` with the given arguments.
+
+If the stub was never called with a function argument, `yield` throws an error.
+
+Returns an Array with all callbacks return values in the order they were called, if no error is thrown.
+
+Also aliased as `invokeCallback`.
+
+
+#### `stub.yieldTo(callback, [arg1, arg2, ...])`
+
+Invokes callbacks passed as a property of an object to the stub.
+
+Like `yield`, `yieldTo` grabs the first matching argument, finds the callback and calls it with the (optional) arguments.
+
+```javascript
+"calling callbacks": function () {
+ var callback = sinon.stub();
+ callback({
+ "success": function () {
+ console.log("Success!");
+ },
+ "failure": function () {
+ console.log("Oh noes!");
+ }
+ });
+
+ callback.yieldTo("failure"); // Logs "Oh noes!"
+}
+```
+
+
+#### `stub.callArg(argNum)`
+
+Like `yield`, but with an explicit argument number specifying which callback to call.
+
+Useful if a function is called with more than one callback, and simply calling the first callback is not desired.
+
+```javascript
+"calling the last callback": function () {
+ var callback = sinon.stub();
+ callback(function () {
+ console.log("Success!");
+ }, function () {
+ console.log("Oh noes!");
+ });
+
+ callback.callArg(1); // Logs "Oh noes!"
+}
+```
+
+#### `stub.callArgWith(argNum, [arg1, arg2, ...])`
+
+Like `callArg`, but with arguments.
+
+#### Asynchronous calls
+
+Same as their corresponding non-Async counterparts, but with callback being deferred at called after all instructions in the current call stack are processed.
+
+* In Node environment the callback is deferred with `process.nextTick`.
+* In a browser the callback is deferred with `setTimeout(callback, 0)`.
+
+More information:
+
+*
{{ release.release_id }}
diff --git a/scripts/copy-documentation-for-new-release.sh b/scripts/copy-documentation-for-new-release.sh
index de20e2c93..2b33fc79d 100755
--- a/scripts/copy-documentation-for-new-release.sh
+++ b/scripts/copy-documentation-for-new-release.sh
@@ -1,4 +1,6 @@
#!/bin/bash
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+cd "$SCRIPT_DIR/.."
if [[ $# != 1 ]]; then
echo "Usage: $0