/js/lib/Socket.IO-node/support/expresso/docs/index.md
Markdown | 290 lines | 201 code | 89 blank | 0 comment | 0 complexity | 5fb961ef3445c37d9b0f39af465e641d MD5 | raw file
Possible License(s): GPL-2.0, LGPL-2.1, MPL-2.0-no-copyleft-exception, BSD-3-Clause
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 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);