PageRenderTime 467ms CodeModel.GetById 54ms RepoModel.GetById 0ms app.codeStats 0ms

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

http://github.com/onedayitwillmake/RealtimeMultiplayerNodeJs
HTML | 377 lines | 286 code | 91 blank | 0 comment | 0 complexity | 3a1fc58058fbe5d204797387fad45297 MD5 | raw file
Possible License(s): GPL-2.0, LGPL-2.1, MPL-2.0-no-copyleft-exception, BSD-3-Clause 
    

  1. <html>
    2. 

  2. 	<head>
    3. 

  3. 		<title>Expresso - TDD Framework For Node</title>
    4. 

  4. 		<style>
    5. 

  5. 			body {
    6. 

  6. 				font: 13px/1.4 "Helvetica", "Lucida Grande", Arial, sans-serif;
    7. 

  7. 				text-align: center;
    8. 

  8. 			}
    9. 

  9. 			#ribbon {
    10. 

  10. 				position: absolute;
    11. 

  11. 				top: 0;
    12. 

  12. 				right: 0;
    13. 

  13. 				z-index: 10;
    14. 

  14. 			}
    15. 

  15. 			#wrapper {
    16. 

  16. 			  margin: 0 auto;
    17. 

  17. 				padding: 50px 80px;
    18. 

  18. 				width: 700px;
    19. 

  19. 				text-align: left;
    20. 

  20. 			}
    21. 

  21. 			h1, h2, h3 {
    22. 

  22. 				margin: 25px 0 15px 0;
    23. 

  23. 			}
    24. 

  24. 			h1 {
    25. 

  25. 			  font-size: 35px;
    26. 

  26. 			}
    27. 

  27. 			pre {
    28. 

  28. 				margin: 0 5px;
    29. 

  29. 				padding: 15px;
    30. 

  30. 				border: 1px solid #eee;
    31. 

  31. 			}
    32. 

  32. 			a {
    33. 

  33. 			  color: #00aaff;
    34. 

  34. 			}
    35. 

  35. 		</style>
    36. 

  36. 	</head>
    37. 

  37. 	<body>
    38. 

  38. 		<a href="http://github.com/visionmedia/expresso">
    39. 

  39. 			<img alt="Fork me on GitHub" id="ribbon" src="http://s3.amazonaws.com/github/ribbons/forkme_right_white_ffffff.png" />
    40. 

  40. 		</a>
    41. 

  41. 		<div id="wrapper">
    42. 

  42. 			<h1>Expresso</h1>
    43. 

  43. <div class='mp'>
    44. 

  44. <h2 id="NAME">NAME</h2>
    45. 

  45. <p class="man-name">
    46. 

  46.   <code>index</code>
    47. 

  47. </p>
    48. 

  48. <p><a href="http://github.com/visionmedia/expresso">Expresso</a> is a JavaScript <a href="http://en.wikipedia.org/wiki/Test-driven_development">TDD</a> framework written for <a href="http://nodejs.org">nodejs</a>. Expresso is extremely fast, and is packed with features such as additional assertion methods, code coverage reporting, CI support, and more.</p>
    49. 

  49. 

  50. <h2 id="Features">Features</h2>
    51. 

  51. 

  52. <ul>
    53. 

  53. <li>light-weight</li>
    54. 

  54. <li>intuitive async support</li>
    55. 

  55. <li>intuitive test runner executable</li>
    56. 

  56. <li>test coverage support and reporting via <a href="http://github.com/visionmedia/node-jscoverage">node-jscoverage</a></li>
    57. 

  57. <li>uses and extends the core <em>assert</em> module</li>
    58. 

  58. <li><code>assert.eql()</code> alias of <code>assert.deepEqual()</code></li>
    59. 

  59. <li><code>assert.response()</code> http response utility</li>
    60. 

  60. <li><code>assert.includes()</code></li>
    61. 

  61. <li><code>assert.isNull()</code></li>
    62. 

  62. <li><code>assert.isUndefined()</code></li>
    63. 

  63. <li><code>assert.isNotNull()</code></li>
    64. 

  64. <li><code>assert.isDefined()</code></li>
    65. 

  65. <li><code>assert.match()</code></li>
    66. 

  66. <li><code>assert.length()</code></li>
    67. 

  67. </ul>
    68. 

  68. 

  69. 

  70. <h2 id="Installation">Installation</h2>
    71. 

  71. 

  72. <p>To install both expresso <em>and</em> node-jscoverage run
    73. 

  73. the command below, which will first compile node-jscoverage:</p>
    74. 

  74. 

  75. <pre><code>$ make install
    76. 

  76. </code></pre>
    77. 

  77. 

  78. <p>To install expresso alone without coverage reporting run:</p>
    79. 

  79. 

  80. <pre><code>$ make install-expresso
    81. 

  81. </code></pre>
    82. 

  82. 

  83. <p>Install via npm:</p>
    84. 

  84. 

  85. <pre><code>$ npm install expresso
    86. 

  86. </code></pre>
    87. 

  87. 

  88. <h2 id="Examples">Examples</h2>
    89. 

  89. 

  90. <p>To define tests we simply export several functions:</p>
    91. 

  91. 

  92. <pre><code>exports['test String#length'] = function(){
    93. 

  93.     assert.equal(6, 'foobar'.length);
    94. 

  94. };
    95. 

  95. </code></pre>
    96. 

  96. 

  97. <p>Alternatively for large numbers of tests you may want to
    98. 

  98. export your own object containing the tests, however this
    99. 

  99. is essentially the as above:</p>
    100. 

  100. 

  101. <pre><code>module.exports = {
    102. 

  102.     'test String#length': function(){
    103. 

  103.         assert.equal(6, 'foobar'.length);
    104. 

  104.     }
    105. 

  105. };
    106. 

  106. </code></pre>
    107. 

  107. 

  108. <p>If you prefer not to use quoted keys:</p>
    109. 

  109. 

  110. <pre><code>exports.testsStringLength = function(){
    111. 

  111.     assert.equal(6, 'foobar'.length);
    112. 

  112. };
    113. 

  113. </code></pre>
    114. 

  114. 

  115. <p>The argument passed to each callback is <em>beforeExit</em>,
    116. 

  116. which is typically used to assert that callbacks have been
    117. 

  117. invoked.</p>
    118. 

  118. 

  119. <pre><code>exports.testAsync = function(beforeExit){
    120. 

  120.     var n = 0;
    121. 

  121.     setTimeout(function(){
    122. 

  122.         ++n;
    123. 

  123.         assert.ok(true);
    124. 

  124.     }, 200);
    125. 

  125.     setTimeout(function(){
    126. 

  126.         ++n;
    127. 

  127.         assert.ok(true);
    128. 

  128.     }, 200);
    129. 

  129.     beforeExit(function(){
    130. 

  130.         assert.equal(2, n, 'Ensure both timeouts are called');
    131. 

  131.     });
    132. 

  132. };
    133. 

  133. </code></pre>
    134. 

  134. 

  135. <h2 id="Assert-Utilities">Assert Utilities</h2>
    136. 

  136. 

  137. <h3 id="assert-isNull-val-msg-">assert.isNull(val[, msg])</h3>
    138. 

  138. 

  139. <p>Asserts that the given <em>val</em> is <em>null</em>.</p>
    140. 

  140. 

  141. <pre><code>assert.isNull(null);
    142. 

  142. </code></pre>
    143. 

  143. 

  144. <h3 id="assert-isNotNull-val-msg-">assert.isNotNull(val[, msg])</h3>
    145. 

  145. 

  146. <p>Asserts that the given <em>val</em> is not <em>null</em>.</p>
    147. 

  147. 

  148. <pre><code>assert.isNotNull(undefined);
    149. 

  149. assert.isNotNull(false);
    150. 

  150. </code></pre>
    151. 

  151. 

  152. <h3 id="assert-isUndefined-val-msg-">assert.isUndefined(val[, msg])</h3>
    153. 

  153. 

  154. <p>Asserts that the given <em>val</em> is <em>undefined</em>.</p>
    155. 

  155. 

  156. <pre><code>assert.isUndefined(undefined);
    157. 

  157. </code></pre>
    158. 

  158. 

  159. <h3 id="assert-isDefined-val-msg-">assert.isDefined(val[, msg])</h3>
    160. 

  160. 

  161. <p>Asserts that the given <em>val</em> is not <em>undefined</em>.</p>
    162. 

  162. 

  163. <pre><code>assert.isDefined(null);
    164. 

  164. assert.isDefined(false);
    165. 

  165. </code></pre>
    166. 

  166. 

  167. <h3 id="assert-match-str-regexp-msg-">assert.match(str, regexp[, msg])</h3>
    168. 

  168. 

  169. <p>Asserts that the given <em>str</em> matches <em>regexp</em>.</p>
    170. 

  170. 

  171. <pre><code>assert.match('foobar', /^foo(bar)?/);
    172. 

  172. assert.match('foo', /^foo(bar)?/);
    173. 

  173. </code></pre>
    174. 

  174. 

  175. <h3 id="assert-length-val-n-msg-">assert.length(val, n[, msg])</h3>
    176. 

  176. 

  177. <p>Assert that the given <em>val</em> has a length of <em>n</em>.</p>
    178. 

  178. 

  179. <pre><code>assert.length([1,2,3], 3);
    180. 

  180. assert.length('foo', 3);
    181. 

  181. </code></pre>
    182. 

  182. 

  183. <h3 id="assert-type-obj-type-msg-">assert.type(obj, type[, msg])</h3>
    184. 

  184. 

  185. <p>Assert that the given <em>obj</em> is typeof <em>type</em>.</p>
    186. 

  186. 

  187. <pre><code>assert.type(3, 'number');
    188. 

  188. </code></pre>
    189. 

  189. 

  190. <h3 id="assert-eql-a-b-msg-">assert.eql(a, b[, msg])</h3>
    191. 

  191. 

  192. <p>Assert that object <em>b</em> is equal to object <em>a</em>. This is an
    193. 

  193. alias for the core <em>assert.deepEqual()</em> method which does complex
    194. 

  194. comparisons, opposed to <em>assert.equal()</em> which uses <em>==</em>.</p>
    195. 

  195. 

  196. <pre><code>assert.eql('foo', 'foo');
    197. 

  197. assert.eql([1,2], [1,2]);
    198. 

  198. assert.eql({ foo: 'bar' }, { foo: 'bar' });
    199. 

  199. </code></pre>
    200. 

  200. 

  201. <h3 id="assert-includes-obj-val-msg-">assert.includes(obj, val[, msg])</h3>
    202. 

  202. 

  203. <p>Assert that <em>obj</em> is within <em>val</em>. This method supports <em>Array_s
    204. 

  204. and </em>Strings_s.</p>
    205. 

  205. 

  206. <pre><code>assert.includes([1,2,3], 3);
    207. 

  207. assert.includes('foobar', 'foo');
    208. 

  208. assert.includes('foobar', 'bar');
    209. 

  209. </code></pre>
    210. 

  210. 

  211. <h3 id="assert-response-server-req-res-fn-msg-fn-">assert.response(server, req, res|fn[, msg|fn])</h3>
    212. 

  212. 

  213. <p>Performs assertions on the given <em>server</em>, which should <em>not</em> call
    214. 

  214. listen(), as this is handled internally by expresso and the server
    215. 

  215. is killed after all responses have completed. This method works with
    216. 

  216. any <em>http.Server</em> instance, so <em>Connect</em> and <em>Express</em> servers will work
    217. 

  217. as well.</p>
    218. 

  218. 

  219. <p>The <em>req</em> object may contain:</p>
    220. 

  220. 

  221. <ul>
    222. 

  222. <li><em>url</em> request url</li>
    223. 

  223. <li><em>timeout</em> timeout in milliseconds</li>
    224. 

  224. <li><em>method</em> HTTP method</li>
    225. 

  225. <li><em>data</em> request body</li>
    226. 

  226. <li><em>headers</em> headers object</li>
    227. 

  227. </ul>
    228. 

  228. 

  229. 

  230. <p>The <em>res</em> object may be a callback function which
    231. 

  231. receives the response for assertions, or an object
    232. 

  232. which is then used to perform several assertions
    233. 

  233. on the response with the following properties:</p>
    234. 

  234. 

  235. <ul>
    236. 

  236. <li><em>body</em> assert response body (regexp or string)</li>
    237. 

  237. <li><em>status</em> assert response status code</li>
    238. 

  238. <li><em>header</em> assert that all given headers match (unspecified are ignored, use a regexp or string)</li>
    239. 

  239. </ul>
    240. 

  240. 

  241. 

  242. <p>When providing <em>res</em> you may then also pass a callback function
    243. 

  243. as the fourth argument for additional assertions.</p>
    244. 

  244. 

  245. <p>Below are some examples:</p>
    246. 

  246. 

  247. <pre><code>assert.response(server, {
    248. 

  248.     url: '/', timeout: 500
    249. 

  249. }, {
    250. 

  250.     body: 'foobar'
    251. 

  251. });
    252. 

  252. 

  253. assert.response(server, {
    254. 

  254.     url: '/',
    255. 

  255.     method: 'GET'
    256. 

  256. },{
    257. 

  257.     body: '{"name":"tj"}',
    258. 

  258.     status: 200,
    259. 

  259.     headers: {
    260. 

  260.         'Content-Type': 'application/json; charset=utf8',
    261. 

  261.         'X-Foo': 'bar'
    262. 

  262.     }
    263. 

  263. });
    264. 

  264. 

  265. assert.response(server, {
    266. 

  266.     url: '/foo',
    267. 

  267.     method: 'POST',
    268. 

  268.     data: 'bar baz'
    269. 

  269. },{
    270. 

  270.     body: '/foo bar baz',
    271. 

  271.     status: 200
    272. 

  272. }, 'Test POST');
    273. 

  273. 

  274. assert.response(server, {
    275. 

  275.     url: '/foo',
    276. 

  276.     method: 'POST',
    277. 

  277.     data: 'bar baz'
    278. 

  278. },{
    279. 

  279.     body: '/foo bar baz',
    280. 

  280.     status: 200
    281. 

  281. }, function(res){
    282. 

  282.     // All done, do some more tests if needed
    283. 

  283. });
    284. 

  284. 

  285. assert.response(server, {
    286. 

  286.     url: '/'
    287. 

  287. }, function(res){
    288. 

  288.     assert.ok(res.body.indexOf('tj') &gt;= 0, 'Test assert.response() callback');
    289. 

  289. });
    290. 

  290. </code></pre>
    291. 

  291. 

  292. <h2 id="expresso-1-">expresso(1)</h2>
    293. 

  293. 

  294. <p>To run a single test suite (file) run:</p>
    295. 

  295. 

  296. <pre><code>$ expresso test/a.test.js
    297. 

  297. </code></pre>
    298. 

  298. 

  299. <p>To run several suites we may simply append another:</p>
    300. 

  300. 

  301. <pre><code>$ expresso test/a.test.js test/b.test.js
    302. 

  302. </code></pre>
    303. 

  303. 

  304. <p>We can also pass a whitelist of tests to run within all suites:</p>
    305. 

  305. 

  306. <pre><code>$ expresso --only "foo()" --only "bar()"
    307. 

  307. </code></pre>
    308. 

  308. 

  309. <p>Or several with one call:</p>
    310. 

  310. 

  311. <pre><code>$ expresso --only "foo(), bar()"
    312. 

  312. </code></pre>
    313. 

  313. 

  314. <p>Globbing is of course possible as well:</p>
    315. 

  315. 

  316. <pre><code>$ expresso test/*
    317. 

  317. </code></pre>
    318. 

    319. 

  319. <p>When expresso is called without any files, <em>test/*</em> is the default,
    320. 

  320. so the following is equivalent to the command above:</p>
    321. 

    322. 

  322. <pre><code>$ expresso
    323. 

  323. </code></pre>
    324. 

    325. 

  325. <p>If you wish to unshift a path to <code>require.paths</code> before
    326. 

  326. running tests, you may use the <code>-I</code> or <code>--include</code> flag.</p>
    327. 

    328. 

  328. <pre><code>$ expresso --include lib test/*
    329. 

  329. </code></pre>
    330. 

    331. 

  331. <p>The previous example is typically what I would recommend, since expresso
    332. 

  332. supports test coverage via <a href="http://github.com/visionmedia/node-jscoverage">node-jscoverage</a> (bundled with expresso),
    333. 

  333. so you will need to expose an instrumented version of you library.</p>
    334. 

    335. 

  335. <p>To instrument your library, simply run <a href="http://github.com/visionmedia/node-jscoverage">node-jscoverage</a>,
    336. 

  336. passing the <em>src</em> and <em>dest</em> directories:</p>
    337. 

    338. 

  338. <pre><code>$ node-jscoverage lib lib-cov
    339. 

  339. </code></pre>
    340. 

    341. 

  341. <p>Now we can run our tests again, using the <em>lib-cov</em> directory that has been
    342. 

  342. instrumented with coverage statements:</p>
    343. 

    344. 

  344. <pre><code>$ expresso -I lib-cov test/*
    345. 

  345. </code></pre>
    346. 

    347. 

  347. <p>The output will look similar to below, depending on your test coverage of course :)</p>
    348. 

    349. 

  349. <p><img src="http://dl.dropbox.com/u/6396913/cov.png" alt="node coverage" /></p>
    350. 

    351. 

  351. <p>To make this process easier expresso has the <em>-c</em> or <em>--cov</em> which essentially
    352. 

  352. does the same as the two commands above. The following two commands will
    353. 

  353. run the same tests, however one will auto-instrument, and unshift <em>lib-cov</em>,
    354. 

  354. and the other will run tests normally:</p>
    355. 

    356. 

  356. <pre><code>$ expresso -I lib test/*
    357. 

  357. $ expresso -I lib --cov test/*
    358. 

  358. </code></pre>
    359. 

    360. 

  360. <p>Currently coverage is bound to the <em>lib</em> directory, however in the
    361. 

  361. future <code>--cov</code> will most likely accept a path.</p>
    362. 

    363. 

  363. <h2 id="Async-Exports">Async Exports</h2>
    364. 

    365. 

  365. <p>Sometimes it is useful to postpone running of tests until a callback or event has fired, currently the <em>exports.foo = function(){};</em> syntax is supported for this:</p>
    366. 

    367. 

  367. <pre><code>setTimeout(function(){
    368. 

  368.     exports['test async exports'] = function(){
    369. 

  369.         assert.ok('wahoo');
    370. 

  370.     };
    371. 

  371. }, 100);
    372. 

  372. </code></pre>
    373. 

    374. 

  374. </div>
    375. 

  375. 		</div>
    376. 

  376. 	</body>
    377. 

  377. </html>
    378.