custom libraries

All your tests need to do is output TAP with console.log().

Many test libraries such as mocha and tape are already capable outputing TAP with console.log(), but if you need to port an existing test library or prefer to write your own library, this guide can help.

test anything protocol

TAP is a simple text-based protocol. Here's an example:

TAP version 13
1..3
ok 1 - fundamental constants of the universe still work
ok 2 - euler's identity still holds
# beep boop

not ok 3 - arithmetic comparison
  expected: 5
  actual:   4

The first line, TAP version 13 is merely advisory, stating the version of the tap protocol we're going to use. It is ignored, but it's a good idea to include it anyways.

1..3 is the plan statement. It says how many tests are going to be run. It is mandatory. You can put the plan anywhere you like in the output, but there should be only one of them.

Lines that begin with ok and not ok followed by a sequence number are assertions. If any assertion begins with not ok, the whole test will be considered failed.

Sequence numbers should always be in order starting at 1 or else the test will be considered failed.

If The number of assertions does not match the plan: either too few or too many; the test is considered failed.

All lines not beginning with ^1..\d+, /^ok /, or /^not ok / are ignored. Put whatever you want in ignored lines. It's typical (but not enforced) for comments to begin with #.

example test library

We can build a super minimal library to output TAP for instructive purposes.

We'll use node-style modules to export our functionality:

var testNumber = 0;

exports.plan = function (n) {
    console.log('1..' + n);
};

exports.equal = function (a, b, desc) {
    ++ testNumber;
    if (!desc) desc = a + ' === ' + b;

    var prefix = a === b ? 'ok' : 'not ok';
    console.log(prefix + ' ' + testNumber + ' - ' + desc)
};

Here we've just implemented equal() and plan() but we could implement many other handy assertion functions such as deepEqual() and ok().

example test usage

To use our test library, just write some tests that require() the test library:

var test = require('./test_library.js')

test.plan(3);
test.equal(1+1, 2);
test.equal('a'+'b', 'ab');
test.equal(4*5, 20);

running the tests

We can verify our library in node:

$ node test.js
1..3
ok 1 - 2 === 2
ok 2 - ab === ab
ok 3 - 20 === 20

then we can verify our library locally in a real browser with the testling command:

$ browserfiy test.js | testling
1..3
ok 1 - 2 === 2
ok 2 - ab === ab
ok 3 - 20 === 20

and finally we can wire up everything to testling-ci proper for continuous integration.

If your custom test library might be useful to other folks, consider publishing it to npm where other people might find it!

After publishing, Just add your custom test library to the "devDependencies" field of package.json so that it will be available for your test code.

quick start guide
Create a github hook to run your tests on every push. Get a browser badge.
writing tests with tape
Write tests with a minimal test api that works in both node and browsers.
testing locally
Run your tests in node and your local browsers.
writing tests with mocha
Run tests in mocha for qunit, tdd, bdd, and exports-style tests.
module-driven development
Write code that is easier to maintain and easier to test with browserify.
dependency management
Use npm to manage your front-end dependencies.
advanced configuration
Read in-depth about the package.json "testling" field.
custom test libraries
Use your own test library by outputting TAP with `console.log()`.