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