kludjs v1.0.0

klud.js

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

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)

Installation

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

Download kludjs.js or kludjs.min.js if you want to use it in browser or Node:

var test = require('kludjs');
test('My first test', function() {
	...
});

Usage

If you're using a bare minimal version you may want to setup a function to report about passed/failed assertions etc:

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

For Node and Browser version you already have a simple reporter 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!');
		next();
	}, 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');
	f();
	ok(f.called, 'function is called');
});

test('Function should throw exception', function() {
	var f = spy(function() {
		var a = unknownVariable; // should throw an exception
	});
	f();
	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!