Node test utility
Lead Maintainer: Wyatt Preul
lab is a simple test utility for node. Unlike other test utilities, lab uses domains instead of uncaught exception and other global manipulation. Our goal with lab is to keep the execution engine as simple as possible, and not try to build an extensible framework. lab works with any assertion library that throws an error when a condition isn't met.
lab supports the following command line options:
-c
- enables code coverage analysis.-C
- enables or disables color output. Defaults to console capabilities.-d
- dry run. Skips all tests. Use with-v
to generate a test catalog. Defaults tofalse
.-e
- value to set theNODE_ENV
environment variable to, defaults to 'test'.-f
- do not perform a recursive load of test files within the test directory.-g
- only run tests matching the given pattern which is internally compiled to a RegExp.-h
- show command line usage.-i
- only run the test for the given identifier (or identifiers range).-I
- ignore a list of globals for the leak detection (comma separated)-l
- disables global variable leak detection.-m
- individual tests timeout in milliseconds (zero disables timeout). Defaults to 2 seconds.-o
- file to write the report to, 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 toconsole
. Options are:console
- text report.html
- HTML code coverage report (sets-c
).json
- output results in JSON format.junit
- output results in JUnit XML format.tap
- TAP protocol report.
-s
- silence test output, defaults to false.-t
- minimum code test coverage percentage (sets-c
), defaults to 100%.-v
- verbose test output, defaults to false.
To install lab globally:
$ npm install -g lab
To use locally:
$ npm install --save-dev 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 export a test script:
var Lab = require('lab');
var lab = exports.lab = Lab.script();
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(err)
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, no exception thrown, and no arguments are passed to done()
.
If no callback function is provided, the test is considered a TODO reminder and will be skipped.
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 async 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 (2000
ms or the value of-m
).parallel
- sets parallel execution of tests within each experiment level. Defaults tofalse
(serial execution).skip
- skip execution. Cannot be overridden in children once parent is set to skip.only
- marks all other tests or experiments withskip
. This doesn't mark all other experiments and tests in a suite of scripts as skipped, instead it works within a single test script.
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();
});
});
The script([options])
method takes an optional options
argument where options
is an object with the following optional keys:
schedule
- iffalse
, an automatic execution of the script is disabled. Automatic execution allows running lab test scripts directly with node without having to use the cli (e.g.node test/script.js
). When using lab programmatically, this behavior is undesired and can be turned off by settingschedule
tofalse
. Defaults totrue
.cli
- allows setting command line options within the script. Note that the last script file loaded wins and usage of this is recommended only for temporarily changing the execution of tests. This option is useful when code working with an automatic test engine that runs test on commits. Setting this option has no effect when not using the CLI runner. For example settingcli
to{ ids: [1] }
will only execute the first test loaded.
To make lab look like BDD:
var Lab = require('lab');
var lab = exports.lab = Lab.script();
var describe = lab.describe;
var it = lab.it;
var before = lab.before;
var after = lab.after;
var expect = Lab.expect;
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 lab = exports.lab = Lab.script();
var suite = lab.suite;
var test = lab.test;
var before = lab.before;
var after = lab.after;
var expect = Lab.expect;
suite('math', function () {
test('returns true when 1 + 1 equals 2', function (done) {
expect(1+1).to.equal(2);
done();
});
});
- Install lab as a global module:
$ npm install -g lab
- Add lab as a dev dependency to your project's
package.json
along with atest
script:
{
"name": "example",
"version": "1.0.0",
"dependencies": {
},
"devDependencies": {
"lab": "4.x.x"
},
"scripts": {
"test": "make test-cov"
},
"licenses": [
{
"type": "BSD",
"url": "http://github.com/hapijs/lab/raw/master/LICENSE"
}
]
}
- Add a
Makefile
to your project:
test:
@node node_modules/lab/bin/lab
test-cov:
@node node_modules/lab/bin/lab -t 100
test-cov-html:
@node node_modules/lab/bin/lab -r html -o coverage.html
.PHONY: test test-cov test-cov-html
Note that npm test
will execute lab with the -t 100
option which will require 100% code coverage. Change or remove
this option if you just cannot be bothered with producing quality code. Run make test-cov-html
and check the coverage.html
file to figure out where coverage is lacking.
- Run your tests with
$ npm test
lab initial code borrowed heavily from mocha, including the actual code used to render the coverage report into HTML. lab coverage code was originally adapted from blanket which in turn uses falafel.