clean-tests ✅️

A lightweight, zero-overhead test library for writing tests as ordinary ECMAScript/TypeScript code with explicit dependencies.

A test suite is an ordinary instance of the Suite class. Tests are added using suite.addTest method, may be exported like any other ECMAScript value, and are executed by calling suite.run() method.

The tests are run in the same thread as the suite.run call, but in an isolated scope, meaning that variables from the closure will not be available inside the test code. To access the utilities, asserts, and functions being tested in the suite, we explicitly add them as functions to the suite scope using the suite.addFunctionToScope method.

A test is considered to have failed if it throws an exception (or if the promise it returns is rejected — for example, for asynchronous functions).

Why clean-tests ✅️?

• Ordinary ECMAScript/TypeScript — a test suite is an ordinary ECMAScript/TypeScript program built from regular classes, functions, objects, and method calls.

• Isolated test scope — each test runs in its own lexical scope and only sees functions that were intentionally added to the suite scope.

• Explicit dependencies — every dependency is explicit, reducing hidden coupling and accidental shared state.

• Zero runtime overhead — tests run in the same thread, worker, and Realm. Isolation is achieved without processes, workers, or VM sandboxes.

• Works everywhere — any environment implementing ECMAScript 2022 or later (node, browsers, Deno, Bun, ...).

• Designed for extension — customize behavior using ordinary ECMAScript/TypeScript inheritance and method overriding.

• Zero dependencies.

Basic example

import {assertValueIsTrue, Suite} from 'clean-tests';
import {sum} from './sum.js';

const suite = new Suite();

suite.addFunctionToScope(assertValueIsTrue);
suite.addFunctionToScope(sum);

suite.addTest('adds 1 + 2 to equal 3', () => {
  assertValueIsTrue(sum(1, 2) === 3);
});

const runResult = await suite.run();

assertValueIsTrue(runResult.runStatus === 'passed');

Features

Skip tests

You can skip a specific test by giving it the skip option:

suite.addTest('skipped', {skip: true}, () => {
  // this code will never run
});

suite.addTest('skipped with reason', {skip: 'some reason'}, () => {
  // this code will never run
});

Todo tests

The test can be marked as a todo test — in this case it will be run, but will not affect the runStatus:

suite.addTest('todo test', {todo: true}, () => {
  // some code
});

suite.addTest('todo test with reason', {todo: 'some reason'}, () => {
  // some code
});

Only tests

The test can be marked as an only test — in this case, only tests marked as only (there may be several of them) will be run, regardless of filtering of tests:

suite.addTest('only test', {only: true}, () => {
  // some code
});

Fail tests

The test can be marked as a fail test — in this case the test will be considered passed if it throws (or rejects the returned promise), and failed otherwise:

suite.addTest('fail test', {fail: true}, () => {
  throw new Error('should throw');
});

Filtering of tests

Tests in suite.run can be filtered using the filterTests function (filtering is ignored if there is at least one only test in the suite):

suite.addTest('foo', () => {
  // some code
});

suite.addTest('bar', () => {
  // some code
});

// will run only the test named 'foo'
const runResult = await suite.run({filterTests: (_options, test) => test.name === 'foo'});

The default filter of tests can be set when creating a suite (the filter specified in suite.run will override it):

// run only tests configured with retries (i.e. tests that will be rerun if they fail)
const suite = new Suite({filterTests: (_options, test) => test.retries > 0});

Asynchronous tests

If a test returns a promise (usually by being an asynchronous function), clean-tests ✅️ waits for it to be fulfilled. Such a test is considered to have failed if the promise is rejected:

suite.addTest('asynchronous test', async () => {
  await new Promise((resolve) => setTimeout(resolve, 1_000));
});

For asynchronous tests you can specify a timeout in milliseconds, after which the test will be considered failed:

suite.addTest('asynchronous test', {timeout: 1_000}, async () => {
  await new Promise((resolve) => setTimeout(resolve, 2_000));
});

The default timeout for each test can be set when creating the suite (the timeout specified in suite.run will override it):

const suite = new Suite({testTimeout: 3_000});

By default testTimeout is 10_000 (10 seconds).

For asynchronous tests, you can specify concurrency (how many of them can be run at the same time at most):

const runResult = await suite.run({concurrency: 3});

The default concurrency can be set when creating a suite (the concurrency specified in suite.run will override it):

const suite = new Suite({concurrency: 3});

By default concurrency is 1.

Output

By default, test results are printed in the TAP (Test Anything Protocol) format.

Output is produced through the suite's print method, which defaults to globalThis.console.log:

const suite = new Suite();

suite.print === globalThis.console.log;

The print method can be overridden in the suite options:

const suite = new Suite({
  print: (message) => {
    // custom output
  },
});

or for a particular run:

await suite.run({
  print: (message) => {
    // custom output
  },
});

The default TAP output is implemented by the onSuiteStart, onTestEnd and onSuiteEnd handlers. Overriding these handlers makes it possible to customize or completely replace the output.

Event handlers

clean-tests ✅️ provides four event handlers that can be used to observe and customize the test run lifecycle.

The default reporting behavior, including TAP output, is implemented entirely through these handlers.

Event handlers can be specified either in the suite options or for a particular run. Alternatively, subclasses may override these methods to customize the suite behavior and optionally call the default implementation using super.

onSuiteStart

Called once before any tests are started. The handler receives the effective run options. The default implementation prints the TAP header.

const suite = new Suite({
  onSuiteStart(options) {
    // some code
  },
});

onTestStart

Called immediately before each test is started. The handler receives the effective run options and information about the test being started. The default implementation does nothing.

const suite = new Suite({
  onTestStart(options, event) {
    // some code
  },
});

onTestEnd

Called immediately after each test finishes. The handler receives the effective run options and information about the completed test, including its result. The default implementation prints the TAP output for the completed test. Overriding this handler makes it possible to customize or completely replace the output.

const suite = new Suite({
  onTestEnd(options, event) {
    // some code
  },
});

onSuiteEnd

Called once after all tests have finished. The handler receives the effective run options and the final run result. The default implementation prints the final TAP summary. Overriding this handler makes it possible to customize or completely replace the output.

const suite = new Suite({
  onSuiteEnd(options, runResult) {
    // some code
  },
});

Both onSuiteStart and onSuiteEnd may be asynchronous. If they return a promise, clean-tests ✅️ waits for it to be fulfilled before continuing.

Install

Works in any environment that implements the ECMAScript 2022 standard (or higher): modern browser, node (version 16 or higher), Deno, Bun.

npm install --save-dev clean-tests

License

MIT