{"id":15401,"library":"ts-node-test","title":"TypeScript Node.js Test Runner Wrapper","description":"ts-node-test is a command-line interface (CLI) wrapper that enables the use of Node.js's native test runner (introduced in Node.js 18.7.0) with TypeScript files. It addresses a limitation in Node.js where the built-in test runner does not natively support custom file extensions for automatic test file discovery, requiring explicit file paths for `.ts` files. This package works by recursively searching specified directories for `.ts`, `.mts`, `.cts`, `.js`, `.mjs`, and `.cjs` files, then passing the discovered files to the Node.js test runner via `ts-node` for execution. The current stable version is 0.4.4, with releases occurring intermittently, focusing on bug fixes, dependency updates, and feature parity with newer Node.js test runner flags. Its primary differentiator is simplifying the setup for TypeScript projects wanting to leverage Node.js's native testing capabilities without complex build steps or manual file listings.","status":"active","version":"0.4.4","language":"javascript","source_language":"en","source_url":"https://github.com/meyfa/ts-node-test","tags":["javascript","nodejs","test","test runner","testing","typescript","ts-node"],"install":[{"cmd":"npm install ts-node-test","lang":"bash","label":"npm"},{"cmd":"yarn add ts-node-test","lang":"bash","label":"yarn"},{"cmd":"pnpm add ts-node-test","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for TypeScript compilation. Must be installed alongside ts-node-test.","package":"typescript","optional":false}],"imports":[{"note":"ts-node-test is primarily a CLI tool. Its functionality is 'imported' by executing the command line utility, typically via `package.json` scripts. There are no direct programmatic exports for import statements from this package itself.","symbol":"Basic CLI Usage","correct":"npm i -D ts-node-test && npm test"},{"note":"The `TEST_EXTENSIONS` environment variable allows overriding the default list of test file extensions, crucial for projects with specific naming conventions. This must be set before invoking `ts-node-test`.","symbol":"CLI with Custom Extensions","correct":"TEST_EXTENSIONS=.test.ts,.spec.ts npm test"},{"note":"CLI flags such as `--watch`, `--test-only`, `--test-name-pattern`, `--test-reporter`, `--experimental-test-coverage`, etc., are passed directly to the underlying Node.js test runner. These are typically included after `ts-node-test` in the command.","symbol":"CLI with Node.js Test Flags","correct":"npm i -D ts-node-test && ts-node-test --watch --test-name-pattern='my_test' test/**/*.ts"}],"quickstart":{"code":"/* package.json */\n{\n  \"name\": \"my-ts-project\",\n  \"version\": \"1.0.0\",\n  \"scripts\": {\n    \"test\": \"ts-node-test 'src/**/*.test.ts' 'test/**/*.test.ts'\"\n  },\n  \"devDependencies\": {\n    \"ts-node-test\": \"^0.4.4\",\n    \"typescript\": \"^5.0.0\",\n    \"@types/node\": \"^18.7.0\" \n  },\n  \"engines\": {\n    \"node\": \">=18.7.0\"\n  }\n}\n\n/* test/example.test.ts */\nimport { test, mock } from 'node:test';\nimport { equal, ok } from 'node:assert/strict';\n\nconst greet = mock.fn((name: string) => `Hello, ${name}!`);\n\ntest('synchronous passing test', () => {\n  equal(1, 1, 'Numbers should be equal');\n});\n\ntest('asynchronous passing test', async () => {\n  const promise = Promise.resolve(42);\n  const result = await promise;\n  equal(result, 42, 'Result should be 42');\n});\n\ntest('test with mocks and assertions', () => {\n  greet('World');\n  equal(greet.mock.callCount(), 1, 'greet should be called once');\n  equal(greet.mock.calls[0].arguments[0], 'World', 'Argument should be World');\n  equal(greet.mock.calls[0].result, 'Hello, World!', 'Return value should be correct');\n});\n\ntest('test with subtest and tags', { tags: ['core', 'feature'] }, async (t) => {\n  await t.test('subtest 1: addition', () => {\n    ok(2 + 2 === 4, '2 + 2 should be 4');\n  });\n  await t.test('subtest 2: skipped example', { skip: true }, () => {\n    // This test will be skipped and not executed\n    equal(true, false, 'This assertion should not run if skipped');\n  });\n});\n\n// To run: \n// 1. npm init -y\n// 2. npm i -D ts-node-test typescript @types/node\n// 3. Create package.json and test/example.test.ts as shown above\n// 4. npm test","lang":"typescript","description":"This quickstart demonstrates how to set up `ts-node-test` in a `package.json` script, along with a simple TypeScript test file using Node.js's native test runner API, including synchronous, asynchronous, mocked, and sub-tests."},"warnings":[{"fix":"Upgrade your Node.js installation to version 18.7.0 or newer. Use `nvm install 18` or `nvm install 20` and `nvm use <version>`.","message":"ts-node-test requires Node.js version 18.7.0 or higher due to its reliance on the native Node.js test runner API. Earlier Node.js versions are not supported.","severity":"breaking","affected_versions":"<=0.4.4"},{"fix":"Install TypeScript: `npm install -D typescript` or `yarn add -D typescript`.","message":"A `typescript` peer dependency is required. Ensure `typescript` is installed in your project (e.g., as a dev dependency) alongside `ts-node-test`. Missing this will result in compilation errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Upgrade to `ts-node-test` v0.4.1 or newer. If staying on an older version, explicitly list test file paths or use fine-grained glob patterns to avoid `node_modules`.","message":"Prior to v0.4.1, `ts-node-test` would recursively search for test files within `node_modules` if a directory path like `./` was provided, potentially leading to unintended test execution or performance issues. This behavior was fixed to explicitly exclude `node_modules` unless specified.","severity":"gotcha","affected_versions":"<0.4.1"},{"fix":"Ensure you are using the latest version of `ts-node-test` to get full compatibility with new Node.js test runner features. Upgrade with `npm update ts-node-test`.","message":"Older versions of `ts-node-test` might not fully support all command-line flags available in the latest Node.js test runner. For example, `--watch` mode was introduced in v0.3.0, and support for additional flags like `--experimental-test-coverage` was added in v0.4.0.","severity":"deprecated","affected_versions":"<0.4.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Install TypeScript as a dev dependency: `npm install -D typescript` or `yarn add -D typescript`.","cause":"The `typescript` package is a peer dependency of `ts-node-test` but is not installed in your project.","error":"Error: Cannot find module 'typescript' from '...' at Function.resolveSync"},{"fix":"Upgrade your Node.js environment to version 18.7.0 or newer. Consider using a tool like `nvm` to manage Node.js versions.","cause":"You are trying to run `ts-node-test` with an older version of Node.js that does not meet the minimum requirement of 18.7.0.","error":"Error: The Node.js test runner API is only available in Node.js >= 18.7.0."},{"fix":"Ensure `TEST_EXTENSIONS` is a comma-separated string of valid extensions (e.g., `.ts,.js`). Double-check the glob patterns or file paths passed to `ts-node-test` to ensure they point to existing files.","cause":"This error can occur if `TEST_EXTENSIONS` environment variable is set to an invalid value (e.g., empty or null) or if the test paths provided to `ts-node-test` are incorrect or resolve to nothing.","error":"TypeError [ERR_INVALID_ARG_TYPE]: The 'path' argument must be of type string or an instance of 'URL'. Received null"}],"ecosystem":"npm"}