tape-six

tape-six is a TAP-based library for unit tests. It is written in the modern JavaScript for the modern JavaScript and works in Node, Deno, Bun and browsers.

Why tape-six? It was supposed to be named tape6 but npm does not allow names "similar" to existing packages. Instead of eliminating name-squatting they force to use unintuitive and unmemorable names. That's why all internal names, environment variables, and public names still use tape6.

Rationale

Why another library? Working on projects written in modern JS (with modules) I found several problems with existing unit test libraries:

• In my opinion unit test files should be directly executable with node, deno, bun, browsers (with a trivial HTML file to load a test file) without a need for a special test runner utility, which wraps and changes my beautiful code.
  • Debugging my tests should be trivial. It should not be different from debugging any regular file.
• The test harness should not obfuscate code nor include hundreds of other packages.
  • I want to debug my code, not dependencies I've never heard about.
  • I want to see where a problem happens, not some guts of a test harness.
• Tests should work with ES modules natively.
  • What if I want to debug some CommonJS code with Node? Fret not! Modules can import CommonJS files directly. But not the other way around (yet). And it helps to test how module users can use your beautiful CommonJS package.
• The DX in browsers are usually abysmal.
  • Both console-based debugging and a UI to navigate results should be properly supported.

Docs

The documentation can be found in the wiki. See how it can be used in tests/.

The whole API is based on two objects: test and Tester.

test

test is the entry point to the test suite:

import test from 'tape-six';

This function registers a test suite. Available options:

• async test(name, options, testFn) — registers a test suite to be executed asynchronously. The returned promise is resolved when the test suite is finished.
  • In most cases no need to wait for the returned promise.
  • The test function has the following signature: testFn(tester)
• test.skip(name, options, testFn) — registers a test suite to be skipped.
  • It is used to mark a test suite to be skipped. It will not be executed.
• test.todo(name, options, testFn) — registers a test suite that is marked as work in progress.
  • Tests in this suite will be executed, errors will be reported but not counted as failures.
  • It is used to mark tests for incomplete features under development.
• test.asPromise(name, options, testPromiseFn) — registers a test suite to be executed asynchronously using the callback-style API to notify that the test suite is finished.
  • The test function has a different signature: testPromiseFn(tester, resolve, reject).

The arguments mentioned above are:

• name — the optional name of the test suite. If not provided, it will be set to the name of the test function or '(anonymous)'.
• options — the optional options object. Available options:
  • skip — if true, the test suite will be skipped.
  • todo — if true, the test suite will be marked as work in progress.
  • name — the optional name of the test suite. If not provided, it will be set to the name of the test function or '(anonymous)'.
    • Can be overridden by the name argument.
  • testFn — the optional test function to be executed.
    • Can be overridden by the testFn argument.
  • timeout — the optional timeout in milliseconds. It is used for asynchronous tests.
    • If the timeout is exceeded, the test suite will be marked as failed.
    • Important: JavaScript does not provide a generic way to cancel asynchronous operations. When the timeout is exceeded, tape6 will stop waiting for the test to finish, but it will continue running in the background.
    • The default: no timeout.
  • testFn — the test function to be executed. It will be called with the tester object. The result will be ignored.
    • This function can be an asynchronous one or return a promise.
  • testPromiseFn — the test function to be executed. It will be called with the tester object and two callbacks: resolve and reject modeled on the Promise API.

Given all that test and its helpers can be called like this:

test(name, options, testFn);
test(name, testFn);
test(testFn);
test(name, options);
test(options, testFn);
test(options);

// examples:
test('foo', t => {
  t.pass();
});
test('bar', async t => {
  t.fail();
});
test(function baz(t) {
  t.ok(1 < 2);
});
test({
  name: 'qux',
  todo: true,
  testFn: t => {
    t.ok(1 < 2);
  }
});

Tester

Tester helps to do asserts and provides an interface between a test suite and the test harness. The following methods are available (all msg arguments are optional):

• Asserts:
  • pass(msg) — asserts that the test passed.
  • fail(msg) — asserts that the test failed.
  • ok(val, msg) — asserts that val is truthy.
    • true() — an alias of ok().
    • assert() — an alias of ok().
  • notOk(val, msg) — asserts that val is falsy.
    • false() — an alias of notOk().
    • notok() — an alias of notOk().
  • error(err, msg) — asserts that err is falsy.
    • ifError() — an alias of error().
    • ifErr() — an alias of error().
    • iferror() — an alias of error().
  • strictEqual(a, b, msg) — asserts that a and b are strictly equal.
    • Strict equality is defined as a === b.
    • is() — an alias of strictEqual().
    • equal() — an alias of strictEqual().
    • isEqual() — an alias of strictEqual().
    • equals() — an alias of strictEqual().
    • strictEquals() — an alias of strictEqual().
  • notStrictEqual(a, b, msg) — asserts that a and b are not strictly equal.
    • not() — an alias of notStrictEqual().
    • notEqual() — an alias of notStrictEqual().
    • notEquals() — an alias of notStrictEqual().
    • notStrictEquals() — an alias of notStrictEqual().
    • doesNotEqual() — an alias of notStrictEqual().
    • isUnequal() — an alias of notStrictEqual().
  • looseEqual(a, b, msg) — asserts that a and b are loosely equal.
    • Loose equality is defined as a == b.
    • looseEquals() — an alias of looseEqual().
  • notLooseEqual(a, b, msg) — asserts that a and b are not loosely equal.
    • notLooseEquals() — an alias of notLooseEqual().
  • deepEqual(a, b, msg) — asserts that a and b are deeply equal.
    • Individual components of a and b are compared recursively using the strict equality.
    • See deep6's equal() for details.
    • same() — an alias of deepEqual().
    • deepEquals() — an alias of deepEqual().
    • isEquivalent() — an alias of deepEqual().
  • notDeepEqual(a, b, msg) — asserts that a and b are not deeply equal.
    • notSame() — an alias of notDeepEqual().
    • notDeepEquals() — an alias of notDeepEqual().
    • notEquivalent() — an alias of notDeepEqual().
    • notDeeply() — an alias of notDeepEqual().
    • isNotDeepEqual() — an alias of notDeepEqual().
    • isNotEquivalent() — an alias of notDeepEqual().
  • deepLooseEqual(a, b, msg) — asserts that a and b are deeply loosely equal.
    • Individual components of a and b are compared recursively using the loose equality.
  • notDeepLooseEqual(a, b, msg) — asserts that a and b are not deeply loosely equal.
  • throws(fn, msg) — asserts that fn throws.
    • fn is called with no arguments in the global context.
  • doesNotThrow(fn, msg) — asserts that fn does not throw.
  • matchString(string, regexp, msg) — asserts that string matches regexp.
  • doesNotMatchString(string, regexp, msg) — asserts that string does not match regexp.
  • match(a, b, msg) — asserts that a matches b.
    • See deep6's match() for details.
  • doesNotMatch(a, b, msg) — asserts that a does not match b.
  • rejects(promise, msg) — asserts that promise rejects.
    • This is an asynchronous method. It is likely to be waited for.
    • doesNotResolve() — an alias of rejects().
  • resolves(promise, msg) — asserts that promise resolves.
    • This is an asynchronous method. It is likely to be waited for.
    • doesNotReject() — an alias of resolves().
• Embedded test suites (all of them are asynchronous and should be waited for):
  • test(name, options, testFn) — runs a test suite asynchronously. See test() above.
  • skip(name, options, testFn) — skips a test suite asynchronously. See test.skip() above.
  • todo(name, options, testFn) — runs a provisional test suite asynchronously. See test.todo() above.
  • asPromise(name, options, testPromiseFn) — runs a test suite asynchronously. See test.asPromise() above.
• Miscellaneous:
  • any — returns the any object. It can be used in deep equivalency asserts to match any value. See deep6's any for details.
  • plan(n) — sets the number of tests in the test suite. Rarely used.
  • comment(msg) — sends a comment to the test harness. Rarely used.
  • skipTest(...args, msg) — skips the current test yet sends a message to the test harness.
  • bailOut(msg) — stops the test suite and sends a message to the test harness.

In all cases, the msg message is optional. If it is not provided, some suitable generic message will be used.

Example:

test('Sample test', async t => {
  const result = await getFromDb({first: 'Bob', last: 'Smith'});
  t.equal(result.position, 'chief bozo', 'the position is correct');
  t.ok(result.manager, 'the manager exists');

  const manager = await getFromDb(result.manager);
  t.ok(manager, 'the manager is retrieved');
  t.equal(manager.first, 'Jane', 'the manager is Jane');
  t.deepEqual(manager.employees, ['Bob Smith'], 'Jane manages only Bob Smith');
});

Running tests

It is super easy to run tests:

1. Install the tape-six package: npm i -D tape-six
2. Write a test. For example, you named it test.js.
3. Run the test: node test.js
   1. Or: bun run test.js
   2. Or: deno run -A test.js
   3. Or you can run them in a browser!
4. Profit!

If you have a lot of tests, you can organize them using multiple files and directories. tape-six provides multiple test runners that can run them in different environments.

Configuring test runners

See set-up tests for details.

Command-line utilities

• tape6 — the main utility of the package to run tests in different environments.
• tape6-server — a custom web server with a web application that helps running tests in browsers.

Release notes

The most recent releases:

• 1.0.2 Bugfix for Deno using the JSONL reporter.
• 1.0.1 Technical release: added more links.
• 1.0.0 The first official release.
• 0.12.3 Technical release: exposed internal classes for external utilities.
• 0.12.2 Fixed a minor serialization issue.
• 0.12.1 Minor Deno-related refactoring, fixed the way tests are triggered.
• 0.12.0 Removed data to avoid serializing non-serializable objects.
• 0.11.0 Minor improvements to the server: temporary redirects, a hyperlink to the web app.
• 0.10.0 Refactored test runners, refactored stopping tests on failure, added JSONL reporter, fixed bugs.
• 0.9.6 Updated deps.
• 0.9.5 Updated the lock file.
• 0.9.4 Updated deps. Added test runners for Bun and Deno.
• 0.9.3 Made TTY reporter work with non-TTY streams.
• 0.9.2 Fixed Windows runner.
• 0.9.1 More updates related to renaming tape6 ⇒ tape-six.
• 0.9.0 Initial release.

For more info consult full release notes.