-
-
Notifications
You must be signed in to change notification settings - Fork 772
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add release documentation for v12.0.0
- Loading branch information
Showing
59 changed files
with
3,644 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
package-lock.json |
17 changes: 17 additions & 0 deletions
17
docs/_releases/v12.0.0/examples/fakes-1-using-fakes-instead-of-spies.test.js
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
}); | ||
}); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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); | ||
}); | ||
}); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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); | ||
}); | ||
}); |
20 changes: 20 additions & 0 deletions
20
docs/_releases/v12.0.0/examples/fakes-12-adding-fake-to-system-under-test.test.js
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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); | ||
}); | ||
}); |
21 changes: 21 additions & 0 deletions
21
docs/_releases/v12.0.0/examples/fakes-2-using-fakes-instead-of-stubs.test.js
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
}); | ||
}); |
Oops, something went wrong.