{"id":14466,"library":"better-node-test","title":"Better Node Test","description":"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.","status":"active","version":"0.8.4","language":"javascript","source_language":"en","source_url":"https://github.com/ai/better-node-test","tags":["javascript","node","test","typescript"],"install":[{"cmd":"npm install better-node-test","lang":"bash","label":"npm"},{"cmd":"yarn add better-node-test","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-node-test","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[],"quickstart":{"code":"import assert from 'node:assert/strict';\nimport { test } from 'node:test';\n\n// Save this content as 'test/example.test.ts'\n\ntest('basic math works', () => {\n  assert.strictEqual(1 + 1, 2, 'Addition should be correct');\n});\n\ntest('async operation', async () => {\n  const result = await Promise.resolve('data');\n  assert.strictEqual(result, 'data', 'Async result should match');\n});\n\ntest('array includes item', () => {\n  const arr = [1, 2, 3];\n  assert.ok(arr.includes(2), 'Array should include 2');\n});\n\n// To install better-node-test:\n// npm install --save-dev better-node-test\n\n// To run all tests and get coverage (100% threshold, excluding test files from coverage calculation):\n// npx bnt --coverage 100 --coverage-exclude '**/*.test.*'\n\n// To run a specific test by name:\n// npx bnt test/example.test.ts -t 'basic math works'\n\n// To run all tests:\n// npx bnt","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"*"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.8.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The installed Node.js version does not meet the minimum requirements specified in the `package.json` `engines` field for `better-node-test`.","error":"Error: This Node.js version is not supported. Please use Node.js ^18.19.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"},{"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.","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.","error":"Error: Coverage is not supported on this Node.js version. Please upgrade Node.js to use this feature."},{"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.","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.","error":"TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension \".ts\" for /path/to/your/test.ts"}],"ecosystem":"npm"}