const { jack, num, opt, list, flag, env } = require('jackspeak')
const {cpus} = require('os')
const reporters = [...new Set([
...(require('tap-mocha-reporter').types),
//...(require('treport/types')),
])]
// nyc bundles its deps, pull reporters out of it
const nycReporters = [
'clover',
'cobertura',
'html',
'json',
'json-summary',
'lcov',
'lcovonly',
'none',
'teamcity',
'text',
'text-lcov',
'text-summary',
]
const pkg = require('../package.json')
module.exports = main => jack({
main,
usage: 'tap [options] [<files>]',
help:`
${pkg.name} v${pkg.version} - ${pkg.description}
Executes all the files and interprets their output as TAP
formatted test result data. If no files are specified, then
tap will search for testy-looking files, and run those.
(See '--test-regex' below.)
To parse TAP data from stdin, specify "-" as a filename.
Short options are parsed gnu-style, so for example '-bCRspec' would be
equivalent to '--bail --no-color --reporter=spec'
If the --check-coverage or --coverage-report options are provided
explicitly, and no test files are specified, then a coverage report or
coverage check will be run on the data from the last test run.
Coverage is never enabled for stdin.
Much more documentation available at: https://www.node-tap.org/
`,
}, {
description: 'Basic Options',
reporter: opt({
hint: 'type',
short: 'R',
default: null,
description: `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 treport and tap-mocha-reporter modules, the
reporter option can also specify a command-line
program or a module to load via require().
Command-line programs receive the raw TAP output
on their stdin.
Modules loaded via require() must export either a
writable stream class or a React.Component subclass.
Writable streams are instantiated and piped into.
React components are rendered using Ink, with tap={tap}
as their only property.
Available built-in reporters:
${reporters.join(' ')}`,
}),
'reporter-arg': list({
hint: 'arg',
short: 'r',
description: `Args to pass to command-line reporters. Ignored when using
built-in reporters or module reporters.`,
}),
'save-fixture': flag({
short: 'F',
envDefault: 'TAP_SAVE_FIXTURE',
description: 'Do not clean up fixtures created with t.testdir()',
}),
bail: flag({
short: 'b',
envDefault: 'TAP_BAIL',
description: 'Bail out on first failure',
negate: {
short: 'B',
description: 'Do not bail out on first failure (default)'
}
}),
comments: flag({
description: 'Print all tap comments to process.stderr'
}),
color: flag({
short: 'c',
envDefault: 'TAP_COLORS',
default: process.stdout.isTTY,
description: 'Use colors (Default for TTY)',
negate: {
short: 'C',
description: 'Do not use colors (Default for non-TTY)'
}
}),
snapshot: flag({
short: 'S',
envDefault: 'TAP_SNAPSHOT',
default: /^snap(shot)?$/.test('' + process.env.npm_lifecycle_event),
description: `Set to generate snapshot files for
't.matchSnapshot()' assertions.`,
}),
watch: flag({
short: 'w',
description: `Watch for changes in the test suite or covered program.
Runs the suite normally one time, and from then on,
re-run just the portions of the suite that are required
whenever a file changes.
Opens a REPL to trigger tests and perform various actions.`,
}),
changed: flag({
short: 'n',
description: `Only run tests for files that have changed since the last
run.
This requires coverage to be enabled, because tap uses
NYC's process info tracking to monitor which file is loaded
by which tests.
If no prior test run data exists, then all default files are
run, as if --changed was not specified.`,
}),
'only-changed': flag({
alias: '--changed',
hidden: true,
}),
'onlyChanged': flag({
alias: '--changed',
hidden: true,
}),
save: opt({
short: 's',
hint: 'file',
default: null,
description: `If <file> exists, then it should be a line-
delimited list of test files to run. If
<file> 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<file> 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.`,
}),
only: flag({
short: 'O',
envDefault: 'TAP_ONLY',
description: `Only run tests with {only: true} option,
or created with t.only(...) function.`,
}),
grep: list({
hint: 'pattern',
short: 'g',
envDefault: 'TAP_GREP',
delimiter: '\n',
description: `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.`,
}),
invert: flag({
envDefault: 'TAP_GREP_INVERT',
default: false,
short: 'i',
description: 'Invert the matches to --grep patterns. (Like grep -v)',
negate: { short: 'I' }
}),
timeout: num({
min: 0,
short: 't',
hint: 'n',
envDefault: 'TAP_TIMEOUT',
default: 30,
description: `Time out test files after <n> seconds.
Defaults to 30, or the value of the
TAP_TIMEOUT environment variable.
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.`,
}),
'no-timeout': flag({
short: 'T',
alias: '--timeout=0',
description: 'Do not time out tests. Equivalent to --timeout=0.',
}),
files: list({
description: `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.`
}),
}, {
description: 'Running Parallel Tests',
help: `Tap can run 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.
To designate a set of files as ok to run in parallel, add them
to a folder containing a file named 'tap-parallel-ok'.
To designate a set of files as not ok to run in parallel, add
them to a folder containing a file named 'tap-parallel-not-ok'.
These folders may be nested within one another, and tap will
do the right thing.`,
jobs: num({
short: 'j',
hint: 'n',
min: 1,
default: Math.min(cpus().length, 8),
description: `Run up to <n> test files in parallel.
By default, this will be set to the number of CPUs on
the system.
Set --jobs=1 to disable parallelization entirely.`
}),
'jobs-auto': flag({
short: 'J',
alias: '--jobs=' + cpus().length,
description: `Run test files in parallel (auto calculated)
This is the default as of v13, so this option serves
little purpose except to re-set the parallelization
back to the default if an earlier option (or config file)
set it differently.
`
}),
before: opt({
hint: 'module',
description: `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.`,
}),
after: opt({
hint: 'module',
description: `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.`,
}),
}, {
description: 'Code Coverage Options',
help: `Tap uses the nyc module internally to provide code coverage, so
there is no need to invoke nyc yourself or depend on it
directly unless you want to use it in other scenarios.`,
'100': flag({
alias: [
'--branches=100',
'--lines=100',
'--functions=100',
'--statements=100'
],
description: `Enforce full coverage, 100%.
Sets branches, statements, functions,
and lines to 100.
This is the default. To specify a lower limit
(or no limit) set --lines, --branches, --functions,
or --statements to a lower number than 100, or disable
coverage checking with --no-check-coverage, or disable
coverage entirely with --no-coverage.`,
}),
'coverage-map': opt({
short: 'M',
hint: 'module',
description: `Provide a path to a node module that 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.
Return 'null' to not cover any files by this test.
Return an empty array [] to cover the set that nyc would
pull in by default. Ie, returning [] is equivalent to not
using a coverage map at all.`,
}),
'no-coverage-map': flag({
description: `Do not use a coverage map.
Primarily useful for disabling a coverage-map that is
set in a config file.`,
}),
coverage: flag({
default: true,
short: 'cov',
description: `Capture coverage information using 'nyc'
This is enabled by default.
If a COVERALLS_REPO_TOKEN environment variable is set,
and the 'coveralls' module is installed, then coverage
is sent to the coveralls.io service.
Note that tap does not automatically install coveralls,
it must already be present in your project to use this
feature.`,
negate: {
short: 'no-cov',
description: `Do not capture coverage information.
Note that if nyc is already loaded, then
the coverage info will still be captured.`,
}
}),
'coverage-report': list({
hint: 'type',
description: `Output coverage information using the
specified istanbul/nyc reporter type.
Default is 'text' when running on the
command line, or 'text-lcov' when piping
to coveralls.
If 'html' is used, then the 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 NYC reporters:
${nycReporters.join(' ')}`,
}),
'no-coverage-report': flag({
description: `Do not output a coverage report, even if coverage
information is generated.`
}),
browser: flag({
description: `Open a browser when an html coverage report is generated.
(this is the default behavior)`,
default: true,
negate: {
description: `Do not open a web browser after generating
an html coverage report`,
}
}),
'show-process-tree': flag({
description: `Enable coverage and display the tree of
spawned processes.`,
implies: {
coverage: true
},
short: 'pstree',
}),
}, {
description: 'Coverage Enfocement Options',
help: `
These options enable you to specify that the test will fail
if a given coverage level is not met. Setting any of the options
below will trigger the --coverage and --check-coverage flags.
The most stringent is --100. You can find a list of projects
running their tests like this at: https://www.node-tap.org/100
If you run tests in this way, please add your project to the list.`,
'check-coverage': flag({
default: true,
description: `Check whether coverage is within
thresholds provided. Setting this
explicitly will default --coverage to
true.
This can be run on its own any time
after a test run that included coverage.`,
implies: {
coverage: true
},
}),
branches: num({
min: 0,
max:100,
default: 100,
hint: 'n',
implies: {
'check-coverage': true,
coverage: true
},
description: `what % of branches must be covered?`,
}),
functions: num({
min: 0,
max:100,
default: 100,
hint: 'n',
implies: {
'check-coverage': true,
coverage: true
},
description: `what % of functions must be covered?`,
}),
lines: num({
min: 0,
max:100,
default: 100,
hint: 'n',
implies: {
'check-coverage': true,
coverage: true
},
description: `what % of lines must be covered?`,
}),
statements: num({
min: 0,
max:100,
default: 100,
hint: 'n',
implies: {
'check-coverage': true,
coverage: true
},
description: `what % of statements must be covered?`,
}),
}, {
description: 'Other Options',
help: flag({
short: 'h',
description: 'Show this helpful output'
}),
version: flag({
short: 'v',
description: 'Show the version of this program.',
}),
'test-regex': opt({
hint: 'pattern',
// anything in a test/ or tests/ folder, or a /tests.js or /test.js,
// or anything ending in *.test.js or *.spec.js
default: '((\\/|^)(tests?|__tests?__)\\/.*|\\.(tests?|spec)|^\\/?tests?)\\.([mc]js|[jt]sx?)$',
description: `A regular expression pattern indicating tests to run if no
positional arguments are provided.
By default, tap will search for all files ending in
.ts, .tsx, .js, .jsx, .cjs, or .mjs, in a top-level folder
named test, tests, or __tests__, or any file ending in
'.spec.' or '.test.' before a supported extension, or a
top-level file named 'test.(js,jsx,...)' or
'tests.(js,jsx,...)'
Ie, the default value for this option is:
((\\/|^)(tests?|__tests?__)\\/.*|\\.(tests?|spec)|^\\/?tests?)\\.([mc]js|[jt]sx?)$
Note that .jsx files will only be run when --jsx is enabled,
.ts files will only be run when --ts is enabled, and .tsx
files will only be run with both --ts and --jsx are enabled.
`
}),
'test-ignore': opt({
hint: 'pattern',
default: '$.',
description: `When no positional arguments are provided, use the supplied
regular expression pattern to exclude tests that would
otherwise be matched by the test-regexp.
Defaults to '$.', which intentionally matches nothing.
Note: folders named tap-snapshots, node_modules, .git, and
.hg 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.`,
}),
'test-arg': list({
hint: 'arg',
description: `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.`,
}),
'test-env': list({
hint: 'key[=<value>]',
description: `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, then the key is ensured to
not be set in the environment. To set a key to the empty
string, use --test-env=key=`,
}),
'nyc-arg': list({
hint: 'arg',
description: `Pass an argument to nyc when running
child processes with coverage enabled.
This can be specified multiple times to
pass multiple args to nyc.`,
}),
'node-arg': list({
hint: 'arg',
description: `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.`,
}),
'expose-gc': flag({
short: 'gc',
alias: '--node-arg=--expose-gc',
description: 'Expose the gc() function to Node.js tests',
}),
debug: flag({
alias: '--node-arg=--debug',
description: 'Run JavaScript tests with node --debug',
}),
'debug-brk': flag({
alias: '--node-arg=--debug-brk',
description: 'Run JavaScript tests with node --debug-brk',
}),
harmony: flag({
alias: '--node-arg=--harmony',
description: 'Enable all Harmony flags in JavaScript tests',
}),
strict: flag({
alias: '--node-arg=--use-strict',
description: `Run JS tests in 'use strict' mode`,
}),
flow: flag({
description: `Removes flow types`,
}),
ts: flag({
default: process.env.TAP_TS === '1',
description: `Automatically load .ts and .tsx tests ts-node module.
Note: you must provide ts-node as a dependency yourself, tap does
not automatically bundle it. (Default: false)`,
}),
jsx: flag({
default: process.env.TAP_JSX === '1',
description: `Automatically load .jsx tests using tap's bundled import-jsx
loader (Default: false)`,
}),
'nyc-help': flag({
description: `Print nyc usage banner. Useful for
viewing options for --nyc-arg.`,
}),
'nyc-version': flag({
description: 'Print version of nyc used by tap.',
}),
'parser-version': flag({
description: 'Print the version of tap-parser used by tap.',
}),
versions: flag({
description: 'Print versions of tap, nyc, and tap-parser',
}),
'dump-config': flag({
description: 'Dump the config options in YAML format',
}),
rcfile: opt({
hint: 'file',
description: `Load any of these configurations from a YAML-formatted
file at the path specified. Defaults to .taprc in the
current working directory.
Run 'tap --dump-config' to see available options and
formatting.`,
envDefault: 'TAP_RCFILE',
default: `${process.cwd()}/.taprc`,
}),
'libtap-settings': opt({
hint: 'module',
description: `A module which exports an object of fields to assign onto
'libtap/settings'. These are advanced configuration options
for modifying the behavior of tap's internal runtime.
Module path is resolved relative to the current working
directory.
Allowed fields: rmdirRecursive, rmdirRecursiveSync,
StackUtils, stackUtils, output, snapshotFile.
See libtap documentation for expected values and usage.
https://github.com/tapjs/libtap`,
envDefault: 'TAP_LIBTAP_SETTINGS',
default: null,
}),
'output-file': opt({
short: 'o',
hint: 'file',
default: null,
description: `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.`,
}),
'output-dir': opt({
short: 'd',
hint: 'dir',
default: null,
description: `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.`,
}),
/* eslint-disable-next-line */
debug: flag({
envDefault: 'TAP_DEBUG',
description: 'Turn on debug mode',
}),
'--': flag({
description: `Stop parsing flags, and treat any additional
command line arguments as filenames.`
}),
}, {
description: 'Environment Variables',
COVERALLS_REPO_TOKEN: env({
description: `Set to a Coveralls token to automatically
send coverage information to https://coveralls.io,
if the 'coveralls' module is installed in the project.`,
implies: {
coverage: true
},
default: null,
}),
TAP_CHILD_ID: env(num({
description: `Test files have this value set to a
numeric value when run through the test
runner. It also appears on the root tap
object as \`tap.childId\`.`,
})),
TAP_SNAPSHOT: env(flag({
description: `Set to '1' to generate snapshot files
for 't.matchSnapshot()' assertions.`,
})),
TAP_RCFILE: env({
description: `A yaml formatted file which can set any
of the above options. Defaults to
./.taprc`
}),
TAP_LIBTAP_SETTINGS: env({
description: `A path (relative to current working directory) of a file
that exports fields to override the default libtap settings`,
}),
TAP_TIMEOUT: env(num({
min: 0,
default: 30,
description: `Default value for --timeout option.`
})),
TAP_COLORS: env(flag({
description: `Set to '1' to force color output, or '0'
to prevent color output.`
})),
TAP_BAIL: flag(env({
description: `Bail out on the first test failure.
Used internally when '--bailout' is set.`
})),
TAP: flag(env({
implies: {
reporter: 'tap'
},
description: `Set to '1' to force standard TAP output,
and suppress any reporters. Used when
running child tests so that their output
is parseable by the test harness.`
})),
TAP_DIAG: env(flag({
description: `Set to '1' to show diagnostics by
default for passing tests. Set to '0'
to NOT show diagnostics by default for
failing tests. If not one of these two
values, then diagnostics are printed by
default for failing tests, and not for
passing tests.`
})),
TAP_BUFFER: env(flag({
description: `Set to '1' to run subtests in buffered
mode by default.`
})),
TAP_DEV_LONGSTACK: env(flag({
description: `Set to '1' to include node-tap internals
in stack traces. By default, these are
included only when the current working
directory is the tap project itself.
Note that node internals are always
excluded.`
})),
TAP_DEBUG: env(flag({
description: `Set to '1' to turn on debug mode.`
})),
NODE_DEBUG: env({
description: `Include 'tap' to turn on debug mode.`
}),
TAP_GREP: env(list({
delimiter: '\n',
description: `A '\\n'-delimited list of grep patterns
to apply to root level test objects.
(This is an implementation detail for how
the '--grep' option works.)`
})),
TAP_GREP_INVERT: env(flag({
description: `Set to '1' to invert the meaning of the
patterns in TAP_GREP. (Implementation
detail for how the '--invert' flag
works.)`
})),
TAP_ONLY: env(flag({
description: `Set to '1' to set the --only flag`
})),
TAP_TS: env(flag({
description: `Set to '1' to enable automatic typescript support`
})),
TAP_JSX: env(flag({
description: `Set to '1' to enable automatic jsx support`
})),
}, {
// a section that's just a description. This is totally fine.
// You can break up the usage output this way.
description: 'Config Files',
help: `You can create a yaml file with any of the options above. By
default, the file at ./.taprc will be loaded, but the
--rcfile option or TAP_RCFILE environment variable can modify this.
Run 'tap --dump-config' for a listing of what can be set in that
file. Each of the keys corresponds to one of the options above.`,
})
|