PageRenderTime 427ms CodeModel.GetById 211ms app.highlight 15ms RepoModel.GetById 196ms 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
  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
 73the 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
 98export your own object containing the tests, however this
 99is 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>,
116which is typically used to assert that callbacks have been
117invoked.</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);
149assert.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);
164assert.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)?/);
172assert.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);
180assert.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
193alias for the core <em>assert.deepEqual()</em> method which does complex
194comparisons, opposed to <em>assert.equal()</em> which uses <em>==</em>.</p>
195
196<pre><code>assert.eql('foo', 'foo');
197assert.eql([1,2], [1,2]);
198assert.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
204and </em>Strings_s.</p>
205
206<pre><code>assert.includes([1,2,3], 3);
207assert.includes('foobar', 'foo');
208assert.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
214listen(), as this is handled internally by expresso and the server
215is killed after all responses have completed. This method works with
216any <em>http.Server</em> instance, so <em>Connect</em> and <em>Express</em> servers will work
217as 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
231receives the response for assertions, or an object
232which is then used to perform several assertions
233on 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
243as 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
253assert.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
265assert.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
274assert.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
285assert.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,
320so 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
326running 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
332supports test coverage via <a href="http://github.com/visionmedia/node-jscoverage">node-jscoverage</a> (bundled with expresso),
333so 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>,
336passing 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
342instrumented 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
352does the same as the two commands above. The following two commands will
353run the same tests, however one will auto-instrument, and unshift <em>lib-cov</em>,
354and 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
361future <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>