Litmus is a unit testing framework for JavaScript.

Installing

NPM is recommended for development, although for production you might want to find/build a package for your operating system:

npm install litmus

Writing a Simple Test

Litmus tests are ordinary CommonJS modules, by convention in a folder called tests within your project. Each test module should export either a litmus.Test or litmus.Suite instance:

var litmus = require('litmus');

module.exports = new litmus.Test(module, function () {
    this.plan(1);
    
    this.ok(1 === 1, 'one is equal to one');
});

This is a simple test containing a single assertion. To run the tests run the litmus command, with the path to the file containing the test as a parameter:

litmus tests/simple.js

See all builtin assertions.

Combining Multiple Tests into a Suite

To create a test suite, export a litmus.Suite in a module (by convention tests/suite.js in your project):

var litmus = require('litmus');

module.exports = new litmus.Suite(module, [
    require('./simple.js'),
    // ...
]);

To run the suite:

litmus tests/suite.js

Asynchronous Tests

To test asynchronous code, use the this.async method to tell litmus that it should expect assertions after the initial execution of the function passed when creating the litmus.Test. The async method returns a handle that is used to tell litmus when the async assertions have finished:

var handle = this.async('description of async operation');

var test = this;

setTimeout(function () {

    test.ok(1 === 1, 'one is equal to one');    

    handle.finish();

}, 50);

Alternatively, you can pass a function to the async method, which will be called with the handle as a parameter:

this.async('description of async operation', function (handle) {

    var test = this;

    setTimeout(function () {
        
        test.ok(1 === 1, 'one is equal to one');

        handle.finish();

    }, 50);

});

Skipping Tests

From time to time, tests will only work in certain circumstances - for example in certain environments. To skip a set of assertions based on some condition use the skipif method, passing the number of assertions that are skipped if the supplied function is not executed:

this.skipif(env === 'browser', 'filesystem tests skipped', 5, function () {

    this.ok(1 === 1, 'one is equal to one');

    // four more assertions... 

});

Writing Assertions

See builtin assertions for a list of available assertions.