Better Node Test

0.8.4 · active · verified Sun Apr 19

Better Node Test (BNT) is a command-line interface (CLI) tool designed to streamline the usage of Node.js's native `node --test` runner. It significantly enhances the testing workflow by providing out-of-the-box support for TypeScript, a convenient `-t` shortcut for filtering and running specific tests by name, and integrated code coverage analysis through the `--coverage` flag. The current stable version is 0.8.4, with releases showing a consistent cadence of minor and patch updates, often addressing compatibility with evolving Node.js features like `strip-types` and robust coverage reporting. BNT differentiates itself by leveraging Node.js's built-in testing capabilities, minimizing reliance on additional third-party test runners, while adding essential developer conveniences like automatic TypeScript compilation and comprehensive coverage reporting tailored for modern Node.js environments.

Common errors

```
Error: This Node.js version is not supported. Please use Node.js ^18.19.0 || ^20.0.0 || ^22.0.0 || >=24.0.0
```
cause The installed Node.js version does not meet the minimum requirements specified in the `package.json` `engines` field for `better-node-test`.

fix Update your Node.js environment to a compatible version (e.g., 20.x or 22.x) using `nvm install <version>` or similar version management tools.
```
Error: Coverage is not supported on this Node.js version. Please upgrade Node.js to use this feature.
```
cause The `--coverage` flag was used with `better-node-test` on a Node.js version that does not fully support the native `node --test` coverage functionality.

fix Upgrade Node.js to a version that provides robust native test coverage support (e.g., Node.js 20.x or 22.x), or remove the `--coverage` flag if an upgrade is not feasible.
```
TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for /path/to/your/test.ts
```
cause Node.js cannot directly execute `.ts` files without a transpilation step. This error, when using `better-node-test`, might indicate a misconfiguration, an unsupported Node.js version interfering with the native `strip-types` feature, or bypassing `bnt` CLI execution.

fix Ensure `better-node-test` is executed via `npx bnt` and that your Node.js version is compatible with its `engines` requirements. Avoid manual `node --loader ts-node` setups when using `bnt`, as `bnt` handles TypeScript compilation internally.

Warnings

breaking Using `better-node-test` with Node.js versions older than those specified in its `engines` field (e.g., `<18.19.0`, `<20.0.0`, `<22.0.0`, or `<24.0.0`) will result in execution failures or unexpected behavior due to engine constraints.
Fix: Ensure your Node.js environment meets the minimum `engines` requirement. Upgrade Node.js to at least `18.19.0` (or `20.0.0`, `22.0.0`, `24.0.0` for newer features and optimal compatibility) using `nvm` or similar version managers.
gotcha Attempting to use the `--coverage` flag on Node.js versions that do not fully support native `node --test` coverage functionality (e.g., pre-Node.js 18.19.0 for initial coverage, or older versions for full features) will result in an explicit error message and failure to report coverage.
Fix: Update to a recent stable Node.js version (e.g., 20.x or 22.x) to ensure full compatibility with native test coverage features, or disable the `--coverage` flag if targeting older Node.js environments.
gotcha The `--experimental-strip-types` flag, while initially supported and sometimes necessary for TypeScript execution on older Node.js versions, has seen its handling evolve. As of `0.8.2`, `better-node-test` aims to always use native strip types for modern Node.js, potentially making this flag redundant or handled implicitly. Relying on its explicit presence or specific behavior might become inconsistent with future Node.js updates or `better-node-test` releases.
Fix: For modern Node.js (>=20.x, 22.x), `better-node-test` should handle TypeScript stripping automatically. Avoid explicitly relying on `--experimental-strip-types` unless specifically troubleshooting or targeting older, unsupported Node.js versions where it was explicitly required.

Install

npm install better-node-test npm
yarn add better-node-test yarn
pnpm add better-node-test pnpm

Quickstart

Demonstrates creating a simple Node.js test file with TypeScript and running it using `better-node-test` with various CLI options, including coverage and test filtering.

import assert from 'node:assert/strict';
import { test } from 'node:test';

// Save this content as 'test/example.test.ts'

test('basic math works', () => {
  assert.strictEqual(1 + 1, 2, 'Addition should be correct');
});

test('async operation', async () => {
  const result = await Promise.resolve('data');
  assert.strictEqual(result, 'data', 'Async result should match');
});

test('array includes item', () => {
  const arr = [1, 2, 3];
  assert.ok(arr.includes(2), 'Array should include 2');
});

// To install better-node-test:
// npm install --save-dev better-node-test

// To run all tests and get coverage (100% threshold, excluding test files from coverage calculation):
// npx bnt --coverage 100 --coverage-exclude '**/*.test.*'

// To run a specific test by name:
// npx bnt test/example.test.ts -t 'basic math works'

// To run all tests:
// npx bnt

view raw JSON →