API
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.
Properties#
- bail
- childId
- context
- debug
- diagnostic
- ended
- indent
- omitVersion
- options
- parent
- preserveWhitespace
- readyToProcess
- silent
- strict
- timedOut
- writeSnapshot
Accessors#
Methods#
Assertion Methods#
- doesNotThrow
- emits
- equal
- fail
- has
- hasOwnProp
- hasOwnProps
- hasOwnPropsOnly
- hasProp
- hasProps
- hasStrict
- match
- matchOnly
- matchOnlyStrict
- matchSnapshot
- matchStrict
- not
- notHas
- notHasStrict
- notMatch
- notMatchOnly
- notMatchOnlyStrict
- notMatchStrict
- notOk
- notSame
- ok
- pass
- rejects
- resolveMatch
- resolveMatchSnapshot
- resolves
- same
- strictNotSame
- strictSame
- throws
- type
Plugin Management#
Spies, Mocks, and Fixtures#
- testdirName
- capture
- captureFn
- createMock
- fixture
- intercept
- mock
- mockImport
- mockRequire
- testdir
- unmock