better-node-test

library0.8.4jsnpmunverified

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.

testing devops

npm install better-node-test

github ↗package ↗

INSTALL

IMPORT

SIG · BETTER-NODE-TEST

better-node-test

testingjavascriptv0.8.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

bnt --version

Debug

Known issues

breakingUsing `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.

affects: *

gotchaAttempting 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.

affects: *

gotchaThe `--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.

affects: >=0.8.2

Errors

Common errors & fixes

Error: This Node.js version is not supported. Please use Node.js ^18.19.0 || ^20.0.0 || ^22.0.0 || >=24.0.0

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.

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

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.

Upgrade

Version history

0.8.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ai/better-node-test ↗

packagehttps://www.npmjs.com/package/better-node-test ↗