{"id":14974,"library":"test-runner","title":"test-runner","description":"test-runner is a fully-featured, lightweight command-line test runner designed for full-stack JavaScript engineers to create and test modern, isomorphic code. It operates by taking one or more files, each exporting a `test object model` (TOM) instance, running the contained tests with controlled order and concurrency, and generating a report. Currently at version `0.11.1`, the project is explicitly marked as \"Work In Progress,\" indicating an active development phase with potential for frequent, non-semver compliant breaking changes before a stable `1.0` release. Its key differentiators include native support for both CommonJS and ECMAScript modules, execution in Node.js and headless Chromium for isomorphic testing, and a unique `Tom` API for defining test suites, distinguishing it from runners relying on global functions or specific assertion libraries. It aims to be part of a broader suite of JavaScript testing tools.","status":"active","version":"0.11.1","language":"javascript","source_language":"en","source_url":"https://github.com/test-runner-js/test-runner","tags":["javascript","test-runner","test","runner","cli","unit","testing","tool","tape"],"install":[{"cmd":"npm install test-runner","lang":"bash","label":"npm"},{"cmd":"yarn add test-runner","lang":"bash","label":"yarn"},{"cmd":"pnpm add test-runner","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Commonly used in test files for making HTTP requests, as demonstrated in the quickstart example. Users must install this separately if their tests require it.","package":"node-fetch","optional":true}],"imports":[{"note":"For ECMAScript Modules (ESM) environments. 'Tom' is a named export. Attempting a default import will fail. 'Tom' is re-exported from the 'test-object-model' package.","wrong":"import Tom from 'test-runner'","symbol":"Tom","correct":"import { Tom } from 'test-runner'"},{"note":"For CommonJS (CJS) environments. 'Tom' is a named export. Attempting to require the entire module and access it as a default export will result in an undefined 'Tom'. 'Tom' is re-exported from the 'test-object-model' package.","wrong":"const Tom = require('test-runner')","symbol":"Tom","correct":"const { Tom } = require('test-runner')"},{"note":"For TypeScript projects, this imports the type definition for the Tom class. Assumes type definitions are shipped with the package or via @types. (Unconfirmed in v0.11.1)","wrong":"import { Tom } from 'test-runner'; // Used only for type annotation, potentially causes runtime overhead or bundling issues if not handled by a type-stripping transpiler.","symbol":"Tom","correct":"import type { Tom } from 'test-runner'"}],"quickstart":{"code":"npm install --save-dev test-runner node-fetch\n\n// test.js\nconst { Tom } = require('test-runner')\nconst assert = require('assert').strict\nconst fetch = require('node-fetch')\n\nconst tom = new Tom()\n\ntom.test('Math.random() should return a number between 0 and 1', function () {\n  const result = Math.random()\n  assert.equal(typeof result, 'number')\n  assert.ok(result >= 0 && result <= 1)\n})\n\ntom.test('REST API should return the current todo item', async function () {\n  const response = await fetch('https://jsonplaceholder.typicode.com/todos/1')\n  const todo = await response.json()\n  assert.equal(todo.userId, 1)\n  assert.equal(todo.title, 'delectus aut autem')\n})\n\nmodule.exports = tom;\n\n// Run from your terminal\n// $ npx test-runner test.js","lang":"javascript","description":"This quickstart demonstrates how to set up and run basic synchronous and asynchronous tests using `test-runner` in a Node.js CommonJS environment, including an external dependency (`node-fetch`) for API testing."},"warnings":[{"fix":"Monitor the project's GitHub repository and release notes closely for updates. Consider pinning to exact versions for critical projects and thorough testing after updates.","message":"The project is explicitly marked as 'Work In Progress' (WIP) and is currently at version 0.11.1. This indicates that the API is not yet stable and breaking changes may occur frequently without strict adherence to semantic versioning until a 1.0 release.","severity":"breaking","affected_versions":">=0.x.x"},{"fix":"Ensure your Node.js environment meets the minimum requirement by upgrading to version 12.17 or newer (e.g., using nvm or your package manager).","message":"test-runner requires Node.js version 12.17 or higher. Running on older Node.js environments will result in runtime errors or unexpected behavior due to unsupported syntax or APIs.","severity":"gotcha","affected_versions":"<12.17"},{"fix":"Refer to the 'test-object-model' documentation and the 'test-runner' README for examples on how to correctly structure test files using the `Tom` instance.","message":"The test definition relies on an instance of the `Tom` class from 'test-object-model' (re-exported by 'test-runner'). Users must familiarize themselves with the `Tom` API (e.g., `tom.test`, `tom.skip`) as it's the primary interface for defining tests, differing from other runners that might use global functions or specific syntaxes.","severity":"gotcha","affected_versions":">=0.x.x"},{"fix":"Ensure consistency in your module system. For ESM, use `import` statements and ensure your `package.json` has `\"type\": \"module\"`. For CJS, use `require` statements. Refer to Node.js documentation on module systems.","message":"test-runner supports both CommonJS (CJS) and ECMAScript Modules (ESM). Incorrectly mixing module systems (e.g., using `require` in an ESM file with `\"type\": \"module\"` or `import` in a pure CJS file without transpilation) can lead to module resolution errors.","severity":"gotcha","affected_versions":">=0.x.x"},{"fix":"Use universal APIs or conditional logic (e.g., checking `typeof window`) within your tests, or create distinct test files and run configurations for browser-only and Node.js-only code.","message":"While test-runner supports isomorphic testing across Node.js and headless Chromium, environment-specific APIs (e.g., `node-fetch` in Node.js vs. native `fetch` in browser) or DOM manipulation will require careful abstraction or separate test files/configurations to run successfully in both environments.","severity":"gotcha","affected_versions":">=0.x.x"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Switch to `import { Tom } from 'test-runner'` or change your file to be a CommonJS module by removing `\"type\": \"module\"` from `package.json` or changing the file extension to `.cjs`.","cause":"Attempting to use `require` in an ECMAScript Module (ESM) file (e.g., when `\"type\": \"module\"` is set in `package.json`).","error":"ReferenceError: require is not defined"},{"fix":"If in a CommonJS context, use `const { Tom } = require('test-runner')`. If in ESM, ensure your `package.json` correctly defines module type and exports, and that the `test-runner` package correctly provides ESM exports.","cause":"Attempting to use an ESM `import` statement in a CommonJS context without proper transpilation, or incorrect export mapping in `package.json`.","error":"SyntaxError: Named export 'Tom' not found. The requested module 'test-runner' does not provide an export named 'Tom'"},{"fix":"Ensure you have `const { Tom } = require('test-runner')` (or `import { Tom } from 'test-runner')` and `const tom = new Tom()` in your test file, and that the test file exports the `tom` instance: `module.exports = tom`.","cause":"The `Tom` object was not correctly instantiated, or the `test` method does not exist on the object being used. This usually happens if `Tom` was not imported/required properly or if `module.exports = tom` is missing from the test file.","error":"TypeError: tom.test is not a function"},{"fix":"Verify the file paths and patterns provided to `test-runner`. Use glob patterns cautiously and ensure they match your file structure. E.g., `npx test-runner 'test/**/*.js'`.","cause":"The command-line arguments for `test-runner` do not correctly specify the path(s) to your test files, or the files do not exist at the specified location.","error":"Error: No test files found matching pattern: <your_pattern>"}],"ecosystem":"npm"}