README.md

Node test utility

Introduction

lab is a simple test utility for node. Unlike other test utilities, lab uses domains instead of uncaught exception and other global manipulation which created conflicts with some spumko modules. Our goal with lab is to keep the execution engine as simple as possible, and not try to build an extensible framework.

Command Line

lab supports the following command line options:

• -c - enables code coverage analysis.
• -e - value to set the NODE_ENV environment variable to, defaults to 'test'.
• -G - export Lab as a global. Defaults to disabled. If you enable this, make sure to remove any require('lab') lines from your tests.
• -i - only run the test for the given identifier.
• -l - disables global variable leak detection.
• -m - individual tests timeout in milliseconds, defaults to 2 seconds.
• -o - file to save the report to (html only), otherwise sent to stdout.
• -p - sets parallel execution as default test option. Defaults to serial execution.
• -r - the reporter used to generate the test results. Defaults to console. Options are:
  • console - simple text output to console.
  • html - HTML code coverage report (sets -c).
  • json - output results in JSON format.
  • spec - Specification reporter.
  • summary - Test results summary.
  • tap - TAP reporter.
• -s - silence test output, defaults to false.
• -t - minimum code test coverage percentage (sets -c), defaults to 100%.

Usage

To install lab:

$ npm install lab

To start:

$ lab

By default, lab loads all the '*.js' files inside the local 'test' directory and executes the tests found. To start lab using different directories or files, pass those as arguments:

$ lab unit.js

Test files must require the lab module, and add tests using the test() method:

var Lab = require('lab');

Lab.test('returns true when 1 + 1 equals 2', function (done) {

    Lab.expect(1+1).to.equal(2);
    done();
});

When a test is completed, done() must be called, otherwise the test will time out (2 seconds by default) and will fail. The test passes if done() is call once before the timeout, and no exception thrown.

lab works with any test utility that throws an error when a condition isn't met. It uses the same error interface as mocha and already includes chai's expect() in its exported interface as shown above.

Tests can be organized into experiments:

Lab.experiment('math', function () {

    Lab.test('returns true when 1 + 1 equals 2', function (done) {

        Lab.expect(1+1).to.equal(2);
        done();
    });
});

If you need to perform some asynch actions before or after executing the tests inside an experiment, the before() and after() methods can be used. To execute code before or after each test in an experiment, use beforeEach() and afterEach().

Lab.experiment('math', function () {

    Lab.before(function (done) {

        // Wait 1 second
        setTimeout(function () { done(); }, 1000);
    });

    Lab.beforeEach(function (done) {

        // Run before every single test
        done();
    });

    Lab.test('returns true when 1 + 1 equals 2', function (done) {

        Lab.expect(1+1).to.equal(2);
        done();
    });
});

Both test() and experiment() accept an optional options argument which must be an object with the following optional keys:

• timeout - set a test or experiment specific timeout in milliseconds. Defaults to the global timeout (2000ms or the value of -m).
• parallel - sets parallel execution of tests within each experiment level. Defaults to false (serial execution).

Lab.experiment('math', { timeout: 1000 }, function () {

    Lab.test('returns true when 1 + 1 equals 2', { parallel: true }, function (done) {

        Lab.expect(1+1).to.equal(2);
        done();
    });
});

To make lab look like BDD:

var Lab = require('lab');

var describe = Lab.experiment;
var it = Lab.test;
var expect = Lab.expect;
var before = Lab.before;
var after = Lab.after;

describe('math', function () {

    it('returns true when 1 + 1 equals 2', function (done) {

        expect(1+1).to.equal(2);
        done();
    });
});

To make lab look like TDD:

var Lab = require('lab');

var suite = Lab.experiment;
var test = Lab.test;
var expect = Lab.expect;
var before = Lab.before;
var after = Lab.after;

suite('math', function () {

    test('returns true when 1 + 1 equals 2', function (done) {

        expect(1+1).to.equal(2);
        done();
    });
});

Acknowledgements

lab borrows heavily from mocha, including the actual code used to render the coverage report into HTML. mocha is a comprehensive test framework created by TJ Holowaychuk. lab coverage code was originally adapted from blanket which in turn uses falafel.