/js/lib/Socket.IO-node/support/expresso/docs/index.md

  1
  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.
  3
  4## Features
  5
  6  - light-weight
  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
 13  - `assert.includes()`
 14  - `assert.isNull()`
 15  - `assert.isUndefined()`
 16  - `assert.isNotNull()`
 17  - `assert.isDefined()`
 18  - `assert.match()`
 19  - `assert.length()`
 20
 21## Installation
 22
 23To install both expresso _and_ node-jscoverage run
 24the command below, which will first compile node-jscoverage:
 25
 26    $ make install
 27
 28To install expresso alone without coverage reporting run:
 29
 30    $ make install-expresso
 31
 32Install via npm:
 33
 34	$ npm install expresso
 35
 36## Examples
 37
 38To define tests we simply export several functions:
 39
 40	exports['test String#length'] = function(){
 41		assert.equal(6, 'foobar'.length);
 42	};
 43
 44Alternatively for large numbers of tests you may want to
 45export your own object containing the tests, however this
 46is essentially the as above:
 47
 48    module.exports = {
 49      	'test String#length': function(){
 50        	assert.equal(6, 'foobar'.length);
 51      	}
 52    };
 53
 54If you prefer not to use quoted keys:
 55
 56	exports.testsStringLength = function(){
 57		assert.equal(6, 'foobar'.length);
 58	};
 59
 60The argument passed to each callback is _beforeExit_,
 61which is typically used to assert that callbacks have been
 62invoked.
 63
 64    exports.testAsync = function(beforeExit){
 65		var n = 0;
 66      	setTimeout(function(){
 67        	++n;
 68        	assert.ok(true);
 69      	}, 200);
 70      	setTimeout(function(){
 71        	++n;
 72        	assert.ok(true);
 73      	}, 200);
 74		beforeExit(function(){
 75			assert.equal(2, n, 'Ensure both timeouts are called');
 76		});
 77    };
 78
 79## Assert Utilities
 80
 81### assert.isNull(val[, msg])
 82
 83Asserts that the given _val_ is _null_.
 84
 85    assert.isNull(null);
 86
 87### assert.isNotNull(val[, msg])
 88
 89Asserts that the given _val_ is not _null_.
 90
 91    assert.isNotNull(undefined);
 92    assert.isNotNull(false);
 93
 94### assert.isUndefined(val[, msg])
 95
 96Asserts that the given _val_ is _undefined_.
 97
 98    assert.isUndefined(undefined);
 99
100### assert.isDefined(val[, msg])
101
102Asserts that the given _val_ is not _undefined_.
103
104    assert.isDefined(null);
105    assert.isDefined(false);
106
107### assert.match(str, regexp[, msg])
108
109Asserts that the given _str_ matches _regexp_.
110
111    assert.match('foobar', /^foo(bar)?/);
112    assert.match('foo', /^foo(bar)?/);
113
114### assert.length(val, n[, msg])
115
116Assert that the given _val_ has a length of _n_.
117
118    assert.length([1,2,3], 3);
119    assert.length('foo', 3);
120
121### assert.type(obj, type[, msg])
122
123Assert that the given _obj_ is typeof _type_.
124
125    assert.type(3, 'number');
126
127### assert.eql(a, b[, msg])
128
129Assert that object _b_ is equal to object _a_. This is an
130alias for the core _assert.deepEqual()_ method which does complex
131comparisons, opposed to _assert.equal()_ which uses _==_.
132
133    assert.eql('foo', 'foo');
134    assert.eql([1,2], [1,2]);
135    assert.eql({ foo: 'bar' }, { foo: 'bar' });
136
137### assert.includes(obj, val[, msg])
138
139Assert that _obj_ is within _val_. This method supports _Array_s
140and _Strings_s.
141
142    assert.includes([1,2,3], 3);
143    assert.includes('foobar', 'foo');
144    assert.includes('foobar', 'bar');
145
146### assert.response(server, req, res|fn[, msg|fn])
147
148Performs assertions on the given _server_, which should _not_ call
149listen(), as this is handled internally by expresso and the server 
150is killed after all responses have completed. This method works with
151any _http.Server_ instance, so _Connect_ and _Express_ servers will work
152as well.
153
154The _req_ object may contain:
155
156  - _url_ request url
157  - _timeout_ timeout in milliseconds
158  - _method_ HTTP method
159  - _data_ request body
160  - _headers_ headers object
161
162The _res_ object may be a callback function which
163receives the response for assertions, or an object
164which is then used to perform several assertions
165on the response with the following properties:
166
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)
170
171When providing _res_ you may then also pass a callback function
172as the fourth argument for additional assertions.
173
174Below are some examples:
175
176    assert.response(server, {
177	  	url: '/', timeout: 500
178    }, {
179		body: 'foobar'
180    });
181
182    assert.response(server, {
183        url: '/',
184        method: 'GET'
185    },{
186        body: '{"name":"tj"}',
187        status: 200,
188        headers: {
189            'Content-Type': 'application/json; charset=utf8',
190			'X-Foo': 'bar'
191        }
192    });
193    
194    assert.response(server, {
195        url: '/foo',
196        method: 'POST',
197        data: 'bar baz'
198    },{
199        body: '/foo bar baz',
200        status: 200
201    }, 'Test POST');
202
203    assert.response(server, {
204        url: '/foo',
205        method: 'POST',
206        data: 'bar baz'
207    },{
208        body: '/foo bar baz',
209        status: 200
210    }, function(res){
211		// All done, do some more tests if needed
212	});
213
214    assert.response(server, {
215        url: '/'
216    }, function(res){
217        assert.ok(res.body.indexOf('tj') >= 0, 'Test assert.response() callback');
218    });
219
220
221## expresso(1)
222
223To run a single test suite (file) run:
224
225    $ expresso test/a.test.js
226
227To run several suites we may simply append another:
228
229    $ expresso test/a.test.js test/b.test.js
230
231We can also pass a whitelist of tests to run within all suites:
232
233    $ expresso --only "foo()" --only "bar()"
234
235Or several with one call:
236
237    $ expresso --only "foo(), bar()"
238
239Globbing is of course possible as well:
240
241    $ expresso test/*
242
243When expresso is called without any files, _test/*_ is the default,
244so the following is equivalent to the command above:
245
246    $ expresso
247
248If you wish to unshift a path to `require.paths` before
249running tests, you may use the `-I` or `--include` flag.
250
251    $ expresso --include lib test/*
252
253The previous example is typically what I would recommend, since expresso
254supports test coverage via [node-jscoverage](http://github.com/visionmedia/node-jscoverage) (bundled with expresso),
255so you will need to expose an instrumented version of you library.
256
257To instrument your library, simply run [node-jscoverage](http://github.com/visionmedia/node-jscoverage),
258passing the _src_ and _dest_ directories:
259
260    $ node-jscoverage lib lib-cov
261
262Now we can run our tests again, using the _lib-cov_ directory that has been
263instrumented with coverage statements:
264
265    $ expresso -I lib-cov test/*
266
267The output will look similar to below, depending on your test coverage of course :)
268
269![node coverage](http://dl.dropbox.com/u/6396913/cov.png)
270
271To make this process easier expresso has the _-c_ or _--cov_ which essentially
272does the same as the two commands above. The following two commands will
273run the same tests, however one will auto-instrument, and unshift _lib-cov_,
274and the other will run tests normally:
275
276    $ expresso -I lib test/*
277    $ expresso -I lib --cov test/*
278
279Currently coverage is bound to the _lib_ directory, however in the
280future `--cov` will most likely accept a path.
281
282## Async Exports
283
284Sometimes 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:
285    
286	setTimeout(function(){
287	    exports['test async exports'] = function(){
288	        assert.ok('wahoo');
289	    };
290	}, 100);