Skip to content
Tutorials Center
My learning

Topics

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().

Terminal
node --test
node --test tests/

Try it

Node.js Running a test file with the runner

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.

Node.js Filtering by name and file discovery

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

Terminal
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 used tap when output was piped. Pick one explicitly in CI so output does not change with the version.
  • Helper files in a test directory 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-file and --experimental-strip-types apply 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 from node:test; see Mocking and timers.