-
-Installation
-------------
-
-There are two options for installing nodeunit:
-
-1. Clone / download nodeunit from [github](https://github.com/caolan/nodeunit),
- then:
-
- make && sudo make install
-
-2. Install via npm:
-
- npm install nodeunit
-
-API Documentation
------------------
-
-Nodeunit uses the functions available in the node.js
-[assert module](http://nodejs.org/docs/v0.4.2/api/assert.html):
-
-* __ok(value, [message])__ - Tests if value is a true value.
-* __equal(actual, expected, [message])__ - Tests shallow, coercive equality
- with the equal comparison operator ( == ).
-* __notEqual(actual, expected, [message])__ - Tests shallow, coercive
- non-equality with the not equal comparison operator ( != ).
-* __deepEqual(actual, expected, [message])__ - Tests for deep equality.
-* __notDeepEqual(actual, expected, [message])__ - Tests for any deep
- inequality.
-* __strictEqual(actual, expected, [message])__ - Tests strict equality, as
- determined by the strict equality operator ( === )
-* __notStrictEqual(actual, expected, [message])__ - Tests strict non-equality,
- as determined by the strict not equal operator ( !== )
-* __throws(block, [error], [message])__ - Expects block to throw an error.
-* __doesNotThrow(block, [error], [message])__ - Expects block not to throw an
- error.
-* __ifError(value)__ - Tests if value is not a false value, throws if it is a
- true value. Useful when testing the first argument, error in callbacks.
-
-Nodeunit also provides the following functions within tests:
-
-* __expect(amount)__ - Specify how many assertions are expected to run within a
- test. Very useful for ensuring that all your callbacks and assertions are
- run.
-* __done()__ - Finish the current test function, and move on to the next. ALL
- tests should call this!
-
-Nodeunit aims to be simple and easy to learn. This is achieved through using
-existing structures (such as node.js modules) to maximum effect, and reducing
-the API where possible, to make it easier to digest.
-
-Tests are simply exported from a module, but they are still run in the order
-they are defined.
-
-__Note:__ Users of old nodeunit versions may remember using ok, equals and same
-in the style of qunit, instead of the assert functions above. These functions
-still exist for backwards compatibility, and are simply aliases to their assert
-module counterparts.
-
-
-Asynchronous Testing
---------------------
-
-When testing asynchronous code, there are a number of sharp edges to watch out
-for. Thankfully, nodeunit is designed to help you avoid as many of these
-pitfalls as possible. For the most part, testing asynchronous code in nodeunit
-_just works_.
-
-
-### Tests run in series
-
-While running tests in parallel seems like a good idea for speeding up your
-test suite, in practice I've found it means writing much more complicated
-tests. Because of node's module cache, running tests in parallel means mocking
-and stubbing is pretty much impossible. One of the nicest things about testing
-in javascript is the ease of doing stubs:
-
- var _readFile = fs.readFile;
- fs.readFile = function(path, callback){
- // its a stub!
- };
- // test function that uses fs.readFile
-
- // we're done
- fs.readFile = _readFile;
-
-You cannot do this when running tests in parallel. In order to keep testing as
-simple as possible, nodeunit avoids it. Thankfully, most unit-test suites run
-fast anyway.
-
-
-### Explicit ending of tests
-
-When testing async code its important that tests end at the correct point, not
-just after a given number of assertions. Otherwise your tests can run short,
-ending before all assertions have completed. Its important to detect too
-many assertions as well as too few. Combining explicit ending of tests with
-an expected number of assertions helps to avoid false test passes, so be sure
-to use the test.expect() method at the start of your test functions, and
-test.done() when finished.
-
-
-Groups, setUp and tearDown
---------------------------
-
-Nodeunit allows the nesting of test functions:
-
- exports.test1 = function (test) {
- ...
- }
-
- exports.group = {
- test2: function (test) {
- ...
- },
- test3: function (test) {
- ...
- }
- }
-
-This would be run as:
-
- test1
- group - test2
- group - test3
-
-Using these groups its possible to add setUp and tearDown functions to your
-tests. Nodeunit has a utility function called testCase which allows you to
-define a setUp function, which is run before each test, and a tearDown
-function, which is run after each test calls test.done():
-
- var testCase = require('nodeunit').testCase;
-
- module.exports = testCase({
- setUp: function (callback) {
- this.foo = 'bar';
- callback();
- },
- tearDown: function (callback) {
- // clean up
- callback();
- },
- test1: function (test) {
- test.equals(this.foo, 'bar');
- test.done();
- }
- });
-
-In this way, its possible to have multiple groups of tests in a module, each
-group with its own setUp and tearDown functions.
-
-
-Running Tests
--------------
-
-Nodeunit comes with a basic command-line test runner, which can be installed
-using 'sudo make install'. Example usage:
-
- nodeunit testmodule1.js testfolder [...]
-
-The default test reporter uses color output, because I think that's more fun :) I
-intend to add a no-color option in future. To give you a feeling of the fun you'll
-be having writing tests, lets fix the example at the start of the README:
-
-
-
-Ahhh, Doesn't that feel better?
-
-When using the included test runner, it will exit using the failed number of
-assertions as the exit code. Exiting with 0 when all tests pass.
-
-
-### Command-line Options
-
-* __--reporter FILE__ - you can set the test reporter to a custom module or
-on of the modules in nodeunit/lib/reporters, when omitted, the default test runner
-is used.
-* __--list-reporters__ - list available build-in reporters.
-* __--config FILE__ - load config options from a JSON file, allows
-the customisation of color schemes for the default test reporter etc. See
-bin/nodeunit.json for current available options.
-* __--version__ or __-v__ - report nodeunit version
-* __--help__ - show nodeunit help
-
-
-Running tests in the browser
-----------------------------
-
-Nodeunit tests can also be run inside the browser. For example usage, see
-the examples/browser folder. The basic syntax is as follows:
-
-__test.html__
-
-
-
- '; - html += a.error.stack || a.error; - html += ''; - } - }; - html += '
');
- console.log(a.error.stack);
- console.log('');
- }
- });
- console.log('