tsest

中文 |

tsest is a unit test runner script based on node:test, for TypeScript.

Installation

1. Install tsest, npm/pnpm/yarn/cnpm all work

npm install --save-dev tsest @types/node

2. Optional

# Support
npm install -g tsx              # (global tsx)
npm install --save-dev tsx      # (spec tsx)
npm install -g ts-node          # (global ts-node)
npm install --save-dev ts-node  # (spec ts-node)
# or do-nothing                 # (can also install nothing, use node --experimental-strip-types which is still unstable)

3. Edit package.json

4. for tsx/esm

"scripts": {
    "test": "tsx node_modules/tsest/run",
    "watch": "tsx node_modules/tsest/run --watch"
}

2. for tsx/cjs

"scripts": {
    "test": "tsx node_modules/tsest/run-cjs",
    "watch": "tsx node_modules/tsest/run-cjs --watch"
}

Full Configuration

Run

# Run test cases
npm run test
# Watch mode
npm run watch

# Fast execution without type checking
tsx node_modules/tsest/run --watch --root=./src --suffix=.test.ts --test-only
node --experimental-strip-types node_modules/tsest/run --watch --root=./src --suffix=.test.ts --test-only

# Type checking during development
node -r ts-node/register node_modules/tsest/run --watch --root=./src --suffix=.test.ts --test-only

TypeScript Support

tsest supports multiple TypeScript runtime environments:

Runtime	Command Example	Type Checking	Performance
tsx	tsx node_modules/tsest/run	❌	⚡ Fast
Node.js built-in	node --experimental-strip-types node_modules/tsest/run	❌	⚡ Fast
ts-node	node -r ts-node/register node_modules/tsest/run	✅	🐌 Slower

Support Description

node parameter	Support	Note
--watch	✅
--test-only	✅
--test-name-pattern	✅	support alias --name-pattern
--test-skip-pattern	✅	support alias --skip-pattern
--test-concurrency	✅	support alias --concurrency
--no-experimental-strip-types	✅
--experimental-test-coverage	❌
--test-coverage-include	❌
--test-coverage-exclude	❌
--test-reporter	❌
--test-reporter-destination	❌
--test-update-snapshots	❌
--experimental-test-module-mocks	❌

tsest additional support

Parameter	Description
--root	Specify test root directory
--test-file-pattern	Specify test file name pattern , alias --test-file-name, --file-name
--test-file-suffix	Specify test file suffix, alias --file-suffix
--strict	use assert/strict, default is assert/default
--timeout	Timeout, ms
--force-exit	Force exit

API

Using node native API and Assert API, as follows:

import { test } from 'node:test';
import assert from 'node:assert';
import { sum } from './mylib';

test('test case', () => {
    assert.equal(sum(1, 2), 3);
});

tsest provides more convenient equivalent APIs, optimized message prompts, and supports batch and asynchronous features.

import {
    test,                       // test is equivalent to import { test } from 'node:test'
    assert,                     // assert is different from node:assert, with some message optimizations,
                                // run --strict to use node:assert/strict , or use assert:assert.default
                                // if you need to use native assertions, please use node:assert
    equal, equalAsync,          // taking equal as an example, all assertions have 8 methods for async x batch x quick test
    equalBatch, equalBatchAsync,
    testEqual, testEqualAsync,
    testEqualBatch, testEqualBatchAsync,
} from 'tsest';

const sum = (a: number, b: number) => a + b;
const sumAsync = async (a: number, b: number) => new Promise(r => setTimeout(r, 1000, a + b));

test('test case', () => {
    assert.equal(sum(1, 2), 3);
    equal(sum, [1, 2], 3);
    equal(sum, [2, 3], 5);
    equalBatch(sum, [
        [[1, 2], 3],
        [[2, 3], 5],
    ])                      // Batch test, each record is an array
})

test('test async case', async () => {
    // For asynchronous methods, use equalAsync for testing
    // Please note that you need to add the await statement
    await equalAsync(sumAsync, [1, 2], 3);
    await equalAsync(sumAsync, [2, 3], 5);
    await equalBatchAsync(sum, [
        [[1, 2], 3],
        [[2, 3], 5],
    ])                      // Batch test asynchronous methods
})

// Directly test this method
testEqual(sum, [1, 2], 3);

// Directly perform batch testing
testEqualBatch(sum, [
    [[1, 2], 3],
    [[2, 3], 5],
])

// Directly test asynchronous methods
testEqualAsync(sumAsync, [1, 2], 3);

// Directly perform batch testing of asynchronous methods
testEqualBatchAsync(sum, [
    [[1, 2], 3],
    [[2, 3], 5],
])

npm test # or npm run watch
✅ test case (0.6166ms)
✅ test async case (2005.9943ms)
✅ Test [sum] (0.3962ms)
✅ Test [sum] (0.1730ms)
✅ Test [sumAsync] (1012.1937ms)
✅ Test [sum] (0.6077ms)