git.cworth.org Git - obsolete/notmuch-web/blob - node_modules/express/node_modules/qs/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
  23 To install both expresso _and_ node-jscoverage run
  24 the command below, which will first compile node-jscoverage:
  25
  26     $ make install
  27
  28 To install expresso alone without coverage reporting run:
  29
  30     $ make install-expresso
  31
  32 Install via npm:
  33
  34         $ npm install expresso
  35
  36 ## Examples
  37
  38 To define tests we simply export several functions:
  39
  40         exports['test String#length'] = function(){
  41                 assert.equal(6, 'foobar'.length);
  42         };
  43
  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:
  47
  48     module.exports = {
  49         'test String#length': function(){
  50                 assert.equal(6, 'foobar'.length);
  51         }
  52     };
  53
  54 If you prefer not to use quoted keys:
  55
  56         exports.testsStringLength = function(){
  57                 assert.equal(6, 'foobar'.length);
  58         };
  59
  60 The argument passed to each callback is _beforeExit_,
  61 which is typically used to assert that callbacks have been
  62 invoked.
  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
  83 Asserts that the given _val_ is _null_.
  84
  85     assert.isNull(null);
  86
  87 ### assert.isNotNull(val[, msg])
  88
  89 Asserts that the given _val_ is not _null_.
  90
  91     assert.isNotNull(undefined);
  92     assert.isNotNull(false);
  93
  94 ### assert.isUndefined(val[, msg])
  95
  96 Asserts that the given _val_ is _undefined_.
  97
  98     assert.isUndefined(undefined);
  99
 100 ### assert.isDefined(val[, msg])
 101
 102 Asserts that the given _val_ is not _undefined_.
 103
 104     assert.isDefined(null);
 105     assert.isDefined(false);
 106
 107 ### assert.match(str, regexp[, msg])
 108
 109 Asserts 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
 116 Assert 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
 123 Assert that the given _obj_ is typeof _type_.
 124
 125     assert.type(3, 'number');
 126
 127 ### assert.eql(a, b[, msg])
 128
 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 _==_.
 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
 139 Assert that _obj_ is within _val_. This method supports _Array_s
 140 and _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
 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
 152 as well.
 153
 154 The _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
 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:
 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
 171 When providing _res_ you may then also pass a callback function
 172 as the fourth argument for additional assertions.
 173
 174 Below 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
 223 To run a single test suite (file) run:
 224
 225     $ expresso test/a.test.js
 226
 227 To run several suites we may simply append another:
 228
 229     $ expresso test/a.test.js test/b.test.js
 230
 231 We can also pass a whitelist of tests to run within all suites:
 232
 233     $ expresso --only "foo()" --only "bar()"
 234
 235 Or several with one call:
 236
 237     $ expresso --only "foo(), bar()"
 238
 239 Globbing is of course possible as well:
 240
 241     $ expresso test/*
 242
 243 When expresso is called without any files, _test/*_ is the default,
 244 so the following is equivalent to the command above:
 245
 246     $ expresso
 247
 248 If you wish to unshift a path to `require.paths` before
 249 running tests, you may use the `-I` or `--include` flag.
 250
 251     $ expresso --include lib test/*
 252
 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.
 256
 257 To instrument your library, simply run [node-jscoverage](http://github.com/visionmedia/node-jscoverage),
 258 passing the _src_ and _dest_ directories:
 259
 260     $ node-jscoverage lib lib-cov
 261
 262 Now we can run our tests again, using the _lib-cov_ directory that has been
 263 instrumented with coverage statements:
 264
 265     $ expresso -I lib-cov test/*
 266
 267 The 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
 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:
 275
 276     $ expresso -I lib test/*
 277     $ expresso -I lib --cov test/*
 278
 279 Currently coverage is bound to the _lib_ directory, however in the
 280 future `--cov` will most likely accept a path.
 281
 282 ## Async Exports
 283
 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:
 285
 286         setTimeout(function(){
 287             exports['test async exports'] = function(){
 288                 assert.ok('wahoo');
 289             };
 290         }, 100);