2 [Expresso](http://github.com/visionmedia/expresso) is a JavaScript [TDD](http://en.wikipedia.org/wiki/Test-driven_development) framework written for [nodejs](http://nodejs.org). Expresso is extremely fast, and is packed with features such as additional assertion methods, code coverage reporting, CI support, and more.
7 - intuitive async support
8 - intuitive test runner executable
9 - test coverage support and reporting via [node-jscoverage](http://github.com/visionmedia/node-jscoverage)
10 - uses and extends the core _assert_ module
11 - `assert.eql()` alias of `assert.deepEqual()`
12 - `assert.response()` http response utility
15 - `assert.isUndefined()`
16 - `assert.isNotNull()`
17 - `assert.isDefined()`
23 To install both expresso _and_ node-jscoverage run
24 the command below, which will first compile node-jscoverage:
28 To install expresso alone without coverage reporting run:
30 $ make install-expresso
34 $ npm install expresso
38 To define tests we simply export several functions:
40 exports['test String#length'] = function(){
41 assert.equal(6, 'foobar'.length);
44 Alternatively for large numbers of tests you may want to
45 export your own object containing the tests, however this
46 is essentially the as above:
49 'test String#length': function(){
50 assert.equal(6, 'foobar'.length);
54 If you prefer not to use quoted keys:
56 exports.testsStringLength = function(){
57 assert.equal(6, 'foobar'.length);
60 The argument passed to each callback is _beforeExit_,
61 which is typically used to assert that callbacks have been
64 exports.testAsync = function(beforeExit){
66 setTimeout(function(){
70 setTimeout(function(){
74 beforeExit(function(){
75 assert.equal(2, n, 'Ensure both timeouts are called');
81 ### assert.isNull(val[, msg])
83 Asserts that the given _val_ is _null_.
87 ### assert.isNotNull(val[, msg])
89 Asserts that the given _val_ is not _null_.
91 assert.isNotNull(undefined);
92 assert.isNotNull(false);
94 ### assert.isUndefined(val[, msg])
96 Asserts that the given _val_ is _undefined_.
98 assert.isUndefined(undefined);
100 ### assert.isDefined(val[, msg])
102 Asserts that the given _val_ is not _undefined_.
104 assert.isDefined(null);
105 assert.isDefined(false);
107 ### assert.match(str, regexp[, msg])
109 Asserts that the given _str_ matches _regexp_.
111 assert.match('foobar', /^foo(bar)?/);
112 assert.match('foo', /^foo(bar)?/);
114 ### assert.length(val, n[, msg])
116 Assert that the given _val_ has a length of _n_.
118 assert.length([1,2,3], 3);
119 assert.length('foo', 3);
121 ### assert.type(obj, type[, msg])
123 Assert that the given _obj_ is typeof _type_.
125 assert.type(3, 'number');
127 ### assert.eql(a, b[, msg])
129 Assert that object _b_ is equal to object _a_. This is an
130 alias for the core _assert.deepEqual()_ method which does complex
131 comparisons, opposed to _assert.equal()_ which uses _==_.
133 assert.eql('foo', 'foo');
134 assert.eql([1,2], [1,2]);
135 assert.eql({ foo: 'bar' }, { foo: 'bar' });
137 ### assert.includes(obj, val[, msg])
139 Assert that _obj_ is within _val_. This method supports _Array_s
142 assert.includes([1,2,3], 3);
143 assert.includes('foobar', 'foo');
144 assert.includes('foobar', 'bar');
146 ### assert.response(server, req, res|fn[, msg|fn])
148 Performs assertions on the given _server_, which should _not_ call
149 listen(), as this is handled internally by expresso and the server
150 is killed after all responses have completed. This method works with
151 any _http.Server_ instance, so _Connect_ and _Express_ servers will work
154 The _req_ object may contain:
157 - _timeout_ timeout in milliseconds
158 - _method_ HTTP method
159 - _data_ request body
160 - _headers_ headers object
162 The _res_ object may be a callback function which
163 receives the response for assertions, or an object
164 which is then used to perform several assertions
165 on the response with the following properties:
167 - _body_ assert response body (regexp or string)
168 - _status_ assert response status code
169 - _header_ assert that all given headers match (unspecified are ignored, use a regexp or string)
171 When providing _res_ you may then also pass a callback function
172 as the fourth argument for additional assertions.
174 Below are some examples:
176 assert.response(server, {
177 url: '/', timeout: 500
182 assert.response(server, {
186 body: '{"name":"tj"}',
189 'Content-Type': 'application/json; charset=utf8',
194 assert.response(server, {
199 body: '/foo bar baz',
203 assert.response(server, {
208 body: '/foo bar baz',
211 // All done, do some more tests if needed
214 assert.response(server, {
217 assert.ok(res.body.indexOf('tj') >= 0, 'Test assert.response() callback');
223 To run a single test suite (file) run:
225 $ expresso test/a.test.js
227 To run several suites we may simply append another:
229 $ expresso test/a.test.js test/b.test.js
231 We can also pass a whitelist of tests to run within all suites:
233 $ expresso --only "foo()" --only "bar()"
235 Or several with one call:
237 $ expresso --only "foo(), bar()"
239 Globbing is of course possible as well:
243 When expresso is called without any files, _test/*_ is the default,
244 so the following is equivalent to the command above:
248 If you wish to unshift a path to `require.paths` before
249 running tests, you may use the `-I` or `--include` flag.
251 $ expresso --include lib test/*
253 The previous example is typically what I would recommend, since expresso
254 supports test coverage via [node-jscoverage](http://github.com/visionmedia/node-jscoverage) (bundled with expresso),
255 so you will need to expose an instrumented version of you library.
257 To instrument your library, simply run [node-jscoverage](http://github.com/visionmedia/node-jscoverage),
258 passing the _src_ and _dest_ directories:
260 $ node-jscoverage lib lib-cov
262 Now we can run our tests again, using the _lib-cov_ directory that has been
263 instrumented with coverage statements:
265 $ expresso -I lib-cov test/*
267 The output will look similar to below, depending on your test coverage of course :)
269 ![node coverage](http://dl.dropbox.com/u/6396913/cov.png)
271 To make this process easier expresso has the _-c_ or _--cov_ which essentially
272 does the same as the two commands above. The following two commands will
273 run the same tests, however one will auto-instrument, and unshift _lib-cov_,
274 and the other will run tests normally:
276 $ expresso -I lib test/*
277 $ expresso -I lib --cov test/*
279 Currently coverage is bound to the _lib_ directory, however in the
280 future `--cov` will most likely accept a path.
284 Sometimes it is useful to postpone running of tests until a callback or event has fired, currently the _exports.foo = function(){};_ syntax is supported for this:
286 setTimeout(function(){
287 exports['test async exports'] = function(){