Node TAP 18.7.2

tap CLI

TAP - Test Anything Protocol library for JavaScript#

Usage:

tap [<options>] [<cmd> [<args> ...]]

Short options are parsed gnu-style, so for example -bCRterse would be equivalent to --bail --no-color --reporter=terse

Much more documentation available at: https://www.node-tap.org/

Subcommands#

tap run [test files...]#

(default) Run the files if specified, or search for test files according to the include and exclude glob expressions.

If the first argument to the tap cli is not one of these subcommands, then it will be treated as a test file to run.

tap plugin [add <plugin> | rm <plugin> | list]#

Manage plugins

tap plugin add <plugin>#

Add the specified plugin to the tap project config.

If the plugin is one of tap's builtin plugins that was previously disabled, then it will simply be re-enabled.

If the plugin is not a module on disk, then tap will attempt to install the plugin package as a dev dependency by running npm install --save-dev <plugin>.

Specifying a version or range is supported. For example, tap plugin add my-plugin@1.x will try to install a version that satisfies the semver range. It will be saved in the configuration without the version. If the plugin is updated in node_modules, it may require running tap build, if the types or interfaces change between versions.

tap plugin rm <plugin>#

Remove the specified plugin.

If the plugin is one of tap's builtin plugins, then it will be disabled by adding !<plugin> to the plugin tap config.

Node-tap will not automatically uninstall plugin dependencies when removed.

tap plugin list#

List the plugins in use

tap report#

Print a coverage report using the coverage-report config.

Coverage reporters can also be specified as positional arguments, for example tap report html.

tap replay#

Replay the results of the last test run, optionally specifying reporter, test files to filter, and so on.

This does not run the actual tests again, it just pipes their TAP standard output through the reporter, but it can be useful to view the results of the previous test run.

tap repl#

Open a REPL for interacting with the test suite. This can be used to watch files for changes, print coverage reports, or interact with the saved process info of past runs.

Run tap repl help for a list of REPL commands, or run help in the REPL itself.

tap build#

Rebuild tap with the configured plugins. This is done automatically when running tests if the set of plugins does not match what tap was previously built with.

tap version#

Print the version of tap in use

This is also run if the -v --version flag is set

tap versions#

Print the versions of tap and its components and plugins.

This is also run if the -V --versions flag is set

tap config [get | list | dump | set | edit]#

Print or edit configuration in YAML format.

tap config get <key> [<key> ...]#

Print the resolved values of the keys specified.

If any keys are undefined (because they have no default and are not set), they are omitted.

tap config list [<key> ...]#

Print the configuration from the config file, and from all environment variables, command-line options, and defaults.

Items are sorted, and keys are highlighted.

If one or more key names are provided, then the results will be filtered to only show those configuration keys.

tap config dump#

Current effect configuration is dumped in YAML format, without any highlighting or sorting.

tap config set <key=val> [<key=val> ...]#

Set the specified keys and values.

Boolean values must be set to literal 'true' or 'false'.

Array values can be set multiple times.

To delete a value, set it with key= (ie, provide an empty value). This can be used for example to clear out an array field and then fill it, rather than appending to it.

tap config edit#

Open the tap configuration in YAML format in your editor. Upon saving and quitting, if the configuration has changed, and is valid, then it will be written to the relevant config file. That is, if your tap configs are coming from a "tap" section in package.json, then they'll be written there, in JSON format. If they're coming from a .taprc file in the project root, then they'll be written there in YAML format.

All comments and empty lines in the file will be removed.

tap list#

Print the test files that will be run, according to the configuration and positional arguments.

tap debug#

Output various debugging information, useful when posting issues on https://github.com/tapjs/tapjs/issues.

tap help#

Print usage information

This is also run if the -h --help flag is set.

Configuration#

If a TAP_RCFILE value is set in the process environment, then that will be the initial location that tap looks for configuration values.

If that's not set, then tap will look for configuration data first in a .taprc file in the project root, and then in the "tap" object in the project package.json file. ('Project root' means the nearest folder at or above the current working directory containing package.json, .taprc, or .git.)

The config object may set any of the following fields, as well as the special "extends" field, which may specify either a package name or file name, relative to the config file that references it.

If the "extends" field resolves to a file on disk, then that will be read as the base configuration object. (It may also extend yet another config file, and so on.)

If the "extends" field specifies a package name, then it must be resolveable in the node_modules folder of the file extending it. That package must contain either a .taprc file, or a package.json file with a "tap" object.

To see the format used in a .taprc file, run the tap dump-config command with the desired options specified on the command line.

Additionally, all config options that are modified from their defaults will be set in the environment with the TAP_ prefix, and will be read from the environment if so specified. For example, specifying --omit-version on the command line, or omit-version: true in a .taprc file, will set TAP_OMIT_VERSION=1 in the environment.

Environment and CLI options take priority over any config files.

Basic Options#

--plugin=<module>#

Configure the tap Test class with the specified plugin.

Typically this is set in a .taprc file, not on the command line, and can be managed using the tap plugin <add|rm> command.

If the set of plugins does not match that which tap was built with previously, then it will rebuild the Test class prior to running tests.

To exclude a plugin which has been previously included (perhaps by being part of tap's default set), add it to this list prefixed by a ! character.

The default plugin set that ships with tap is:

Even if excluded, the runner will use some of these plugins in its own operation.

Can be set multiple times

-R<reporter> --reporter=<reporter>#

Use the specified reporter. Defaults to base when colors are in use, or tap when colors are disabled.

In addition to the built-in reporters provided by the @tapjs/reporter module, the reporter option can also specify a command-line program or a module to load via import().

Command-line programs receive the raw TAP output on their stdin.

Modules loaded via import() must default export a writable stream class, React function component, or a React.Component subclass.

Writable streams are instantiated and piped into.

React components are rendered using Ink, with tap={tap} and config={loadedConfig} as their properties.

Built-in test reporters:

-f<file> --reporter-file=<file>#

Write the test report to the specified file, instead of stdout. Useful for reports such as junit, json, etc.

To save the raw TAP data to a file, the --output-file or --output-dir options are usually more appropriate.

If TAP=1 is set in the environment, then raw TAP output is always written to stdout, because this is how test files communicate with the runner.

-r<arg> --reporter-arg=<arg>#

Args to pass to command-line reporters. Ignored when using built-in reporters or module reporters.

Can be set multiple times

--coverage-report=<type>#

Output coverage information using the specified istanbul coverage reporter type.

Default is text.

If html or lcov is used, then the HTML report will be opened in a web browser after running.

This can be run on its own at any time after a test run that included coverage.

Built-in coverage reporters:

Can be set multiple times

--show-full-coverage#

Show the 100 lines in the default text coverage reporter for every file that has full coverage. Defaults to false for all commands other than tap report. Has no effect on any other coverage report styles.

If not set, and the test suite has full coverage, then no text coverage report will be generated when running tests. It can be assumed in this case that no news is good news, and a zero-exit test process means full coverage was generated. When generating any other test report styles, files with full coverage are still reported.

When running tap report, this defaults to true, because presumably you do want to see something if explicitly requesting a coverage report, even if it's just a list of green 100s.

When running tap report --no-show-full-coverage, with this config explicitly set false, it will omit the default text report on full coverage, and behave like running tap report none (ie, print nothing).

When running tap report text --no-show-full-coverage, explicitly requesting a text report and also explicitly requesting that full coverage text report not be shown, then a summary report will be printed instead of the full text report.

--coverage-map=<module>#

Provide a path to a node module (esm or cjs) that default exports a single function. That function takes a test file as an argument, and returns an array of files to instrument with coverage when that file is run.

This is useful in cases where a unit test should cover a single portion of the system under test, or where you wish to avoid tracking "accidental coverage" by integration tests.

Return null to not cover any files by this test.

Return an empty array [] to cover the set that would be pulled in by default. Ie, returning [] is equivalent to not using a coverage map at all.

--allow-empty-coverage#

Suppress the error exit if the test run produces no coverage whatsoever.

The # No coverage generated message will still be printed.

If coverage is generated, but incomplete, then the process will exit in error, unless allow-incomplete-coverage is also set.

WARNING: tests that do not produce coverage are untrustworthy. This should only be used when coverage is being generated and tracked by some other mechanism.

--allow-incomplete-coverage#

Suppress the error exit if the test run produces incomplete coverage information.

The coverage report showing missing coverage will still be generated.

If no coverage is generated, then the process will exit in error, unless allow-empty-coverage is also set.

WARNING: tests that produce incomplete coverage are untrustworthy. This should only be used when coverage is being generated and tracked by some other mechanism.

--disable-coverage#

Do not generate code coverage information for the test run.

This will always result in a # No coverage generated message being printed. If this flag is set, then --allow-empty-coverage will default to true, because we do not expect to get any coverage.

WARNING: tests that do not produce coverage are untrustworthy. This should only be used when coverage is being generated and tracked by some other mechanism.

-b --bail#

Bail out on first failure

-B --no-bail#

Do not bail out on first failure (default)

--comments#

Print all tap comments to process.stderr

--passes#

Include passing tests in assertion summary reports.

Has no effect on TAP output if a reporter is not used, but will cause passing assertions to be included in the Test.lists collection by default.

Note: this usually makes test output QUITE noisy.

--fail-todo#

Treat # TODO tests as failures

--fail-skip#

Treat # SKIP assertions as failures

-c --color#

Use colors (Default for TTY)

-C --no-color#

Do not use colors (Default for non-TTY)

-n --changed#

Only run tests for files that have changed since the last run.

If no prior test run data exists, then all default files are run, as if --changed was not specified.

-s<file> --save=<file>#

If exists, then it should be a line- delimited list of test files to run. If is not present, then all command-line positional arguments are run.

After the set of test files are run, any failed test files are written back to the save file.

This way, repeated runs with -s will re-run failures until all the failures are passing, and then once again run all tests.

Its a good idea to .gitignore the file used for this purpose, as it will churn a lot.

--diag#

Set to show diagnostics by default for both passing and failing tests. If not set, then diagnostics are printed by default for failing tests, and not for passing tests.

--no-diag#

Do not show diagnostics by default for passing or failing tests. If not set, then diagnostics are printed by default for failing tests, and not for passing tests.

-t<n> --timeout=<n>#

Time out test files after seconds. Defaults to 30. Setting to 0 allows tests to run forever.

When a test process calls t.setTimeout(n) on the top-level tap object, it also updates this value for that specific process.

--files=<filename>#

Alternative way to specify test set rather than using positional arguments. Supported as an option so that test file arguments can be specified in .taprc and package.json files.

Can be set multiple times

Test Running Options#

Tap runs multiple test files in parallel. This generally results in a speedier test run, but can also cause problems if your test files are not designed to be independent from one another.

The before module, if specified, will always run before any tests, and the after module will be loaded after the entire test run is complete.

-j<n> --jobs=<n>#

Run up to n test files in parallel.

By default, this will be set based on the number of CPUs on the system.

Set --jobs=1 to disable parallelization entirely.

--before=<module>#

A node program to be run before test files are executed.

Exiting with a non-zero status code or a signal will fail the test run and exit the process in error.

Relative before paths are resolved against the project config root, even if specified on the cli.

--after=<module>#

A node program to be executed after tests are finished.

This will be run even if a test in the series fails with a bailout, but it will not be run if a --before script fails.

Exiting with a non-zero status code or a signal will fail the test run and exit the process in error.

Relative after paths are resolved against the project config root, even if specified on the cli.

-o<filename> --output-file=<filename>#

Send the raw TAP output to the specified file. Reporter output will still be printed to stdout, but the file will contain the raw TAP for later replay or analysis.

-d<dir> --output-dir=<dir>#

Send the raw TAP output to the specified directory. A separate .tap file will be created for each test file that is run. Reporter output will still be printed to stdout, but the files will contain the raw TAP for later replay or analysis.

Files will be created to match the folder structure and filenames of test files run, but with .tap appended to the filenames.

--include=<pattern>#

A glob expression pattern indicating tests to run if no positional arguments are provided to the tap run command.

The special token __EXTENSIONS__ will expand to the list of known file type extensions that tap knows how to process. When the @tapjs/typescript plugin is loaded (default), this will be:

Without the typescript plugin, this will be just the file extensions known to Node:

By default, tap will search for all files ending in these known file type extensions in the following ways:

No files excluded by the exclude option will be loaded, meaning that dependencies, build artifacts in dist, test fixtures, snapshots, and source control metadata will be ignored.

The glob patterns are expanded without the dot option, so any file starting with a . will be ignored.

Can be set multiple times

--exclude=<pattern>#

A glob pattern indicating which filenames should NEVER be run as tests. This overrides the include option.

Defaults to excluding any folders named dist, fixture, or fixtures.

Note: folders named tap-snapshots, node_modules, or .git are ALWAYS excluded from the default test file set. If you wish to run tests in these folders, then name the test files on the command line as positional arguments.

Can be set multiple times

--serial=<dir>#

Mark all test files anywhere within the specified directory as serial tests, not to be run in parallel with any other test files.

Can be set multiple times

--test-arg=<arg>#

Pass an argument to test files spawned by the tap command line executable. This can be specified multiple times to pass multiple args to test scripts.

Can be set multiple times

--test-env=<key=value>#

Pass a key=value (ie, --test-env=key=value) to set an environment variable in the process where tests are run.

If a value is not provided, such as --test-env=key, then the key is ensured to not be set in the environment. To set a key to the empty string, use --test-env=key=

Can be set multiple times

--node-arg=<arg>#

Pass an argument to Node binary in all child processes. Run node --help to see a list of all relevant arguments. This can be specified multiple times to pass multiple args to Node.

Can be set multiple times

Other Options#

--debug#

Turn on debug mode (very noisy)

--omit-version#

Do not print the TAP version 14 line. (This may be needed for compapatibility with some older TAP parsers.)

--omit-whitespace#

Prune empty lines out of the output from child tests

--no-omit-whitespace#

Preserve extra empty lines in the output.

-V --versions#

Show the version of tap and relevant tap libraries in use.

-v --version#

Show the version of this program.

-h --help#

show this help banner

From plugin: @tapjs/filter#

-O --only#

Only run tests with {only: true} option, or created with the t.only(...) function.

-g<pattern> --grep=<pattern>#

Only run subtests tests matching the specified pattern.

Patterns are matched against top-level subtests in each file. To filter tests at subsequent levels, specify this option multiple times.

To specify regular expression flags, format pattern like a JavaScript RegExp literal. For example: /xyz/i for case-insensitive matching.

Can be set multiple times

-i --invert#

Invert the matches to --grep patterns. (Like grep -v)

-I --no-invert#

Do not invert the matches to --grep patterns. (default)

--filter-quietly#

Do not apply a skip message to tests filtered using --grep and --only.

Defaults to true if --fail-skip is set.

--no-filter-quietly#

Always set a skip message on filtered tests, even if --fail-skip is enabled.

From plugin: @tapjs/fixture#

-F --save-fixture#

Do not clean up fixtures created with t.testdir()

From plugin: @tapjs/snapshot#

-S --snapshot#

Generate snapshot files for t.matchSnapshot() assertions.

Defaults to true if the TAP_SNAPSHOT environment variable is set to 1, or if the npm_lifecycle_event environment variable is set to either snap or snapshot.

That is, if you put "scripts": { "snap": "tap" } in your package.json file, then npm run snap will generate snapshots.

--snapshot-clean-cwd#

Automatically clean the current working directory out of snapshot data, replacing it with a token.

This helps prevent frustrating "works on my machine" when tests capture an error message or file path, but then fail when run on any other system, and so is enabled by default.

--no-snapshot-clean-cwd#

Do not clean the current working directory out of snapshots

May be required when using fixtures or other snapshot data sources that intentionally include strings which happen to match the current working directory.

Not recommended! It's better to leave this protection on, and edit your fixtures so that they do not include the cwd.

From plugin: @tapjs/typescript#

--typecheck#

Type-check test files, in addition to transpiling and running them.

This defaults to false, even though type checking your tests is generally a good idea. Unfortunately, it is also often considerably slower, adding as much as 500-750ms to each test suite file, which can be painful if you have a lot of tests. In large project folders, the effect can be even more pronounced.

It is a good idea to enable this in CI environments, where test speed is less of an ergonomic drawback.

The "skipLibCheck": true" option in tsconfig will also speed things up a bit, at the expense of some type safety.

Note that even if you pre-compile your tests, they will still be subject to type checking if "allowJs": true is set in your tsconfig.

--tsconfig=<tsconfig>#

Path to the tsconfig.json file containing project settings provided to ts-node when running tests.

Similar to the --project option to ts-node. Sets the TS_NODE_PROJECT environment variable.

If this is a relative directory, then it is resolved against the project root directory.

Defaults to the first of these files that are found in the project root directory: