Node.js Reference ยท CLI Flags
Node.js --test flag
Reference for node --test: how the built-in test runner finds files, its reporters, filters like --test-name-pattern, concurrency, coverage and exit codes.
node --test runs Node.js's built-in test runner. Without arguments it searches the current directory for test files, runs each file in its own process, and prints a report. The exit code is 0 if everything passed and 1 if any test failed, which makes it directly usable in CI.
Tests themselves are written with the node:test module (test(), describe(), it()) and node:assert. This page covers the command line; the API is in test().
node --test node --test tests/
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
node --test [options] [files or globs]
| Flag | Description |
|---|---|
--test |
Run the test runner instead of a script. Optional arguments are files, directories or globs. |
--test-reporter=name |
Choose the output: spec (default in a terminal), tap, dot, junit, lcov. Combine with --test-reporter-destination=file. |
--test-name-pattern=regex |
Run only tests whose names match. Repeatable. |
--test-skip-pattern=regex |
Skip tests whose names match. |
--test-only |
Run only tests marked with the only option. |
--test-concurrency=n |
Number of test files to run at the same time. |
--test-timeout=ms |
Fail any test that takes longer. |
--test-shard=index/total |
Run one slice of the files, for splitting across CI machines. |
--experimental-test-coverage |
Collect a coverage report (see concept: coverage). |
--watch |
Rerun when files change. |
Default file discovery (when no arguments are given): files named *.test.{js,cjs,mjs}, *-test.*, *_test.* and test-*.* anywhere, plus every file inside a directory named test.
Exit codes: 0 all passed, 1 one or more failed.
Usage notes
- One process per file. Tests in different files are isolated from each other, so module state does not leak between files. Within a file, tests run in the order defined unless you opt into concurrency.
- Quote globs so the runner, not the shell, expands them:
node --test "src/**/*.test.js". This is portable to Windows. - Reporters. Current Node versions default to
spec; older ones usedtapwhen output was piped. Pick one explicitly in CI so output does not change with the version. - Helper files in a
testdirectory run as tests because every file there is considered a test. Keep fixtures elsewhere or name them so they are not matched. - Combine with other flags.
--import,--require,--env-fileand--experimental-strip-typesapply to every test process. - Pass failure details to CI with
--test-reporter=junit --test-reporter-destination=results.xml. - Mocking and timers (
mock,mock.timers) come fromnode:test; see Mocking and timers.