Run a single test file in Node.js

Pass the file path to Node's built-in test runner:

node --test test/math.test.cjs

Use a supported Node release. The test runner arrived in Node 18 and was also backported to 16.17; its feature set and stability changed across later releases.

Create a small runnable test

Save this as math.cjs:

exports.add = (a, b) => a + b;

Place math.test.cjs beside it:

const test = require('node:test');
const assert = require('node:assert/strict');
const { add } = require('./math.cjs');
test('adds positive numbers', () => {
  assert.equal(add(2, 3), 5);
});
test('handles a negative number', () => {
  assert.equal(add(-1, 1), 0);
});

node --test math.test.cjs
node --test --test-name-pattern='adds positive' math.test.cjs

Put runner options before the file path. --test-name-pattern filters test names with a regular expression. Be aware that parent suites can affect selection of nested tests.

Running node --test without an explicit file invokes the runner's discovery rules, which include more than just *.test.js. Consult the rules for your Node release and repository layout.

Use only-mode deliberately

To select tests marked with test.only() in the normal isolated runner, invoke node --test --test-only math.test.cjs. Merely adding .only without enabling the appropriate mode is not a reliable way to restrict the run. Remove temporary selections before committing tests so the full suite remains meaningful.

Watch mode is available for the test runner from Node 18.13 and 19.2:

node --test --watch math.test.cjs

Other frameworks

For frameworks already installed in the project:

npx jest --runTestsByPath test/math.test.js
npx jest --runTestsByPath test/math.test.js -t 'adds positive'
npx mocha test/math.test.js
npx vitest run test/math.test.js

Jest's --runTestsByPath treats the supplied path as an exact file rather than a path-pattern filter. Vitest's filename argument is a filter and can match more than one file; inspect its selected-file output. npx may offer to fetch a missing package, so ensure you are using the project's intended runner and version.

The built-in runner provides assertions through node:assert and version-dependent mocking, snapshots, and coverage features. Choose a framework based on the features and integrations your tests need, rather than project size alone.

For supported releases, coverage uses node --test --experimental-test-coverage math.test.cjs. Do not assume a generic --test-coverage replacement exists. Coverage support, exclusions, and thresholds vary by release; check node --help and the matching documentation before adding flags to CI.

References

• Node.js test runner
• Node.js CLI options
• Jest CLI
• Vitest CLI
• Mocha CLI