tap

library0.2jsnpmunverified

TAP (Test-Anything-Protocol) is a robust and opinionated test framework for Node.js, currently in version 21.7.1. It provides a comprehensive command-line test runner and a JavaScript/TypeScript framework for writing tests that output in the TAP format. A key differentiator is its philosophy of treating test files as "normal" programs, running each test in its own process to prevent state leakage and inter-test dependencies. Since version 18, `tap` has been entirely rewritten in TypeScript, offering first-class support for ESM, CommonJS, and TypeScript out-of-the-box, including rich, machine-generated type definitions for an enhanced developer experience with editor auto-completion. It features built-in test coverage (powered by `c8`), various reporter formats, and an extensive API leveraging a plugin-based architecture for core functionalities like assertions and mocking. The project maintains an active release cadence with frequent updates.

testing

npm install tap

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TAP

tap

testingjavascriptv0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

tap

✓ import tap from 'tap'

✗ const tap = require('tap')

While CommonJS `require('tap')` still works for basic usage, ESM `import tap from 'tap'` is the idiomatic way since v18. Older Node versions or incorrect `package.json` configuration might lead to module resolution errors.

test

✓ import { test } from 'tap'

✗ import { tap } from 'tap'

The `test` function is a named export for convenience, allowing direct access to the primary test definition function without needing the default `tap` object. The main `tap` object itself is the default export.

Test

✓ import type { Test } from 'tap'

✗ import { Test } from 'tap'

This imports the TypeScript type for the `t` object passed to test callbacks. It should be imported as a type, not a runtime value. The `Test` class is what your test programs interact with and is the base for the default `tap` export.

Demonstrates basic synchronous and asynchronous tests, including assertions, type usage for the 't' object, and how to skip tests.

import tap from 'tap'; import type { Test } from 'tap'; interface MyApiResult { data: string; status: number; } async function fetchData(): Promise<MyApiResult> { // Simulate an API call return new Promise(resolve => { setTimeout(() => { resolve({ data: 'Hello TAP!', status: 200 }); }, 50); }); } tap.test('Basic assertions and async test', async (t: Test) => { t.plan(3); // Declare the number of assertions expected t.ok(true, 'should be truthy'); t.equal(1 + 1, 2, 'addition works'); const result = await fetchData(); t.deepEqual(result, { data: 'Hello TAP!', status: 200 }, 'async data matches expected structure'); }); tap.test('Skipping a test', (t: Test) => { t.skip('This test is intentionally skipped for now'); t.end(); // Must call t.end() for non-async tests unless t.plan() is used. }); tap.test('Synchronous operations', (t: Test) => { const arr = [1, 2, 3]; t.notHas(arr, 4, 'array should not contain 4'); t.throws(() => { throw new Error('Expected error'); }, 'Expected error was thrown'); t.end(); });

tap --version

Debug

Known issues

breakingNode.js version 20 or >=22 is now required. Older Node.js versions (e.g., Node.js 18 or 16) are no longer supported and will cause `tap` to fail at runtime.

fix

Upgrade your Node.js runtime to version 20 or 22 (LTS versions are recommended). Use a Node Version Manager (like nvm) to manage multiple Node.js installations.

affects: >=20.0

breakingStarting with `tap` v18, the module system was rewritten to be a hybrid ESM/CommonJS package. Projects upgrading from versions prior to v18 might encounter `ERR_REQUIRE_ESM` or similar module resolution errors if they incorrectly mix `require()` with ESM modules.

fix

Ensure consistent module syntax (ESM `import`/`export` or CommonJS `require`/`module.exports`) across your project, especially for files imported by `tap`. For hybrid projects, verify `package.json`'s `type` field and appropriate file extensions (`.mjs`, `.cjs`).

affects: >=18.0

breakingAs of `tap` v18, code coverage is enabled by default, and a 100% coverage threshold is enforced by default. Tests will fail if code is not fully covered or if coverage reports are missing.

fix

Review your test suite to ensure comprehensive code coverage. If 100% coverage is not feasible or desired for specific files, configure `tap` to adjust thresholds or ignore specific paths in your `.taprc` or `package.json` configuration.

affects: >=18.0

deprecatedAssertion synonyms (e.g., `t.is_not_equal()`) were deprecated in v16 and largely removed in v18. Using these older assertion names will result in errors.

fix

Migrate to the standard assertion methods like `t.notEqual()`, `t.deepEqual()`, etc. Refer to the `tap` API documentation for the current assertion method names.

affects: >=18.0

gotchaWhile `tap` fully supports TypeScript, enabling strict type checking (`typecheck: true`) can significantly increase test run times, especially in large projects with many test files, potentially adding 500-750ms per file.

fix

Enable `typecheck: true` cautiously, perhaps primarily in CI environments. Consider using `skipLibCheck: true` in your `tsconfig.json` for development to speed up local runs, or pre-compile TypeScript tests before running `tap`.

affects: >=18.0

Errors

Common errors & fixes

Error: The current Node.js version (X.Y.Z) is not supported. Please upgrade to Node.js 20 or newer.

The installed Node.js version is below the minimum required by `tap` (20 or 22).

fix

Update your Node.js environment to version 20 or 22. Use `nvm install 20 && nvm use 20` or similar commands for your Node.js version manager.

Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: ... require() of ES modules is not supported.

Attempting to `require()` an ES Module or running a CommonJS file that imports an ESM-only dependency, particularly in projects that haven't fully migrated to ESM or correctly configured hybrid modules.

fix

Ensure `import` statements are used for ES Modules. If running a CommonJS test file, either rewrite it to ESM or ensure all its dependencies are also CommonJS or correctly hybrid-compatible. For `.js` files that are ESM, add `"type": "module"` to your `package.json` or use `.mjs` extension.

AssertionError: Values are not deeply equal

A `t.deepEqual()` (or similar assertion) failed because the actual value does not strictly match the expected value, often due to differences in object structure or primitive values.

fix

Inspect the assertion's `diff` output to understand the discrepancy between the actual and expected values. Adjust either your assertion's expected value or the code under test.

Test suite hangs, never finishes, or passes without running assertions.

An asynchronous test or subtest did not explicitly signal its completion via `t.end()` or by returning a Promise. Or `t.plan()` was used with an incorrect count.

fix

For asynchronous tests, ensure the test callback is an `async` function (which implicitly returns a Promise) or explicitly call `t.end()` when all asynchronous operations are complete. If `t.plan(N)` is used, verify that exactly N assertions are run.

Upgrade

Version history

0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

3 hits · last 30 days

node

Resources

githubhttps://github.com/tapjs/tapjs ↗

packagehttps://www.npmjs.com/package/tap ↗

homepagehttps://node-tap.org ↗