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

http://github.com/onedayitwillmake/RealtimeMultiplayerNodeJs · Markdown · 290 lines · 201 code · 89 blank · 0 comment · 0 complexity · 5fb961ef3445c37d9b0f39af465e641d MD5 · raw file

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