Registry / testing / test-runner

test-runner

JSON →
library0.7.0jsnpmunverified

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.

testing
npm install test-runner
github ↗package ↗
INSTALL
IMPORT
SIG · TEST-RUNNER
T
test-runner
testingjavascriptv0.7.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Tom
✓ import { Tom } from 'test-runner'
✗ import Tom from 'test-runner'
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.
Tom
✓ const { Tom } = require('test-runner')
✗ const Tom = require('test-runner')
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.
Tom
✓ import type { Tom } from 'test-runner'
✗ 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.
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)

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.

npm install --save-dev test-runner node-fetch // test.js const { Tom } = require('test-runner') const assert = require('assert').strict const fetch = require('node-fetch') const tom = new Tom() tom.test('Math.random() should return a number between 0 and 1', function () { const result = Math.random() assert.equal(typeof result, 'number') assert.ok(result >= 0 && result <= 1) }) tom.test('REST API should return the current todo item', async function () { const response = await fetch('https://jsonplaceholder.typicode.com/todos/1') const todo = await response.json() assert.equal(todo.userId, 1) assert.equal(todo.title, 'delectus aut autem') }) module.exports = tom; // Run from your terminal // $ npx test-runner test.js
test-runner --version
Debug
Known issues
breakingThe 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.
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.
affects: >=0.x.x
gotchatest-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.
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).
affects: <12.17
gotchaThe 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.
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.
affects: >=0.x.x
gotchatest-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.
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.
affects: >=0.x.x
gotchaWhile 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.
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.
affects: >=0.x.x
Errors
Common errors & fixes
ReferenceError: require is not defined
Attempting to use `require` in an ECMAScript Module (ESM) file (e.g., when `"type": "module"` is set in `package.json`).
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`.
SyntaxError: Named export 'Tom' not found. The requested module 'test-runner' does not provide an export named 'Tom'
Attempting to use an ESM `import` statement in a CommonJS context without proper transpilation, or incorrect export mapping in `package.json`.
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.
TypeError: tom.test is not a function
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.
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`.
Error: No test files found matching pattern: <your_pattern>
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.
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'`.
Upgrade
Version history
0.7.0latest on npm
Audit
Dependencies
node-fetchoptionalCommonly used in test files for making HTTP requests, as demonstrated in the quickstart example. Users must install this separately if their tests require it.
Agent activity
10 hits · last 30 days
node
10
Resources
githubhttps://github.com/test-runner-js/test-runner ↗
packagehttps://www.npmjs.com/package/test-runner ↗
test-runner — npm install test-runner · libregistry