node_modules/ejs/support/expresso/docs/index.html

   1 <html>
   2         <head>
   3                 <title>Expresso - TDD Framework For Node</title>
   4                 <style>
   5                         body {
   6                                 font: 13px/1.4 "Helvetica", "Lucida Grande", Arial, sans-serif;
   7                         }
   8                         #header {
   9                                 position: absolute;
  10                             top: 10px;
  11                             left: 0;
  12                             padding: 14px 0 12px 0;
  13                             text-indent: 40px;
  14                             font-family: "Helvetica";
  15                             width: 100%;
  16                             border-top: 1px solid rgba(0,0,0,0.2);
  17                             border-bottom: 1px solid rgba(0,0,0,0.2);
  18                             background: rgba(255,255,255,0.6) url(http://www.sencha.com/favicon.ico) no-repeat 15px 50%;
  19                             text-align: left;
  20                             color: #888;
  21                     }
  22                         #ribbon {
  23                                 position: absolute;
  24                                 top: 0;
  25                                 right: 0;
  26                                 z-index: 10;
  27                         }
  28                         #wrapper {
  29                                 padding: 80px;
  30                         }
  31                         h1, h2, h3 {
  32                                 margin: 25px 0 15px 0;
  33                         }
  34                         pre {
  35                                 margin: 0 5px;
  36                                 padding: 10px;
  37                                 border: 1px solid #eee;
  38                         }
  39                 </style>
  40         </head>
  41         <body>
  42                 <a href="http://github.com/visionmedia/expresso">
  43                         <img alt="Fork me on GitHub" id="ribbon" src="http://s3.amazonaws.com/github/ribbons/forkme_right_white_ffffff.png" />
  44                 </a>
  45                 <div id="header"><strong>Sencha</strong> labs</div>
  46                 <div id="wrapper">
  47                         <h1>Expresso</h1>
  48 <div class='mp'>
  49 <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>
  50
  51 <h2 id="Features">Features</h2>
  52
  53 <ul>
  54 <li>light-weight</li>
  55 <li>intuitive async support</li>
  56 <li>intuitive test runner executable</li>
  57 <li>test coverage support and reporting via <a href="http://github.com/visionmedia/node-jscoverage">node-jscoverage</a></li>
  58 <li>uses and extends the core <em>assert</em> module</li>
  59 <li><code>assert.eql()</code> alias of <code>assert.deepEqual()</code></li>
  60 <li><code>assert.response()</code> http response utility</li>
  61 <li><code>assert.includes()</code></li>
  62 <li><code>assert.isNull()</code></li>
  63 <li><code>assert.isUndefined()</code></li>
  64 <li><code>assert.isNotNull()</code></li>
  65 <li><code>assert.isDefined()</code></li>
  66 <li><code>assert.match()</code></li>
  67 <li><code>assert.length()</code></li>
  68 </ul>
  69
  70
  71 <h2 id="Installation">Installation</h2>
  72
  73 <p>To install both expresso <em>and</em> node-jscoverage run
  74 the command below, which will first compile node-jscoverage:</p>
  75
  76 <pre><code>$ make install
  77 </code></pre>
  78
  79 <p>To install expresso alone without coverage reporting run:</p>
  80
  81 <pre><code>$ make install-expresso
  82 </code></pre>
  83
  84 <p>Install via npm:</p>
  85
  86 <pre><code>$ npm install expresso
  87 </code></pre>
  88
  89 <h2 id="Examples">Examples</h2>
  90
  91 <h2 id="Examples">Examples</h2>
  92
  93 <p>To define tests we simply export several functions:</p>
  94
  95 <pre><code>exports['test String#length'] = function(assert){
  96     assert.equal(6, 'foobar'.length);
  97 };
  98 </code></pre>
  99
 100 <p>Alternatively for large numbers of tests you may want to
 101 export your own object containing the tests, however this
 102 is essentially the as above:</p>
 103
 104 <pre><code>module.exports = {
 105     'test String#length': function(assert){
 106         assert.equal(6, 'foobar'.length);
 107     }
 108 };
 109 </code></pre>
 110
 111 <p>If you prefer not to use quoted keys:</p>
 112
 113 <pre><code>exports.testsStringLength = function(assert){
 114     assert.equal(6, 'foobar'.length);
 115 };
 116 </code></pre>
 117
 118 <p>The second argument passed to each callback is <em>beforeExit</em>,
 119 which is typically used to assert that callbacks have been
 120 invoked.</p>
 121
 122 <pre><code>exports.testAsync = function(assert, beforeExit){
 123     var n = 0;
 124     setTimeout(function(){
 125         ++n;
 126         assert.ok(true);
 127     }, 200);
 128     setTimeout(function(){
 129         ++n;
 130         assert.ok(true);
 131     }, 200);
 132     beforeExit(function(){
 133         assert.equal(2, n, 'Ensure both timeouts are called');
 134     });
 135 };
 136 </code></pre>
 137
 138 <h2 id="Assert-Utilities">Assert Utilities</h2>
 139
 140 <h3 id="assert-isNull-val-msg-">assert.isNull(val[, msg])</h3>
 141
 142 <p>Asserts that the given <em>val</em> is <em>null</em>.</p>
 143
 144 <pre><code>assert.isNull(null);
 145 </code></pre>
 146
 147 <h3 id="assert-isNotNull-val-msg-">assert.isNotNull(val[, msg])</h3>
 148
 149 <p>Asserts that the given <em>val</em> is not <em>null</em>.</p>
 150
 151 <pre><code>assert.isNotNull(undefined);
 152 assert.isNotNull(false);
 153 </code></pre>
 154
 155 <h3 id="assert-isUndefined-val-msg-">assert.isUndefined(val[, msg])</h3>
 156
 157 <p>Asserts that the given <em>val</em> is <em>undefined</em>.</p>
 158
 159 <pre><code>assert.isUndefined(undefined);
 160 </code></pre>
 161
 162 <h3 id="assert-isDefined-val-msg-">assert.isDefined(val[, msg])</h3>
 163
 164 <p>Asserts that the given <em>val</em> is not <em>undefined</em>.</p>
 165
 166 <pre><code>assert.isDefined(null);
 167 assert.isDefined(false);
 168 </code></pre>
 169
 170 <h3 id="assert-match-str-regexp-msg-">assert.match(str, regexp[, msg])</h3>
 171
 172 <p>Asserts that the given <em>str</em> matches <em>regexp</em>.</p>
 173
 174 <pre><code>assert.match('foobar', /^foo(bar)?/);
 175 assert.match('foo', /^foo(bar)?/);
 176 </code></pre>
 177
 178 <h3 id="assert-length-val-n-msg-">assert.length(val, n[, msg])</h3>
 179
 180 <p>Assert that the given <em>val</em> has a length of <em>n</em>.</p>
 181
 182 <pre><code>assert.length([1,2,3], 3);
 183 assert.length('foo', 3);
 184 </code></pre>
 185
 186 <h3 id="assert-type-obj-type-msg-">assert.type(obj, type[, msg])</h3>
 187
 188 <p>Assert that the given <em>obj</em> is typeof <em>type</em>.</p>
 189
 190 <pre><code>assert.type(3, 'number');
 191 </code></pre>
 192
 193 <h3 id="assert-eql-a-b-msg-">assert.eql(a, b[, msg])</h3>
 194
 195 <p>Assert that object <em>b</em> is equal to object <em>a</em>. This is an
 196 alias for the core <em>assert.deepEqual()</em> method which does complex
 197 comparisons, opposed to <em>assert.equal()</em> which uses <em>==</em>.</p>
 198
 199 <pre><code>assert.eql('foo', 'foo');
 200 assert.eql([1,2], [1,2]);
 201 assert.eql({ foo: 'bar' }, { foo: 'bar' });
 202 </code></pre>
 203
 204 <h3 id="assert-includes-obj-val-msg-">assert.includes(obj, val[, msg])</h3>
 205
 206 <p>Assert that <em>obj</em> is within <em>val</em>. This method supports <em>Array_s
 207 and </em>Strings_s.</p>
 208
 209 <pre><code>assert.includes([1,2,3], 3);
 210 assert.includes('foobar', 'foo');
 211 assert.includes('foobar', 'bar');
 212 </code></pre>
 213
 214 <h3 id="assert-response-server-req-res-fn-msg-fn-">assert.response(server, req, res|fn[, msg|fn])</h3>
 215
 216 <p>Performs assertions on the given <em>server</em>, which should <em>not</em> call
 217 listen(), as this is handled internally by expresso and the server
 218 is killed after all responses have completed. This method works with
 219 any <em>http.Server</em> instance, so <em>Connect</em> and <em>Express</em> servers will work
 220 as well.</p>
 221
 222 <p>The <em>req</em> object may contain:</p>
 223
 224 <ul>
 225 <li><em>url</em> request url</li>
 226 <li><em>timeout</em> timeout in milliseconds</li>
 227 <li><em>method</em> HTTP method</li>
 228 <li><em>data</em> request body</li>
 229 <li><em>headers</em> headers object</li>
 230 </ul>
 231
 232
 233 <p>The <em>res</em> object may be a callback function which
 234 receives the response for assertions, or an object
 235 which is then used to perform several assertions
 236 on the response with the following properties:</p>
 237
 238 <ul>
 239 <li><em>body</em> assert response body</li>
 240 <li><em>status</em> assert response status code</li>
 241 <li><em>header</em> assert that all given headers match (unspecified are ignored)</li>
 242 </ul>
 243
 244
 245 <p>When providing <em>res</em> you may then also pass a callback function
 246 as the fourth argument for additional assertions.</p>
 247
 248 <p>Below are some examples:</p>
 249
 250 <pre><code>assert.response(server, {
 251     url: '/', timeout: 500
 252 }, {
 253     body: 'foobar'
 254 });
 255
 256 assert.response(server, {
 257     url: '/',
 258     method: 'GET'
 259 },{
 260     body: '{"name":"tj"}',
 261     status: 200,
 262     headers: {
 263         'Content-Type': 'application/json; charset=utf8',
 264         'X-Foo': 'bar'
 265     }
 266 });
 267
 268 assert.response(server, {
 269     url: '/foo',
 270     method: 'POST',
 271     data: 'bar baz'
 272 },{
 273     body: '/foo bar baz',
 274     status: 200
 275 }, 'Test POST');
 276
 277 assert.response(server, {
 278     url: '/foo',
 279     method: 'POST',
 280     data: 'bar baz'
 281 },{
 282     body: '/foo bar baz',
 283     status: 200
 284 }, function(res){
 285     // All done, do some more tests if needed
 286 });
 287
 288 assert.response(server, {
 289     url: '/'
 290 }, function(res){
 291     assert.ok(res.body.indexOf('tj') &gt;= 0, 'Test assert.response() callback');
 292 });
 293 </code></pre>
 294
 295 <h2 id="expresso-1-">expresso(1)</h2>
 296
 297 <p>To run a single test suite (file) run:</p>
 298
 299 <pre><code>$ expresso test/a.test.js
 300 </code></pre>
 301
 302 <p>To run several suites we may simply append another:</p>
 303
 304 <pre><code>$ expresso test/a.test.js test/b.test.js
 305 </code></pre>
 306
 307 <p>We can also pass a whitelist of tests to run within all suites:</p>
 308
 309 <pre><code>$ expresso --only "foo()" --only "bar()"
 310 </code></pre>
 311
 312 <p>Or several with one call:</p>
 313
 314 <pre><code>$ expresso --only "foo(), bar()"
 315 </code></pre>
 316
 317 <p>Globbing is of course possible as well:</p>
 318
 319 <pre><code>$ expresso test/*
 320 </code></pre>
 321
 322 <p>When expresso is called without any files, <em>test/*</em> is the default,
 323 so the following is equivalent to the command above:</p>
 324
 325 <pre><code>$ expresso
 326 </code></pre>
 327
 328 <p>If you wish to unshift a path to <code>require.paths</code> before
 329 running tests, you may use the <code>-I</code> or <code>--include</code> flag.</p>
 330
 331 <pre><code>$ expresso --include lib test/*
 332 </code></pre>
 333
 334 <p>The previous example is typically what I would recommend, since expresso
 335 supports test coverage via <a href="http://github.com/visionmedia/node-jscoverage">node-jscoverage</a> (bundled with expresso),
 336 so you will need to expose an instrumented version of you library.</p>
 337
 338 <p>To instrument your library, simply run <a href="http://github.com/visionmedia/node-jscoverage">node-jscoverage</a>,
 339 passing the <em>src</em> and <em>dest</em> directories:</p>
 340
 341 <pre><code>$ node-jscoverage lib lib-cov
 342 </code></pre>
 343
 344 <p>Now we can run our tests again, using the <em>lib-cov</em> directory that has been
 345 instrumented with coverage statements:</p>
 346
 347 <pre><code>$ expresso -I lib-cov test/*
 348 </code></pre>
 349
 350 <p>The output will look similar to below, depending on your test coverage of course :)</p>
 351
 352 <p><img src="http://dl.dropbox.com/u/6396913/cov.png" alt="node coverage" /></p>
 353
 354 <p>To make this process easier expresso has the <em>-c</em> or <em>--cov</em> which essentially
 355 does the same as the two commands above. The following two commands will
 356 run the same tests, however one will auto-instrument, and unshift <em>lib-cov</em>,
 357 and the other will run tests normally:</p>
 358
 359 <pre><code>$ expresso -I lib test/*
 360 $ expresso -I lib --cov test/*
 361 </code></pre>
 362
 363 <p>Currently coverage is bound to the <em>lib</em> directory, however in the
 364 future <code>--cov</code> will most likely accept a path.</p>
 365
 366 <h2 id="Async-Exports">Async Exports</h2>
 367
 368 <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>
 369
 370 <pre><code>setTimeout(function(){
 371     exports['test async exports'] = function(assert){
 372         assert.ok('wahoo');
 373     };
 374 }, 100);
 375 </code></pre>
 376
 377 </div>
 378                 </div>
 379         </body>
 380 </html>