Skip to content
A powerful test runner for NodeJS applications.
JavaScript Shell
Pull request Compare This branch is even with cloudkick:v0.3.0.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Whiskey is a simple test runner for NodeJS applications.


  • Each test file is run in a separate process
  • Support for a test file timeout
  • Support for a "failfast mode" (runner exits after a first failure / timeout)
  • setUp / tearDown function support
  • Support for a test initialization function which is run before running the tests in a test file
  • Nicely formatted output (colors!)
  • Support for test coverage


  • Also instrument code in the node_modules directory (need to modify node-jscoverage to ignore shebang lines)


Console output (CLI test reporter) Console output (TAP test reporter) Code coverage #1 (HTML coverage reporter) Code coverage #2 (HTML coverage reporter) Code coverage (CLI coverage reporter)


  • optparse-js
  • async
  • sprintf
  • rimraf
  • magic-templates
  • node-jscoverage (only required if --coverage option is used)


  • 01.05.2011 - v0.3.0:
    • Refactor most of the internals to make the code more readable and more easy to extend
    • Communication between the main and child processes now takes place over a unix socket
    • Add support for "Reporter" classes
    • Remove the --init-file option
    • User can now specify a maximum number of async tests which will run at the same time (--concurrency [NUMBER] option)
    • Add a new "TAP" test reporter class (--test-reporter tap)
    • Add test coverage support with support for text and HTML output (--coverage option)
    • User can now specify a module with custom assertion functions which are attached to the assert object and passed to the each test function (--custom-assert-module MODULE_PATH)

Note: The test format has changed and it is not backward compatible with Whiskey 0.2.0.

Now each test gets passed in a special test object and a custom assert module which must be used to perform assertions.

exports['test_some_func'] = function(test, assert)`
  • 15.04.2011 - v0.2.3:

    • Better reporting on a test file timeout
    • Properly report if a test file does not exist or some other uncaught exception was thrown
    • Fix a bug with output buffer not being fully flushed on exit on OS X
    • add --print-stdout and --print-stderr option
  • 30.03.2011 - v0.2.2:

    • Add timeout support to the init, setUp and tearDown function - if the callback passed to one of those functions is not called in timeout milliseconds, an exception is thrown and test execution is aborted
    • Test timeout is now properly reported as a failure
  • 27.03.2011 - v0.2.1:

    • Handle uncaughtExceptions better
    • Use lighter colors so test status output is more distinguishable
    • Fix bug with "cannot find module" exception not being properly reported
    • Add support for per-test file init function / file
    • Print stdout and stderr on failure
  • 26.03.2011 - v0.2.0

    • Add support for the failfast mode (runner exists after a first failure)
    • User can specify custom test timeout by passing in the --timeout argument
    • Add support for a setUp and tearDown function
    • Add colors to the output
    • Now each test file must export all the test functions so the runner can iterate over them
    • Add support for a global initialization file / function (init function in this file is run before all the tests in a main process and can perform some kind of global initialization)
    • Add support for --chdir argument
  • 25.03.2011 - v0.1.0

    • Initial release (refactor module out from Cast and move it into a separate project)


Install it using npm: npm install whiskey


whiskey [options] --tests "<test files>"

Available options

  • -t, --tests - Whitespace separated list of test files to run
  • -ti, --test-init-file - A path to the initialization file which must export init function and it is called in a child process *before running the tests in each test file
  • -c, --chdir - An optional path to which the child process will chdir to before running the tests
  • --timeout [NUMBER] - How long to wait for tests to complete before timing out
  • --concurrency [NUMBER] - Maximum number of tests which will run in parallel
  • --print-stdout - Print data which was sent to stdout
  • --print-stderr - Print data which was sent to stderr
  • --test-reporter [cli,tap] - Which test reporter to use (defaults to cli)
  • --coverage - Use this option to enable the test coverage
  • --coverage-reporter [cli,html] - Which coverage reporter to use (defaults to cli)
  • --coverage-dir - Directory where the coverage HTML report is saved

Note: When specifying multiple test a list with the test paths must be quoted, for example: whiskey --tests "tests/a.js tests/b.js tests/c.js"


A simple example (success):

var called = 0;

exports['test_async_one_equals_one'] = function(test, assert) {
  setTimeout(function() {
    assert.equal(1, 1);
  }, 1000);

exports['tearDown'] = function(test, assert) {
  assert.equal(called, 1);

A simple example (failure):

exports['test_two_equals_one'] = function(test, assert) {
  assert.equal(2, 1);

For more examples please check the example/ folder.

Something went wrong with that request. Please try again.