Klud.js (kludges) is an ultimately minimal unit testing library (~1kB).

Briefly, klud.js gives you just four functions:

  • test() to write tests or to configure test reporting
  • ok() to do assertions
  • eq() to compare complex data
  • spy() to make spies (testable function wrappers)

Usage with npm

Install it:

npm install kludjs

Use it:

var test = require('kludjs');
test('My first test', function() {
    ok(2 + 2 == 4, 'Two plus two equals four');

Usage without npm

Download klud.js or klud.min.js if you want a core version without any test reporters.

If you're using a bare minimal version you may want to setup a custom function to report about passed/failed assertions etc, otherwise you won't see anything after you run your tests:

test(function(e, test, msg) {
    switch (e) {
        case 'begin':
            console.log('Test started: ' + test);
        case 'end':
            console.log('Test finished: ' + test);
        case 'pass':
            console.log('Assertion passed: ' + test + ':' + msg);
        case 'fail':
            console.log('Assertion failed: ' + test + ':' + msg);
        case 'except':
            console.log('Unhandled exception: ' + test + ':' + msg);

For Node and browser a simple reporter is already included.


Now you can start writing your tests:

var test = require('kludjs');

function isEven(x) {
    return x % 2 == 0;

test('Testing isEven', function() {
    ok(isEven(0), 'Zero is even');
    ok(isEven(1) == false, 'One is odd');
    ok(isEven(12), 'Twelve is even');

test() is a test declaration. Inside a test function you can use ok() to do assertions.

If your assertion needs to compare objects or arrays you can use eq() function:

test('Equal objects', function() {
    ok(eq([1, 2, 3], [1, 2, 3]), 'Arrays are equal');
    ok(eq({a:1, b:false}, {b:false, a:1}), 'Objects are equal');

Finally, if you have asynchronous code (I bet you have if you're using javascript) you can use async tests and spies to test your functions.

Asynchronous test looks very similar to normal tests, except for a next parameter is added to a test routine and the third parameter is added to the test function:

test('Async test', function(next) {
    setTimeout(function() {
        ok(1 == 1, 'it works!');
    }, 1000);
}, true);

All asynchronous tests are put to the queue and executed one by one, so be careful to not miss the next() call when your async test is finished.

A spy wraps a normal function but remembers function calls and thrown exceptions:

test('Function should be called', function() {
    var f = spy();
    ok(!f.called, 'function is not called yet');
    ok(f.called, 'function is called');

test('Function should throw exception', function() {
    var f = spy(function() {
        var a = unknownVariable; // should throw an exception
    ok(f.thrown.length == 1, 'exception thrown');

called and thrown are arrays. The first one contains the lists of arguments for every spy call, and the second one contains exception objects for every function call or undefined if no exception was thrown during the call.

Spy without an underlying function behaves like a function that returns undefined. It's useful to test is the callbacks are called in the right time in the right place with the right arguments.

That's all for now. Have fun!