substack/tape


tap-producing test harness for node and browsers

License: MIT

Language: JavaScript


tape

tap-producing test harness for node and browsers

browser support

build status

tape

example

var test = require('tape');

test('timing test', function (t) {
    t.plan(2);

    t.equal(typeof Date.now, 'function');
    var start = Date.now();

    setTimeout(function () {
        t.equal(Date.now() - start, 100);
    }, 100);
});
$ node example/timing.js
TAP version 13
# timing test
ok 1 should be equal
not ok 2 should be equal
  ---
    operator: equal
    expected: 100
    actual:   107
  ...

1..2
# tests 2
# pass  1
# fail  1

usage

You always need to require('tape') in test files. You can run the tests by usual node means (require('test-file.js') or node test-file.js). You can also run tests using the tape binary to utilize globbing, on Windows for example:

$ tape tests/**/*.js

tape's arguments are passed to the glob module. If you want glob to perform the expansion on a system where the shell performs such expansion, quote the arguments as necessary:

$ tape 'tests/**/*.js'
$ tape "tests/**/*.js"

Preloading modules

Additionally, it is possible to make tape load one or more modules before running any tests, by using the -r or --require flag. Here's an example that loads babel-register before running any tests, to allow for JIT compilation:

$ tape -r babel-register tests/**/*.js

Depending on the module you're loading, you may be able to parameterize it using environment variables or auxiliary files. Babel, for instance, will load options from .babelrc at runtime.

The -r flag behaves exactly like node's require, and uses the same module resolution algorithm. This means that if you need to load local modules, you have to prepend their path with ./ or ../ accordingly.

For example:

$ tape -r ./my/local/module tests/**/*.js

Please note that all modules loaded using the -r flag will run before any tests, regardless of when they are specified. For example, tape -r a b -r c will actually load a and c before loading b, since they are flagged as required modules.

things that go well with tape

tape maintains a fairly minimal core. Additional features are usually added by using another module alongside tape.

pretty reporters

The default TAP output is good for machines and humans that are robots.

If you want a more colorful / pretty output there are lots of modules on npm that will output something pretty if you pipe TAP into them:

To use them, try node test/index.js | tap-spec or pipe it into one of the modules of your choice!

uncaught exceptions

By default, uncaught exceptions in your tests will not be intercepted, and will cause tape to crash. If you find this behavior undesirable, use tape-catch to report any exceptions as TAP errors.

other

methods

The assertion methods in tape are heavily influenced or copied from the methods in node-tap.

var test = require('tape')

test([name], [opts], cb)

Create a new test with an optional name string and optional opts object. cb(t) fires with the new test object t once all preceding tests have finished. Tests execute serially.

Available opts options are:

  • opts.skip = true/false. See test.skip.
  • opts.timeout = 500. Set a timeout for the test, after which it will fail. See test.timeoutAfter.
  • opts.objectPrintDepth = 5. Configure max depth of expected / actual object printing. Environmental variable NODE_TAPE_OBJECT_PRINT_DEPTH can set the desired default depth for all tests; locally-set values will take precedence.
  • opts.todo = true/false. Test will be allowed to fail.

If you forget to t.plan() out how many assertions you are going to run and you don't call t.end() explicitly, your test will hang.

test.skip([name], [opts], cb)

Generate a new test that will be skipped over.

test.onFinish(fn)

The onFinish hook will get invoked when ALL tape tests have finished right before tape is about to print the test summary.

test.onFailure(fn)

The onFailure hook will get invoked whenever any tape tests has failed.

t.plan(n)

Declare that n assertions should be run. t.end() will be called automatically after the nth assertion. If there are any more assertions after the nth, or after t.end() is called, they will generate errors.

t.end(err)

Declare the end of a test explicitly. If err is passed in t.end will assert that it is falsey.

t.fail(msg)

Generate a failing assertion with a message msg.

t.pass(msg)

Generate a passing assertion with a message msg.

t.timeoutAfter(ms)

Automatically timeout the test after X ms.

t.skip(msg)

Generate an assertion that will be skipped over.

t.ok(value, msg)

Assert that value is truthy with an optional description of the assertion msg.

Aliases: t.true(), t.assert()

t.notOk(value, msg)

Assert that value is falsy with an optional description of the assertion msg.

Aliases: t.false(), t.notok()

t.error(err, msg)

Assert that err is falsy. If err is non-falsy, use its err.message as the description message.

Aliases: t.ifError(), t.ifErr(), t.iferror()

t.equal(actual, expected, msg)

Assert that actual === expected with an optional description of the assertion msg.

Aliases: t.equals(), t.isEqual(), t.is(), t.strictEqual(), t.strictEquals()

t.notEqual(actual, expected, msg)

Assert that actual !== expected with an optional description of the assertion msg.

Aliases: t.notEquals(), t.notStrictEqual(), t.notStrictEquals(), t.isNotEqual(), t.isNot(), t.not(), t.doesNotEqual(), t.isInequal()

t.deepEqual(actual, expected, msg)

Assert that actual and expected have the same structure and nested values using node's deepEqual() algorithm with strict comparisons (===) on leaf nodes and an optional description of the assertion msg.

Aliases: t.deepEquals(), t.isEquivalent(), t.same()

t.notDeepEqual(actual, expected, msg)

Assert that actual and expected do not have the same structure and nested values using node's deepEqual() algorithm with strict comparisons (===) on leaf nodes and an optional description of the assertion msg.

Aliases: t.notDeepEquals, t.notEquivalent(), t.notDeeply(), t.notSame(), t.isNotDeepEqual(), t.isNotDeeply(), t.isNotEquivalent(), t.isInequivalent()

t.deepLooseEqual(actual, expected, msg)

Assert that actual and expected have the same structure and nested values using node's deepEqual() algorithm with loose comparisons (==) on leaf nodes and an optional description of the assertion msg.

Aliases: t.looseEqual(), t.looseEquals()

t.notDeepLooseEqual(actual, expected, msg)

Assert that actual and expected do not have the same structure and nested values using node's deepEqual() algorithm with loose comparisons (==) on leaf nodes and an optional description of the assertion msg.

Aliases: t.notLooseEqual(), t.notLooseEquals()

t.throws(fn, expected, msg)

Assert that the function call fn() throws an exception. expected, if present, must be a RegExp or Function. The RegExp matches the string representation of the exception, as generated by err.toString(). The Function is the exception thrown (e.g. Error). msg is an optional description of the assertion.

t.doesNotThrow(fn, expected, msg)

Assert that the function call fn() does not throw an exception. expected, if present, limits what should not be thrown. For example, set expected to /user/ to fail the test only if the string representation of the exception contains the word user. Any other exception would pass the test. If expected is omitted, any exception will fail the test. msg is an optional description of the assertion.

t.test(name, [opts], cb)

Create a subtest with a new test handle st from cb(st) inside the current test t. cb(st) will only fire when t finishes. Additional tests queued up after t will not be run until all subtests finish.

You may pass the same options that test() accepts.

t.comment(message)

Print a message without breaking the tap output. (Useful when using e.g. tap-colorize where output is buffered & console.log will print in incorrect order vis-a-vis tap output.)

var htest = test.createHarness()

Create a new test harness instance, which is a function like test(), but with a new pending stack and test state.

By default the TAP output goes to console.log(). You can pipe the output to someplace else if you htest.createStream().pipe() to a destination stream on the first tick.

test.only([name], [opts], cb)

Like test([name], [opts], cb) except if you use .only this is the only test case that will run for the entire process, all other test cases using tape will be ignored.

var stream = test.createStream(opts)

Create a stream of output, bypassing the default output stream that writes messages to console.log(). By default stream will be a text stream of TAP output, but you can get an object stream instead by setting opts.objectMode to true.

tap stream reporter

You can create your own custom test reporter using this createStream() api:

var test = require('tape');
var path = require('path');

test.createStream().pipe(process.stdout);

process.argv.slice(2).forEach(function (file) {
    require(path.resolve(file));
});

You could substitute process.stdout for whatever other output stream you want, like a network connection or a file.

Pass in test files to run as arguments:

$ node tap.js test/x.js test/y.js
TAP version 13
# (anonymous)
not ok 1 should be equal
  ---
    operator: equal
    expected: "boop"
    actual:   "beep"
  ...
# (anonymous)
ok 2 should be equal
ok 3 (unnamed assert)
# wheee
ok 4 (unnamed assert)

1..4
# tests 4
# pass  3
# fail  1

object stream reporter

Here's how you can render an object stream instead of TAP:

var test = require('tape');
var path = require('path');

test.createStream({ objectMode: true }).on('data', function (row) {
    console.log(JSON.stringify(row))
});

process.argv.slice(2).forEach(function (file) {
    require(path.resolve(file));
});

The output for this runner is:

$ node object.js test/x.js test/y.js
{"type":"test","name":"(anonymous)","id":0}
{"id":0,"ok":false,"name":"should be equal","operator":"equal","actual":"beep","expected":"boop","error":{},"test":0,"type":"assert"}
{"type":"end","test":0}
{"type":"test","name":"(anonymous)","id":1}
{"id":0,"ok":true,"name":"should be equal","operator":"equal","actual":2,"expected":2,"test":1,"type":"assert"}
{"id":1,"ok":true,"name":"(unnamed assert)","operator":"ok","actual":true,"expected":true,"test":1,"type":"assert"}
{"type":"end","test":1}
{"type":"test","name":"wheee","id":2}
{"id":0,"ok":true,"name":"(unnamed assert)","operator":"ok","actual":true,"expected":true,"test":2,"type":"assert"}
{"type":"end","test":2}

install

With npm do:

npm install tape --save-dev

license

MIT

Project Statistics

Sourcerank 21
Repository Size 683 KB
Stars 5,311
Forks 300
Watchers 72
Open issues 39
Dependencies 21
Contributors 88
Tags 199
Created
Last updated
Last pushed

Top Contributors See all

James Halliday Jordan Harband Jake Verbaten Nelson Stephen Sugden Marcus Berner Marcus Stade Andrew Fong isaacs Domenic Denicola Fredrik Norén nhamer Nicola Girardi Ram Josh Duff Miklós Antal Brad Dunbar Joe Lapp Kohei Asai Joshua T Corbin

Packages Referencing this Repo

tape
tap-producing test harness for node and browsers
Latest release 5.0.1 - Updated - 5.31K stars
org.webjars.npm:tape
WebJar for tape
Latest release 5.0.0-next.5 - Updated - 5.31K stars
@pre-bundled/tape
tap-producing test harness for node and browsers
Latest release 5.0.0 - Updated - 5.31K stars
@kepi/tape-ignore
tap-producing test harness for node and browsers
Latest release 4.10.1 - Updated - 5.31K stars

Recent Tags See all

v5.0.1 May 25, 2020
v4.13.3 May 24, 2020
v5.0.0 April 24, 2020
v5.0.0-next.5 March 02, 2020
v4.13.2 March 02, 2020
v5.0.0-next.4 January 19, 2020
v4.13.1 January 09, 2020
v5.0.0-next.3 January 09, 2020
v5.0.0-next.2 January 08, 2020
v4.13.0 January 08, 2020
v5.0.0-next.1 January 01, 2020
v4.12.1 December 24, 2019
v5.0.0-next.0 December 21, 2019
v4.12.0 December 16, 2019
v4.11.0 June 29, 2019

Interesting Forks See all

nelsonic/tape
tap-producing test harness for node and browsers
JavaScript - Other - Last pushed - 1 stars
CNXTEoE/tape
tap-producing test harness for node and browsers
JavaScript - Updated - 1 stars
jprichardson/tape
tap-producing test harness for node and browsers
JavaScript - Last pushed - 1 stars
MignonCornet/tape
tap-producing test harness for node and browsers
JavaScript - Updated - 1 stars
Raynos/tape
tap-producing test harness for node and browsers
JavaScript - MIT - Last pushed - 1 stars

Something wrong with this page? Make a suggestion

Last synced: 2019-12-21 07:03:23 UTC

Login to resync this repository