tap-producing test harness for node and browsers
TAP-producing test harness for node and browsers
[![github actions][actions-image]][actions-url] [![coverage][codecov-image]][codecov-url] [![License][license-image]][license-url] [![Downloads][downloads-image]][downloads-url]
[![npm badge][npm-badge-png]][package-url]
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);
});
test('test using promises', async function (t) {
const result = await someAsyncThing();
t.ok(result);
});
$ node example/timing.js
TAP version 13
# timing test
ok 1 should be strictly equal
not ok 2 should be strictly equal
---
operator: equal
expected: 100
actual: 107
...
1..2
# tests 2
# pass 1
# fail 1
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"
If you want tape to error when no files are found, pass --strict:
$ tape --strict 'tests/**/*.js'
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.
tape maintains a fairly minimal core. Additional features are usually added by using another module alongside tape.
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!
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.
While running tests, top-level configurations can be passed via the command line to specify desired behavior.
Available configurations are listed below:
Alias: -r
This is used to load modules before running tests and is explained extensively in the preloading modules section.
Alias: -i
This flag is used when tests from certain folders and/or files are not intended to be run.
The argument is a path to a file that contains the patterns to be ignored.
It defaults to .gitignore when passed with no argument.
tape -i .ignore '**/*.js'
An error is thrown if the specified file passed as argument does not exist.
Same functionality as --ignore, but passing the pattern directly instead of an ignore file.
If both --ignore and --ignore-pattern are given, the --ignore-pattern argument is appended to the content of the ignore file.
tape --ignore-pattern 'integration_tests/**/*.js' '**/*.js'
This is particularly useful in a CI environment where an only test is not supposed to go unnoticed.
By passing the --no-only flag, any existing only test causes tests to fail.
tape --no-only **/*.js
Alternatively, the environment variable NODE_TAPE_NO_ONLY_TEST can be set to true to achieve the same behavior; the command-line flag takes precedence.
The assertion methods in tape are heavily influenced or copied from the methods in node-tap.
var test = require('tape')
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:
true (unless the NODE_TAPE_STRICT_TIMEOUT environment variable is set to a non-empty value). When false, a test that blocks the event loop past its timeout is failed once it ends, rather than being allowed to pass. See test.timeoutAfter.NODE_TAPE_OBJECT_PRINT_DEPTH can set the desired default depth for all tests; locally-set values will take precedence.If you forget to t.plan() out how many assertions you are going to run and you don't call t.end() explicitly, or return a Promise that eventually settles, your test will hang.
If cb returns a Promise, it will be implicitly awaited. If that promise rejects, the test will be failed; if it fulfills, the test will end. Explicitly calling t.end() while also returning a Promise that fulfills is an error.
Generate a new test that will be skipped over.
The onFinish hook will get invoked when ALL tape tests have finished right before tape is about to print the test summary.
fn is called with no arguments, and its return value is ignored.
The onFailure hook will get invoked whenever any tape tests has failed.
fn is called with no arguments, and its return value is ignored.
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.
Declare the end of a test explicitly. If err is passed in t.end will assert that it is falsy.
Do not call t.end() if your test callback returns a Promise.
Register a callback to run after the individual test has completed. Multiple registered teardown callbacks will run in order. Useful for undoing side effects, closing network connections, etc.
Generate a failing assertion with a message msg.
Generate a passing assertion with a message msg.
Automatically timeout the test after X ms.
JavaScript is single-threaded, so a test that blocks the event loop (for example, with a long synchronous loop) can not be interrupted mid-run. By default (ignoreSyncTimeout is true) such a test is allowed to run to completion and pass, even if it runs past the timeout. Setting the ignoreSyncTimeout option to false - or the NODE_TAPE_STRICT_TIMEOUT environment variable (when set to a non-empty value), which flips the default for all tests - instead fails the test once it ends, if it took at least X ms. A per-test ignoreSyncTimeout value takes precedence over the environment variable.
Generate an assertion that will be skipped over.
Assert that value is truthy with an optional description of the assertion msg.
Aliases: t.true(), t.assert()
Assert that value is falsy with an optional description of the assertion msg.
Aliases: t.false(), t.notok()
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()
Assert that Object.is(actual, expected) with an optional description of the assertion msg.
Aliases: t.equals(), t.isEqual(), t.strictEqual(), t.strictEquals(), t.is()
Assert that !Object.is(actual, expected) with an optional description of the assertion msg.
Aliases: t.notEquals(), t.isNotEqual(), t.doesNotEqual(), t.isInequal(), t.notStrictEqual(), t.notStrictEquals(), t.isNot(), t.not()
Assert that actual == expected with an optional description of the assertion msg.
Aliases: t.looseEquals()
Assert that actual != expected with an optional description of the assertion msg.
Aliases: t.notLooseEquals()
Assert that actual and expected have the same structure and nested values using node's deepEqual() algorithm with strict comparisons (===) on le
No open issues yet, or sync has not completed.