Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP


tag: 0.1.2

Fetching latest commit…

Cannot retrieve the latest commit at this time


If you're looking for a full-featured and descriptive specification framework you might want to checkout a project like the excellent jspec. If, like me, you just want to dive into writing some code and don't want to learn an extensive framework before writing tests, then nodeunit could be for you.

nodeunit offers easy unit testing based on a simplified version of the QUnit API. However, unlike QUnit, it assumes all your tests are asynchronous, and plays nicely with the existing module system. Because of these assumptions, the already minimal API offered by QUnit can be further reduced.

nodeunit is available as an npm package:

npm install nodeunit



Here is an example unit test module:

exports.testSomething = function(test){
    test.ok(true, "this assertion should pass");

exports.testSomethingElse = function(test){
    test.ok(false, "this assertion should fail");

When run using the included testrunner, this will output the following:

API Documentation

  • ok(state, message) - A boolean assertion, equivalent to assert.ok
  • equals(actual, expected, message) - A comparison assertion, equivalent to assert.equal
  • same(actual, expected, message) - A deep recursive comparison, equivalent to assert.deepEquals
  • done() - Finish this test function, and move on to the next. ALL tests should call this!

These 5 functions are all you need to know!


Tests are simply exported from a module, but they are still run in the order they are defined. The module() call from QUnit can be omitted, since it is inside a module file, and we can refer to it by filename.

Asynchronous Testing


Tests run in series


var _readFile = fs.readFile;
fs.readFile = function(path, callback){
    // its a stub!
// test function that uses fs.readFile

// we're done
fs.readFile = _readFile;


Explicit ending of tests


Running Tests

nodeunit comes with a basic command-line test runner, which exists in the lib folder. Example usage:

node nodeunit/lib/testrunner.js testmodule1.js testfolder [...]


Ahhh, Doesn't that feel better?

You can also add some code to the bottom of your test modules so they can be run directly from the command-line:

if( == '.'){
    var testrunner = require('nodeunit').testrunner;[__filename]);

NOTE: this requires nodeunit to be in your require paths. You can make nodeunit available to all your projects by copying it to ~/.node-libraries


Adding nodeunit to Your Projects

Usually, you'll want to create a script that runs the tests for your project with the correct require paths set up. Here's an example test script, with deps, lib and test directories:


require.paths.push(__dirname + '/deps');
require.paths.push(__dirname + '/lib');
var testrunner = require('nodeunit').testrunner;



git submodule add git:// deps/nodeunit

This will add nodeunit to the deps folder of your project. Now, when cloning the repository, nodeunit can be downloaded by doing the following:

git submodule init
git submodule update



require.paths.push(__dirname + '/deps');
require.paths.push(__dirname + '/lib');

try {
    var testrunner = require('nodeunit').testrunner;
catch(e) {
    var sys = require('sys');
    sys.puts("Cannot find nodeunit module.");
    sys.puts("You can download submodules for this project by doing:");
    sys.puts("    git submodule init");
    sys.puts("    git submodule update");



Writing a Test Runner


  • moduleStart(name) - called before a module is tested

The assertion object:

  • passed() - did the assertion pass?
  • failed() - did the assertion fail?
  • error - the AssertionError if the assertion failed

The assertions object:

  • An array-like object with the following new attributes:
    • failures - the number of assertions which failed

For a reference implementation of a test runner, see lib/testrunner.js in the nodeunit project directory.

Running the nodeunit Tests


To run the nodeunit tests do: node test.js

Note: The tests hang when using node v0.2.0, upgrading to v0.2.1 fixes this.

Something went wrong with that request. Please try again.