1 | # should.js
|
2 |
|
3 | [![Join the chat at https://gitter.im/shouldjs/should.js](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/shouldjs/should.js)
|
4 |
|
5 | [![Build Status](https://travis-ci.org/shouldjs/should.js.svg?branch=master)](https://travis-ci.org/shouldjs/should.js)
|
6 |
|
7 | [![Selenium Test Status](https://saucelabs.com/browser-matrix/shouldjs.svg)](https://saucelabs.com/u/shouldjs)
|
8 |
|
9 | _should_ is an expressive, readable, framework-agnostic assertion library. The main goals of this library are __to be expressive__ and __to be helpful__. It keeps your test code clean, and your error messages helpful.
|
10 |
|
11 | By default (when you `require('should')`) _should_ extends the `Object.prototype` with a single non-enumerable getter that allows you to express how that object should behave. It also returns itself when required with `require`.
|
12 |
|
13 | It is also possible to use should.js without getter (it will not even try to extend Object.prototype), just `require('should/as-function')`. Or if you already use version that auto add getter, you can call `.noConflict` function.
|
14 |
|
15 | **Results of `(something).should` getter and `should(something)` in most situations are the same**
|
16 |
|
17 | ### Upgrading instructions
|
18 |
|
19 | Please check [wiki page](https://github.com/shouldjs/should.js/wiki/Breaking-changes) for upgrading instructions.
|
20 |
|
21 | ### FAQ
|
22 |
|
23 | You can take look in [FAQ](https://github.com/shouldjs/should.js/wiki/FAQ).
|
24 |
|
25 | ## Example
|
26 | ```javascript
|
27 | var should = require('should');
|
28 |
|
29 | var user = {
|
30 | name: 'tj'
|
31 | , pets: ['tobi', 'loki', 'jane', 'bandit']
|
32 | };
|
33 |
|
34 | user.should.have.property('name', 'tj');
|
35 | user.should.have.property('pets').with.lengthOf(4);
|
36 |
|
37 | // If the object was created with Object.create(null)
|
38 | // then it doesn't inherit `Object.prototype`, so it will not have `.should` getter
|
39 | // so you can do:
|
40 | should(user).have.property('name', 'tj');
|
41 |
|
42 | // also you can test in that way for null's
|
43 | should(null).not.be.ok();
|
44 |
|
45 | someAsyncTask(foo, function(err, result){
|
46 | should.not.exist(err);
|
47 | should.exist(result);
|
48 | result.bar.should.equal(foo);
|
49 | });
|
50 | ```
|
51 | ## To begin
|
52 |
|
53 | 1. Install it:
|
54 |
|
55 | ```bash
|
56 | $ npm install should --save-dev
|
57 | ```
|
58 |
|
59 | 2. Require it and use:
|
60 |
|
61 | ```js
|
62 | var should = require('should');
|
63 |
|
64 | (5).should.be.exactly(5).and.be.a.Number();
|
65 | ```
|
66 |
|
67 | ```js
|
68 | var should = require('should/as-function');
|
69 |
|
70 | should(10).be.exactly(5).and.be.a.Number();
|
71 | ```
|
72 |
|
73 | ## In browser
|
74 |
|
75 | Well, even when browsers by complains of authors has 100% es5 support, it does not mean it has no bugs. Please see [wiki](https://github.com/shouldjs/should.js/wiki/Known-Bugs) for known bugs.
|
76 |
|
77 | If you want to use _should_ in browser, use the `should.js` file in the root of this repository, or build it yourself. To build a fresh version:
|
78 |
|
79 | ```bash
|
80 | $ npm install
|
81 | $ gulp script
|
82 | ```
|
83 |
|
84 | The script is exported to `window.should`:
|
85 |
|
86 | ```js
|
87 | should(10).be.exactly(10)
|
88 | ```
|
89 |
|
90 | You can easy install it with npm or bower:
|
91 |
|
92 | ```sh
|
93 | npm install should -D
|
94 | # or
|
95 | bower install shouldjs/should.js
|
96 | ```
|
97 |
|
98 | ## API docs
|
99 |
|
100 | Actual api docs generated by jsdoc comments and available at [http://shouldjs.github.io](http://shouldjs.github.io).
|
101 |
|
102 | ## Usage examples
|
103 |
|
104 | Please look on usage in [examples](https://github.com/shouldjs/examples)
|
105 |
|
106 | ## .not
|
107 |
|
108 | `.not` negates the current assertion.
|
109 |
|
110 | ## .any
|
111 |
|
112 | `.any` allow for assertions with multiple parameters to assert any of the parameters (but not all). This is similar to the native JavaScript [array.some](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some).
|
113 |
|
114 | # Assertions
|
115 | ## chaining assertions
|
116 |
|
117 | Every assertion will return a `should.js`-wrapped Object, so assertions can be chained.
|
118 | To help chained assertions read more clearly, you can use the following helpers anywhere in your chain: `.an`, `.of`, `.a`, `.and`, `.be`, `.have`, `.with`, `.is`, `.which`. Use them for better readability; they do nothing at all.
|
119 | For example:
|
120 | ```js
|
121 | user.should.be.an.instanceOf(Object).and.have.property('name', 'tj');
|
122 | user.pets.should.be.instanceof(Array).and.have.lengthOf(4);
|
123 | ```
|
124 | Almost all assertions return the same object - so you can easy chain them. But some (eg: `.length` and `.property`) move the assertion object to a property value, so be careful.
|
125 |
|
126 | ## Adding own assertions
|
127 |
|
128 | Adding own assertion is pretty easy. You need to call `should.Assertion.add` function. It accept 2 arguments:
|
129 |
|
130 | 1. name of assertion method (string)
|
131 | 2. assertion function (function)
|
132 |
|
133 | What assertion function should do. It should check only positive case. `should` will handle `.not` itself.
|
134 | `this` in assertion function will be instance of `should.Assertion` and you **must** define in any way this.params object
|
135 | in your assertion function call before assertion check happen.
|
136 |
|
137 | `params` object can contain several fields:
|
138 |
|
139 | - `operator` - it is string which describe your assertion
|
140 | - `actual` it is actual value, you can assume it is your own this.obj if you need to define you own
|
141 | - `expected` it is any value that expected to be matched this.obj
|
142 |
|
143 | You can assume its usage in generating AssertionError message like: expected `obj`? || this.obj not? `operator` `expected`?
|
144 |
|
145 | In `should` sources appeared 2 kinds of usage of this method.
|
146 |
|
147 | First not preferred and used **only** for shortcuts to other assertions, e.g how `.should.be.true()` defined:
|
148 |
|
149 | ```javascript
|
150 | Assertion.add('true', function() {
|
151 | this.is.exactly(true);
|
152 | });
|
153 | ```
|
154 | There you can see that assertion function do not define own `this.params` and instead call within the same assertion `.exactly`
|
155 | that will fill `this.params`. **You should use this way very carefully, but you can use it**.
|
156 |
|
157 | Second way preferred and i assume you will use it instead of first.
|
158 |
|
159 | ```javascript
|
160 | Assertion.add('true', function() {
|
161 | this.params = { operator: 'to be true', expected: true };
|
162 |
|
163 | should(this.obj).be.exactly(true);
|
164 | });
|
165 | ```
|
166 | in this case this.params defined and then used new assertion context (because called `.should`). Internally this way does not
|
167 | create any edge cases as first.
|
168 |
|
169 | ```javascript
|
170 | Assertion.add('asset', function() {
|
171 | this.params = { operator: 'to be asset' };
|
172 |
|
173 | this.obj.should.have.property('id').which.is.a.Number();
|
174 | this.obj.should.have.property('path');
|
175 | })
|
176 |
|
177 | //then
|
178 | > ({ id: '10' }).should.be.an.asset();
|
179 | AssertionError: expected { id: '10' } to be asset
|
180 | expected '10' to be a number
|
181 |
|
182 | > ({ id: 10 }).should.be.an.asset();
|
183 | AssertionError: expected { id: 10 } to be asset
|
184 | expected { id: 10 } to have property path
|
185 | ```
|
186 |
|
187 |
|
188 | ## Contributions
|
189 |
|
190 | [Actual list of contributors](https://github.com/visionmedia/should.js/graphs/contributors) if you want to show it your friends.
|
191 |
|
192 | To run the tests for _should_ simply run:
|
193 |
|
194 | $ npm test
|
195 |
|
196 | See also [CONTRIBUTING](./CONTRIBUTING.md).
|
197 |
|
198 | ## OMG IT EXTENDS OBJECT???!?!@
|
199 |
|
200 | Yes, yes it does, with a single getter _should_, and no it won't break your code, because it does this **properly** with a non-enumerable property.
|
201 |
|
202 | Also it is possible use it without extension.
|
203 |
|
204 | ## License
|
205 |
|
206 | MIT © 2010-2014 TJ Holowaychuk
|