Skip to content

Commit 69bf8f2

Browse files
mroderickmroderick
committed
Add release documentation for v2.3.1
1 parent eee4564 commit 69bf8f2

File tree

12 files changed

+2462
-0
lines changed

12 files changed

+2462
-0
lines changed

‎docs/_releases/v2.3.1.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
layout: page
3+
title: API documentation - Sinon.JS
4+
release_id: v2.3.1
5+
---
6+
7+
# {{page.title}} - `{{page.release_id}}`
8+
9+
This page contains the entire Sinon.JS API documentation along with brief introductions to the concepts Sinon implements.
10+
11+
* [Spies](./spies)
12+
* [Stubs](./stubs)
13+
* [Mocks](./mocks)
14+
* [Fake timers](./fake-timers)
15+
* [Fake <code>XHR</code> and server](./fake-xhr-and-server)
16+
* [JSON-P](./json-p)
17+
* [Assertions](./assertions)
18+
* [Matchers](./matchers)
19+
* [Sandboxes](./sandbox)
20+
* [Utils](./utils)
21+
22+
### Migrating from v1.x to v2.0
23+
24+
Please see our [migration guide](./migrating-to-2.0) for details on migrating to Sinon.JS v2.0
25+
26+
### Compatibility
27+
28+
### ES5.1
29+
30+
Sinon `{{page.release_id}}` is written as [ES5.1][ES5] and requires no transpiler or polyfills to run in the runtimes listed below.
31+
32+
### Supported runtimes
33+
34+
`{{page.release_id}}` has been verified in these runtimes:
35+
36+
* Firefox 45
37+
* Chrome 48
38+
* Internet Explorer 11
39+
* Edge 14
40+
* Safari 9
41+
* Node 4
42+
43+
There should not be any issues with using Sinon `{{page.release_id}}` in newer versions of the same runtimes.
44+
45+
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. If that fails, we recommend [getting a legacy releases of Sinon][legacy-site].
46+
47+
{% include docs/contribute.md %}
48+
49+
[ES5]: http://www.ecma-international.org/ecma-262/5.1/
50+
[es5-shim]: https://github.com/es-shims/es5-shim
51+
[legacy-site]: http://legacy.sinonjs.org

‎docs/_releases/v2.3.1/assertions.md

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
---
2+
layout: page
3+
title: Assertions - Sinon.JS
4+
breadcrumb: assertions
5+
---
6+
7+
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.
8+
9+
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`.
10+
11+
The assertions can be used with either spies or stubs.
12+
13+
```javascript
14+
"test should call subscribers with message as first argument" : function () {
15+
var message = "an example message";
16+
var spy = sinon.spy();
17+
18+
PubSub.subscribe(message, spy);
19+
PubSub.publishSync(message, "some payload");
20+
21+
sinon.assert.calledOnce(spy);
22+
sinon.assert.calledWith(spy, message);
23+
}
24+
```
25+
26+
## Assertions API
27+
28+
#### `sinon.assert.fail(message)`
29+
30+
Every assertion fails by calling this method.
31+
32+
By default it throws an error of type `sinon.assert.failException`.
33+
34+
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.
35+
36+
37+
#### `sinon.assert.failException;`
38+
39+
Defaults to `AssertError`.
40+
41+
42+
#### `sinon.assert.pass(assertion);`
43+
44+
Called every time `assertion` passes.
45+
46+
Default implementation does nothing.
47+
48+
49+
#### `sinon.assert.notCalled(spy);`
50+
51+
Passes if `spy` was never called
52+
53+
#### `sinon.assert.called(spy);`
54+
55+
Passes if `spy` was called at least once.
56+
57+
58+
#### `sinon.assert.calledOnce(spy);`
59+
60+
Passes if `spy` was called once and only once.
61+
62+
63+
#### `sinon.assert.calledTwice(spy);`
64+
65+
Passes if `spy` was called exactly twice.
66+
67+
68+
#### `sinon.assert.calledThrice(spy)`
69+
70+
Passes if `spy` was called exactly three times.
71+
72+
73+
#### `sinon.assert.callCount(spy, num)`
74+
Passes if `spy` was called exactly `num` times.
75+
76+
77+
#### `sinon.assert.callOrder(spy1, spy2, ...)`
78+
Passes if provided spies were called in the specified order.
79+
80+
81+
#### `sinon.assert.calledOn(spy, obj)`
82+
83+
Passes if `spy` was ever called with `obj` as its `this` value.
84+
85+
86+
#### `sinon.assert.alwaysCalledOn(spy, obj)`
87+
88+
Passes if `spy` was always called with `obj` as its `this` value.
89+
90+
91+
#### `sinon.assert.calledWith(spy, arg1, arg2, ...);`
92+
93+
Passes if `spy` was called with the provided arguments.
94+
95+
96+
#### `sinon.assert.alwaysCalledWith(spy, arg1, arg2, ...);`
97+
98+
Passes if `spy` was always called with the provided arguments.
99+
100+
101+
#### `sinon.assert.neverCalledWith(spy, arg1, arg2, ...);`
102+
103+
Passes if `spy` was never called with the provided arguments.
104+
105+
106+
#### `sinon.assert.calledWithExactly(spy, arg1, arg2, ...);`
107+
108+
Passes if `spy` was called with the provided arguments and no others.
109+
110+
111+
#### `sinon.assert.alwaysCalledWithExactly(spy, arg1, arg2, ...);`
112+
113+
Passes if `spy` was always called with the provided arguments and no others.
114+
115+
116+
#### `sinon.assert.calledWithMatch(spy, arg1, arg2, ...)`
117+
118+
Passes if `spy` was called with matching arguments.
119+
120+
This behaves the same way as `sinon.assert.calledWith(spy, sinon.match(arg1), sinon.match(arg2), ...)`.
121+
122+
123+
#### `sinon.assert.alwaysCalledWithMatch(spy, arg1, arg2, ...)`
124+
125+
Passes if `spy` was always called with matching arguments.
126+
127+
This behaves the same way as `sinon.assert.alwaysCalledWith(spy, sinon.match(arg1), sinon.match(arg2), ...)`.
128+
129+
130+
#### `sinon.assert.neverCalledWithMatch(spy, arg1, arg2, ...)`
131+
132+
Passes if `spy` was never called with matching arguments.
133+
134+
This behaves the same way as `sinon.assert.neverCalledWith(spy, sinon.match(arg1), sinon.match(arg2), ...)`.
135+
136+
137+
#### `sinon.assert.threw(spy, exception);`
138+
139+
Passes if `spy` threw the given exception.
140+
141+
The exception can be a `String` denoting its type, or an actual object.
142+
143+
If only one argument is provided, the assertion passes if `spy` ever threw any exception.
144+
145+
146+
#### `sinon.assert.alwaysThrew(spy, exception);`
147+
148+
Like above, only required for all calls to the spy.
149+
150+
#### `sinon.assert.match(actual, expectation);`
151+
152+
Uses [`sinon.match`](../matchers) to test if the arguments can be considered a match.
153+
154+
```javascript
155+
var sinon = require('sinon');
156+
157+
describe('example', function(){
158+
it('should match on `x` property, and ignore `y` property', function() {
159+
var expected = {x: 1},
160+
actual = {x: 1, y: 2};
161+
162+
sinon.assert.match(actual, expected);
163+
});
164+
});
165+
```
166+
167+
#### `sinon.assert.expose(object, options);`
168+
169+
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.
170+
171+
```javascript
172+
sinon.assert.expose(this);
173+
```
174+
175+
This will give you `assertCalled(spy)`,`assertCallOrder(spy1, spy2, ...)` and so on.
176+
177+
The method accepts an optional options object with two options.
178+
179+
<dl>
180+
<dt>prefix</dt>
181+
<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>
182+
183+
<dt>includeFail</dt>
184+
<dd><code>true</code> by default, copies over the <code>fail</code> and <code>failException</code> properties</dd>
185+
</dl>

‎docs/_releases/v2.3.1/fake-timers.md

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
layout: page
3+
title: Fake timers - Sinon.JS
4+
breadcrumb: fake timers
5+
---
6+
7+
Fake timers are synchronous implementations of `setTimeout` and friends that
8+
Sinon.JS can overwrite the global functions with to allow you to more easily
9+
test code using them.
10+
11+
Fake timers provide a `clock` object to pass time, which can also be used to control `Date` objects created through either `new Date();`
12+
or `Date.now();` (if supported by the browser).
13+
14+
For standalone usage of fake timers it is recommended to use [lolex](https://github.com/sinonjs/lolex) package instead. It provides the same
15+
set of features (Sinon uses it under the hood) and was previously extracted from Sinon.JS.
16+
17+
```javascript
18+
{
19+
setUp: function () {
20+
this.clock = sinon.useFakeTimers();
21+
},
22+
23+
tearDown: function () {
24+
this.clock.restore();
25+
},
26+
27+
"test should animate element over 500ms" : function(){
28+
var el = jQuery("<div></div>");
29+
el.appendTo(document.body);
30+
31+
el.animate({ height: "200px", width: "200px" });
32+
this.clock.tick(510);
33+
34+
assertEquals("200px", el.css("height"));
35+
assertEquals("200px", el.css("width"));
36+
}
37+
}
38+
```
39+
40+
41+
## Fake timers API
42+
43+
44+
#### `var clock = sinon.useFakeTimers();`
45+
46+
Causes Sinon to replace the global `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval`, `setImmediate`, `clearImmediate` and `Date` with a custom implementation which is bound to the returned `clock` object.
47+
48+
Starts the clock at the UNIX epoch (timestamp of 0).
49+
50+
51+
#### `var clock = sinon.useFakeTimers(now);`
52+
53+
As above, but rather than starting the clock with a timestamp of 0, start at the provided timestamp.
54+
55+
*Since `[email protected]`*
56+
57+
You can also pass in a Date object, and it's `getTime()` will be used for the starting timestamp.
58+
59+
#### `var clock = sinon.useFakeTimers([now, ]prop1, prop2, ...);`
60+
61+
Sets the clock start timestamp and names functions to fake.
62+
63+
Possible functions are `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval`, `setImmediate`, `clearImmediate` and `Date`. Can also be called without the timestamp.
64+
65+
66+
#### `clock.tick(ms);`
67+
68+
Tick the clock ahead `ms` milliseconds.
69+
70+
Causes all timers scheduled within the affected time range to be called.
71+
72+
73+
#### `clock.restore();`
74+
75+
Restore the faked methods.
76+
77+
Call in e.g. `tearDown`.

0 commit comments

Comments
 (0)