nodeunit

Nodeunit

DEPRECATED PROJECT

The project is very stale. We've kept it working on new versions of node, and sometimes merged small PRs that help teams relying on nodeunit.

Nodeunit was the arguably first testing framework developed for node. It was very useful at the time, but there's an overwhelming number
of other worthwhile testing solutions out there that are actively maintained. tap, ava, tape, mocha, jasmine, jest, ... the list goes on and on.

If Nodeunit were truly bringing some different philosophy to the testing scene I'd say yes effort should be made to shore up it's development,
but given how many other great options there are out there, a benefit of letting it atrophy is it's one less choice people have to make when
choosing a testing solution. You are strongly encouraged to check out other more modern testing options.

Features

Simple to use

Just export the tests from a module

Works with node.js and in the browser

Helps you avoid common pitfalls when testing asynchronous code

Easy to add test cases with setUp and tearDown functions if you wish

Flexible reporters for custom output, built-in support for HTML and jUnit XML

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:

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 it's 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. It's 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.

In this way, it's 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 [...]

If no entry file specified, test defaults.

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. This means it exits 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 built-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.

If you wish to use a commonjs format for your test suites (using exports), it is
up to you to define the commonjs tools for the browser. There are a number of
alternatives and it's important it fits with your existing code, which is
why nodeunit does not currently provide this out of the box.

In the example above, the tests will run when the page is loaded.

The browser-version of nodeunit.js is created in dist/browser when you do, make browser. You'll need UglifyJS installed in
order for it to automatically create nodeunit.min.js.

Adding nodeunit to Your Projects

If you don't want people to have to install the nodeunit command-line tool,
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, that assumes you
have nodeunit in a suitably located node_modules directory.

If you're using git, you might find it useful to include nodeunit as a
submodule. Using submodules makes it easy for developers to download nodeunit
and run your test suite, without cluttering up your repository with
the source code. To add nodeunit as a git submodule do the following:

Now if someone attempts to run your test suite without nodeunit installed they
will be prompted to download the submodules for your project.

Built-in Test Reporters

default - The standard reporter seen in the nodeunit screenshots

minimal - Pretty, minimal output, shows errors and progress only

html - Outputs a HTML report to stdout

junit - Creates jUnit compatible XML reports, which can be used with
continuous integration tools such as Hudson.

machineout - Simple reporter for machine analysis. There is
nodeunit.vim which is useful for TDD on VIM.

Writing a Test Reporter

Nodeunit exports runTest(fn, options), runModule(mod, options) and
runFiles(paths, options). You'll most likely want to run test suites from
files, which can be done using the latter function. The options argument can
contain callbacks which run during testing. Nodeunit provides the following
callbacks:

moduleStart(name) - called before a module is tested

moduleDone(name, assertions) - called once all test functions within the
module have completed (see assertions object reference below)
ALL tests within the module

testStart(name) - called before a test function is run

testReady(test) - called before a test function is run with the test object that will be passed to the test function

testDone(name, assertions) - called once a test function has completed
(by calling test.done())

log(assertion) - called whenever an assertion is made (see assertion
object reference below)

done(assertions) - called after all tests/modules are complete

The assertion object:

passed() - did the assertion pass?

failed() - did the assertion fail?

error - the AssertionError if the assertion failed

method - the nodeunit assertion method used (ok, same, equals...)

message - the message the assertion method was called with (optional)

The assertionList object:

An array-like object with the following new attributes:

failures() - the number of assertions which failed

duration - the time taken for the test to complete in msecs

For a reference implementation of a test reporter, see lib/reporters/default.js in
the nodeunit project directory.

Sandbox utility

This is a function which evaluates JavaScript files in a sandbox and returns the
context. The sandbox function can be used for testing client-side code or private
un-exported functions within a module.

sandbox(files, sandbox) - Evaluates JavaScript files in a sandbox, returning
the context. The first argument can either be a single filename or an array of
filenames. If multiple filenames are given their contents are concatenated before
evaluation. The second argument is an optional context to use for the sandbox.

Note: When working with the sandbox if your script depends on outside sources
(i.e. using require) then you will want to pass that into the optional
context when setting up the sandbox.

Running the nodeunit Tests

The tests for nodeunit are written using nodeunit itself as the test framework.
However, the module test-base.js first does some basic tests using the assert
module to ensure that test functions are actually run, and a basic level of
nodeunit functionality is available.

To run the nodeunit tests do:

make test

Note: There was a bug in node v0.2.0 causing the tests to hang, upgrading
to v0.2.1 fixes this.

machineout reporter

The default reporter is readable for human but not for machine analysis.
When you want to analyze the output of nodeunit, use machineout reporter and you will get