Programmatically running unit tests with nodeunit in node.js

Unit testing and unit testing frameworks are an important part of any significant development project. For our needs, the unit testing framework that turned out to be the best option was nodeunit. However, maybe because we are running on Windows (not linux), it took a little bit to figure out a nice clean way to run the unit tests.

In the end, we wrote our own node.js script to run the unit tests and we thought it might be nice to share that with others to save some time.

First you need to install the package using npm.  As expected, you do this by running:

npm install nodeunit

Now that nodeunit is installed, you can create your test cases in separate files. They are fairly simple to create if you read through some of the documentation on the nodeunit website. We’ll also have an upcoming article on writing test cases in nodeunit for some examples.

Once you’ve written your test cases and saved them in a js file, you are now ready to run them. Now there are a few different methods of doing this, but we ended up using the following launcher script which gives us a little more control.  Here’s the source for the launcher script we use:

 * Kick-off script for unit tests

var reporter = require('nodeunit').reporters.default;


var run_tests = new Array();
var tests_available = { 
    'remote_callback' : 'module_1/tests_mod_1.js',
    'lock' : 'module_2/tests_mod_2.js',
    'db' : 'module_3/tests_mod_3.js'

var test_name;

// Check if any arguments were provided to the script
if(process.argv.length > 2) {
    var i;
	// For each argument, treat it as the name of a test
    for(i = 2; i < process.argv.length; i++) {
        test_name = process.argv[i];
        if(tests_available.hasOwnProperty(test_name)) {
			// Add the test to the list of tests to run
        } else {
            console.log("Invalid test '" + test_name + "'");
} else {
	// No arguments provided to the script, so we run all the tests
    for(test_name in tests_available) {
        if(tests_available.hasOwnProperty(test_name)) {

// Tell the reporter to run the tests
if(run_tests.length > 0) {;

In this script, you can see that in the variable called “tests_available” we are defining a set of names and files for the tests.  If you had multiple files which contain unit tests for your application, this is where you would list them all.

If you save this script as “run_tests.js”, you can now execute all the test cases in all the test files by running:

node run_tests.js

By giving each test file a simple name in the “tests_available” object, it gives an easy way to run a single test file by specifying the name on the command line. You would do this by specifying the name as a command line argument like this:

node run_tests.js module_1

This would run the tests for module_1 which are contained in the file ‘module_1/tests_mod_1.js’.

In case you haven’t read anything about nodeunit, it’s important to note that this is not the only way to do this. There is a launcher script that comes with nodeunit but for simplicity of launching tests, this script made it easier for us.

Leave us a comment if you have anything to add or any questions.

Leave a Comment