| OLD | NEW |
| (Empty) | |
| 1 # Sinon.JS Assertions for Chai |
| 2 |
| 3 **Sinon–Chai** provides a set of custom assertions for using the [Sinon.JS][] sp
y, stub, and mocking framework with the |
| 4 [Chai][] assertion library. You get all the benefits of Chai with all the powerf
ul tools of Sinon.JS. |
| 5 |
| 6 Instead of using Sinon.JS's assertions: |
| 7 |
| 8 ```javascript |
| 9 sinon.assertCalledWith(mySpy, "foo"); |
| 10 ``` |
| 11 |
| 12 or awkwardly trying to use Chai's `should` or `expect` interfaces on spy propert
ies: |
| 13 |
| 14 ```javascript |
| 15 mySpy.calledWith("foo").should.be.ok; |
| 16 expect(mySpy.calledWith("foo")).to.be.ok; |
| 17 ``` |
| 18 |
| 19 you can say |
| 20 |
| 21 ```javascript |
| 22 mySpy.should.have.been.calledWith("foo"); |
| 23 expect(mySpy).to.have.been.calledWith("foo"); |
| 24 ``` |
| 25 |
| 26 ## Assertions |
| 27 |
| 28 All of your favorite Sinon.JS assertions made their way into Sinon–Chai. We show
the `should` syntax here; the `expect` |
| 29 equivalent is also available. |
| 30 |
| 31 <table> |
| 32 <thead> |
| 33 <tr> |
| 34 <th>Sinon.JS property/method</th> |
| 35 <th>Sinon–Chai assertion</th> |
| 36 </tr> |
| 37 </thead> |
| 38 <tbody> |
| 39 <tr> |
| 40 <td>called</td> |
| 41 <td>spy.should.have.been.called</td> |
| 42 </tr> |
| 43 <tr> |
| 44 <td>callCount</td> |
| 45 <td>spy.should.have.callCount(n)</td> |
| 46 </tr> |
| 47 <tr> |
| 48 <td>calledOnce</td> |
| 49 <td>spy.should.have.been.calledOnce</td> |
| 50 </tr> |
| 51 <tr> |
| 52 <td>calledTwice</td> |
| 53 <td>spy.should.have.been.calledTwice</td> |
| 54 </tr> |
| 55 <tr> |
| 56 <td>calledThrice</td> |
| 57 <td>spy.should.have.been.calledThrice</td> |
| 58 </tr> |
| 59 <tr> |
| 60 <td>calledBefore</td> |
| 61 <td>spy1.should.have.been.calledBefore(spy2)</td> |
| 62 </tr> |
| 63 <tr> |
| 64 <td>calledAfter</td> |
| 65 <td>spy1.should.have.been.calledAfter(spy2)</td> |
| 66 </tr> |
| 67 <tr> |
| 68 <td>calledImmediatelyBefore</td> |
| 69 <td>spy.should.have.been.calledImmediatelyBefore(spy2)</td> |
| 70 </tr> |
| 71 <tr> |
| 72 <td>calledImmediatelyAfter</td> |
| 73 <td>spy.should.have.been.calledImmediatelyAfter(spy2)</td> |
| 74 </tr> |
| 75 <tr> |
| 76 <td>calledWithNew</td> |
| 77 <td>spy.should.have.been.calledWithNew</td> |
| 78 </tr> |
| 79 <tr> |
| 80 <td>alwaysCalledWithNew</td> |
| 81 <td>spy.should.always.have.been.calledWithNew</td> |
| 82 </tr> |
| 83 <tr> |
| 84 <td>calledOn</td> |
| 85 <td>spy.should.have.been.calledOn(context)</td> |
| 86 </tr> |
| 87 <tr> |
| 88 <td>alwaysCalledOn</td> |
| 89 <td>spy.should.always.have.been.calledOn(context)</td> |
| 90 </tr> |
| 91 <tr> |
| 92 <td>calledWith</td> |
| 93 <td>spy.should.have.been.calledWith(...args)</td> |
| 94 </tr> |
| 95 <tr> |
| 96 <td>alwaysCalledWith</td> |
| 97 <td>spy.should.always.have.been.calledWith(...args)</td> |
| 98 </tr> |
| 99 <tr> |
| 100 <td>calledWithExactly</td> |
| 101 <td>spy.should.have.been.calledWithExactly(...args)</td> |
| 102 </tr> |
| 103 <tr> |
| 104 <td>alwaysCalledWithExactly</td> |
| 105 <td>spy.should.always.have.been.calledWithExactly(...args)</td> |
| 106 </tr> |
| 107 <tr> |
| 108 <td>calledWithMatch</td> |
| 109 <td>spy.should.have.been.calledWithMatch(...args)</td> |
| 110 </tr> |
| 111 <tr> |
| 112 <td>alwaysCalledWithMatch</td> |
| 113 <td>spy.should.always.have.been.calledWithMatch(...args)</td> |
| 114 </tr> |
| 115 <tr> |
| 116 <td>returned</td> |
| 117 <td>spy.should.have.returned(returnVal)</td> |
| 118 </tr> |
| 119 <tr> |
| 120 <td>alwaysReturned</td> |
| 121 <td>spy.should.have.always.returned(returnVal)</td> |
| 122 </tr> |
| 123 <tr> |
| 124 <td>threw</td> |
| 125 <td>spy.should.have.thrown(errorObjOrErrorTypeStringOrNothing)</td> |
| 126 </tr> |
| 127 <tr> |
| 128 <td>alwaysThrew</td> |
| 129 <td>spy.should.have.always.thrown(errorObjOrErrorTypeStringOrNothing
)</td> |
| 130 </tr> |
| 131 </tbody> |
| 132 </table> |
| 133 |
| 134 For more information on the behavior of each assertion, see |
| 135 [the documentation for the corresponding spy methods][spymethods]. These of cour
se work on not only spies, but |
| 136 individual spy calls, stubs, and mocks as well. |
| 137 |
| 138 Note that you can negate any assertion with Chai's `.not`. E. g. for `notCalled`
use `spy.should.have.not.been.called`. |
| 139 |
| 140 For `assert` interface there is no need for this library. You can install [Sinon
.JS assertions][sinonassertions] right into Chai's `assert` object with `expose`
: |
| 141 |
| 142 ```javascript |
| 143 var chai = require("chai"); |
| 144 var sinon = require("sinon"); |
| 145 |
| 146 sinon.assert.expose(chai.assert, { prefix: "" }); |
| 147 ``` |
| 148 |
| 149 ## Examples |
| 150 |
| 151 Using Chai's `should`: |
| 152 |
| 153 ```javascript |
| 154 "use strict"; |
| 155 var chai = require("chai"); |
| 156 var sinon = require("sinon"); |
| 157 var sinonChai = require("sinon-chai"); |
| 158 chai.should(); |
| 159 chai.use(sinonChai); |
| 160 |
| 161 function hello(name, cb) { |
| 162 cb("hello " + name); |
| 163 } |
| 164 |
| 165 describe("hello", function () { |
| 166 it("should call callback with correct greeting", function () { |
| 167 var cb = sinon.spy(); |
| 168 |
| 169 hello("foo", cb); |
| 170 |
| 171 cb.should.have.been.calledWith("hello foo"); |
| 172 }); |
| 173 }); |
| 174 ``` |
| 175 |
| 176 Using Chai's `expect`: |
| 177 |
| 178 ```javascript |
| 179 "use strict"; |
| 180 var chai = require("chai"); |
| 181 var sinon = require("sinon"); |
| 182 var sinonChai = require("sinon-chai"); |
| 183 var expect = chai.expect; |
| 184 chai.use(sinonChai); |
| 185 |
| 186 function hello(name, cb) { |
| 187 cb("hello " + name); |
| 188 } |
| 189 |
| 190 describe("hello", function () { |
| 191 it("should call callback with correct greeting", function () { |
| 192 var cb = sinon.spy(); |
| 193 |
| 194 hello("foo", cb); |
| 195 |
| 196 expect(cb).to.have.been.calledWith("hello foo"); |
| 197 }); |
| 198 }); |
| 199 ``` |
| 200 |
| 201 ## Installation and Usage |
| 202 |
| 203 ### Node |
| 204 |
| 205 Do an `npm install sinon-chai` to get up and running. Then: |
| 206 |
| 207 ```javascript |
| 208 var chai = require("chai"); |
| 209 var sinonChai = require("sinon-chai"); |
| 210 |
| 211 chai.use(sinonChai); |
| 212 ``` |
| 213 |
| 214 You can of course put this code in a common test fixture file; for an example us
ing [Mocha][], see |
| 215 [the Sinon–Chai tests themselves][fixturedemo]. |
| 216 |
| 217 ### AMD |
| 218 |
| 219 Sinon–Chai supports being used as an [AMD][] module, registering itself anonymou
sly (just like Chai). So, assuming you |
| 220 have configured your loader to map the Chai and Sinon–Chai files to the respecti
ve module IDs `"chai"` and |
| 221 `"sinon-chai"`, you can use them as follows: |
| 222 |
| 223 ```javascript |
| 224 define(function (require, exports, module) { |
| 225 var chai = require("chai"); |
| 226 var sinonChai = require("sinon-chai"); |
| 227 |
| 228 chai.use(sinonChai); |
| 229 }); |
| 230 ``` |
| 231 |
| 232 ### `<script>` tag |
| 233 |
| 234 If you include Sinon–Chai directly with a `<script>` tag, after the one for Chai
itself, then it will automatically plug |
| 235 in to Chai and be ready for use. Note that you'll want to get the latest browser
build of Sinon.JS as well: |
| 236 |
| 237 ```html |
| 238 <script src="chai.js"></script> |
| 239 <script src="sinon-chai.js"></script> |
| 240 <script src="sinon.js"></script> |
| 241 ``` |
| 242 |
| 243 ### Ruby on Rails |
| 244 |
| 245 Thanks to [Cymen Vig][], there's now [a Ruby gem][] of Sinon–Chai that integrate
s it with the Rails asset pipeline! |
| 246 |
| 247 |
| 248 [Sinon.JS]: http://sinonjs.org/ |
| 249 [Chai]: http://chaijs.com/ |
| 250 [spymethods]: http://sinonjs.org/docs/#spies-api |
| 251 [sinonassertions]: http://sinonjs.org/docs/#assertions |
| 252 [Mocha]: https://mochajs.org/ |
| 253 [fixturedemo]: https://github.com/domenic/sinon-chai/tree/master/test/ |
| 254 [AMD]: https://github.com/amdjs/amdjs-api/wiki/AMD |
| 255 [Cymen Vig]: https://github.com/cymen |
| 256 [a Ruby gem]: https://github.com/cymen/sinon-chai-rails |
| OLD | NEW |