test-director

library11.0.0jsnpmunverified

test-director is an ultra-lightweight unit test director specifically designed for Node.js environments. Currently stable at version 11.0.0, the package maintains a steady release cadence with frequent updates to Node.js support and internal tooling. Its key differentiators include its minimal footprint, strict adherence to ECMAScript Modules (ESM) as its primary distribution format since v6, and its compatibility with any assertion library that throws errors (such as Node.js `assert` or `snapshot-assertion`). It leverages JSDoc for providing TypeScript type definitions, emphasizing a JavaScript-first, standards-compliant approach to testing without imposing specific assertion frameworks or runners.

testing

npm install test-director

github ↗package ↗

INSTALL

IMPORT

SIG · TEST-DIRECTOR

test-director

testingjavascriptv11.0.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.

TestDirector

✓ import TestDirector from 'test-director';

✗ const TestDirector = require('test-director'); import { TestDirector } from 'test-director';

The package is ESM-only since v6.0.0 and `TestDirector` is a default export.

TestDirector (TypeScript types)

✓ import TestDirector from 'test-director';

✗ import type { TestDirector } from 'test-director';

Types are provided via JSDoc comments; the default import provides both runtime and type information if TypeScript is configured correctly (e.g., `allowJs: true`, `module: node16`/`nodenext`).

Node.js Built-ins

✓ import { equal } from 'node:assert';

✗ import { equal } from 'assert';

Since v10.0.0, `test-director` internally uses the `node:` URL scheme for built-in modules. While not strictly required for consumer code, it is recommended for consistency and future-proofing.

Demonstrates synchronous, asynchronous, and nested tests, showcasing `TestDirector`'s basic API for defining and running tests with Node.js `assert` and `fetch`.

import { equal, ok } from 'node:assert'; import TestDirector from 'test-director'; const tests = new TestDirector(); // A basic synchronous test tests.add('Synchronous addition check.', () => { equal(1 + 1, 2); }); // An asynchronous test involving a network request tests.add('External service check (GitHub).', async () => { const response = await fetch('https://github.com'); ok(response.ok, 'GitHub response should be OK.'); }); // Nested tests for hierarchical reporting tests.add('Grouped operations with sub-tests.', async () => { const nestedTests = new TestDirector(); nestedTests.add('Sub-test A: String manipulation.', () => { equal('HELLO'.toLowerCase(), 'hello'); }); nestedTests.add('Sub-test B: Array length check.', () => { equal([1, 2, 3].length, 3); }); await nestedTests.run(true); // 'true' for nested tests to run immediately }); tests.add('Final top-level assertion.', () => { ok(true, 'This final assertion should always pass.'); }); tests.run(); // Execute all defined tests

Debug

Known issues

breakingThe package transitioned to ESM-only in v6.0.0, moving from CJS `.js` files to `.mjs`. This means `TestDirector` can only be imported via `import` statements and is no longer accessible via `require()`. This is a significant breaking change for CommonJS projects.

fix

Migrate your project to use ECMAScript Modules (`import` syntax) or pin to a version prior to v6.0.0 if CommonJS is required.

affects: >=6.0.0

breakingThe minimum Node.js version support has been updated frequently across major releases. For v11.0.0, the package requires Node.js `^16.9.0 || >= 18.0.0`. Running on older Node.js versions will lead to runtime errors or incompatibilities.

fix

Ensure your Node.js environment meets the minimum requirements for the installed `test-director` version. Upgrade Node.js if necessary.

affects: >=5.0.0

breakingSince v6.0.0, the `TestDirector` class is exclusively available as a default import. Attempting to use a named import (e.g., `import { TestDirector } from 'test-director'`) will result in an `undefined` value or `TypeError`.

fix

Always use `import TestDirector from 'test-director';` to correctly import the class.

affects: >=6.0.0

breakingIn v10.0.0, the `package.json` `main` field was removed, relying solely on the `exports` field for module resolution. This might affect older tooling or bundlers that do not fully support the `exports` field, leading to module resolution errors.

fix

Update your build tooling (e.g., Webpack, Rollup) or Node.js environment to versions that fully support the `exports` field in `package.json`.

affects: >=10.0.0

breakingWith v5.0.0, the internal file structure was reorganized, breaking any previously used deep imports (e.g., `test-director/path/to/module`). Custom import paths must be updated according to the package's `exports` definition.

fix

Refer to the package's `package.json` `exports` field or documentation for correct import paths. Avoid deep imports unless explicitly documented.

affects: >=5.0.0

gotchaWhile `test-director` ships types via JSDoc, correct TypeScript project configuration is required to fully leverage them. Specifically, `compilerOptions.allowJs` should be `true`, `compilerOptions.maxNodeModuleJsDepth` set reasonably high (e.g., `10`), and `compilerOptions.module` set to `"node16"` or `"nodenext"`. Incorrect configuration can lead to missing type definitions or compilation errors.

fix

Configure your `tsconfig.json` with the recommended `compilerOptions` for optimal JSDoc type inference.

affects: >=8.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import() or an ESM import statement.

Attempting to `require()` the `test-director` package in a CommonJS context after it became ESM-only in v6.0.0.

fix

Change `const TestDirector = require('test-director');` to `import TestDirector from 'test-director';` and ensure your project is configured for ESM.

TypeError: TestDirector is not a constructor

Attempting to instantiate `TestDirector` after importing it incorrectly as a named export (e.g., `import { TestDirector } from 'test-director';`) when it is a default export.

fix

Correct the import statement to use the default import: `import TestDirector from 'test-director';`.

TypeError: Argument 1 'name' must be a string

Calling the `tests.add()` method with a non-string value for the `name` argument, which is strictly enforced since v6.0.0.

fix

Ensure the first argument passed to `tests.add()` is always a string describing the test.

ERR_MODULE_NOT_FOUND: Cannot find module 'test-director/some/deep/path'

Trying to use a deep import path that was reorganized or removed after v5.0.0 due to file structure changes and reliance on the `exports` field.

fix

Review the package's `package.json` `exports` field or README to identify the correct, officially exported path for the module you intend to import.

Upgrade

Version history

11.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/jaydenseric/test-director ↗

packagehttps://www.npmjs.com/package/test-director ↗