Node TAP 19.0.2


The API presented in test programs is the combination of the base class defined by @tapjs/core and all plugins that are currently loaded.

By default, a set of plugins are included with tap, providing the most common utilities that tests will need to use.

The methods and properties are documented in detail in the generated TypeDocs for the Test class.

See TAP Basics for basic usage information.

Node-tap is optimized for use in a TypeScript-aware editor, such as neovim or VSCode. Intellisense is often much better documentation than this website, because it is more likely to be accurate and you don't have to come here to read it.

Class TAP#

The root test object is the default export of the tap package. It is a plugged-in singleton Test subclass, with all of the same assertions, methods, and so on, plus a few additional features.

These process registrations are triggered when the root test pipes to stdout, or by calling t.register() explicitly. If it never does that, then none of these hooks are applied.

Special Timeout Handling#

If the root test times out, often it's because of something left running that prevented the program from gracefully exiting.

To help debug this situation, active handles and requests are listed. These are often very low-level Node.js objects, so it can be challenging to get any useful clues about what caused the timeout, but tap does its best to help you there.

After printing information about active handles and requests, the process is terminated with a SIGALRM signal if possible, so that the timeout exit is clear to a parent runner process.

Automatically pipe to stdout#

By default, the TAP object will pipe to standard output as soon as it generates some test results. Pretty much anything you do with it will cause it to start piping to stdout immediately.

If the stdout stream emits an EPIPE error, then it is ignored.

If the root test is piped to something other than stdout, then it will not automatically pipe to stdout once it starts generating test results.

Handling Timeout Signals#

When a test subprocess or worker thread times out, the parent test runner sends a an IPC message indicating that it's timed out. If that fails to cause the test to exit, then the process is killed more forcibly. The root TAP object is what listens to this signal.

Exit on bailout#

If the root tap receives a bailout, then it exits the process in error.

Automatically t.end() on Process Exit#

The root TAP object will automatically terminate when the process exits.

If a t.teardown method is attached, then the root TAP test will terminate once it is in an "idle" state. This behavior allows you to have t.teardown() function terminate a server or other long-running job that would otherwise keep the process running indefinitely.

If any tests are still in process, they will be emitted as test failures.

Set Process Exit Code on Failure#

If the test fails, then it sets the process.exitCode to 1.

Class Test#

The Test class is the main interface for using node-tap. It is a Proxy around all of the plugin results and a TestBase base object.




Assertion Methods#

Plugin Management#

Spies, Mocks, and Fixtures#

Subtest Methods#

Test Lifecycle Management#

Test Reflection#