0
# Test
1
2
The `test` package provides a complete port of Node.js 18's experimental test runner (`node:test`) that works with Node.js 14+. It offers a comprehensive testing framework with minimal dependencies, supporting synchronous functions, Promise-based async functions, and callback-based functions for test execution.
3
4
## Package Information
5
6
- **Package Name**: test
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install test`
10
11
## Core Imports
12
13
```javascript
14
import test, { describe, it, before, after, beforeEach, afterEach, run, mock } from "test";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const test = require("test");
21
const { describe, it, before, after, beforeEach, afterEach, run, mock } = require("test");
22
```
23
24
## Basic Usage
25
26
```javascript
27
import test, { describe, it, beforeEach } from "test";
28
29
// Simple test
30
test("should add numbers correctly", (t) => {
31
const result = 2 + 3;
32
if (result !== 5) {
33
throw new Error(`Expected 5, got ${result}`);
34
}
35
});
36
37
// Test suite with hooks
38
describe("Calculator tests", () => {
39
beforeEach(() => {
40
console.log("Setting up test");
41
});
42
43
it("should multiply correctly", () => {
44
const result = 4 * 5;
45
if (result !== 20) {
46
throw new Error(`Expected 20, got ${result}`);
47
}
48
});
49
});
50
51
// Async test
52
test("async operation", async (t) => {
53
const result = await Promise.resolve(42);
54
if (result !== 42) {
55
throw new Error(`Expected 42, got ${result}`);
56
}
57
});
58
```
59
60
## Architecture
61
62
The test package is built around several key components:
63
64
- **Core Test Functions**: `test`, `describe`, and `it` functions for organizing and running tests
65
- **Test Context System**: Context objects passed to test functions providing diagnostic and control capabilities
66
- **Hook System**: Lifecycle hooks (`before`, `after`, `beforeEach`, `afterEach`) for test setup and teardown
67
- **Test Runner**: Programmatic runner for executing test files with configurable options
68
- **Mocking System**: Comprehensive function and method mocking with call tracking and implementation control
69
- **CLI Tools**: Command-line utilities for various testing scenarios with TAP output support
70
71
## Capabilities
72
73
### Core Testing Functions
74
75
Primary test definition functions for creating individual tests and organizing them into suites. Supports multiple execution patterns and configuration options.
76
77
```javascript { .api }
78
function test(name: string, options: TestOptions, fn: TestFn): void;
79
function test(name: string, fn: TestFn): void;
80
function test(options: TestOptions, fn: TestFn): void;
81
function test(fn: TestFn): void;
82
83
function describe(name: string, options: TestOptions, fn: SuiteFn): void;
84
function describe(name: string, fn: SuiteFn): void;
85
function describe(options: TestOptions, fn: SuiteFn): void;
86
function describe(fn: SuiteFn): void;
87
88
function it(name: string, options: TestOptions, fn: ItFn): void;
89
function it(name: string, fn: ItFn): void;
90
function it(options: TestOptions, fn: ItFn): void;
91
function it(fn: ItFn): void;
92
93
interface TestOptions {
94
concurrency?: boolean | number;
95
skip?: boolean | string;
96
todo?: boolean | string;
97
timeout?: number;
98
signal?: AbortSignal;
99
}
100
```
101
102
[Core Testing Functions](./core-testing.md)
103
104
### Test Lifecycle Hooks
105
106
Hook functions that run at specific points in the test lifecycle for setup and teardown operations.
107
108
```javascript { .api }
109
function before(fn: () => void | Promise<void>, options?: { signal?: AbortSignal, timeout?: number }): void;
110
function after(fn: () => void | Promise<void>, options?: { signal?: AbortSignal, timeout?: number }): void;
111
function beforeEach(fn: () => void | Promise<void>, options?: { signal?: AbortSignal, timeout?: number }): void;
112
function afterEach(fn: () => void | Promise<void>, options?: { signal?: AbortSignal, timeout?: number }): void;
113
```
114
115
[Test Lifecycle Hooks](./hooks.md)
116
117
### Test Runner
118
119
Programmatic test runner for executing test files with advanced configuration options including concurrency, timeouts, and custom reporters.
120
121
```javascript { .api }
122
function run(options?: RunOptions): TestsStream;
123
124
interface RunOptions {
125
concurrency?: number;
126
timeout?: number;
127
signal?: AbortSignal;
128
files?: string[];
129
inspectPort?: number;
130
}
131
```
132
133
[Test Runner](./runner.md)
134
135
### Mocking System
136
137
Comprehensive mocking system for functions and object methods with call tracking, implementation control, and restoration capabilities.
138
139
```javascript { .api }
140
const mock: MockTracker;
141
142
interface MockTracker {
143
fn(original?: Function, implementation?: Function, options?: MockOptions): MockFunctionContext;
144
method(object: object, methodName: string, implementation?: Function, options?: MethodMockOptions): MockFunctionContext;
145
getter(object: object, methodName: string, implementation?: Function, options?: MockOptions): MockFunctionContext;
146
setter(object: object, methodName: string, implementation?: Function, options?: MockOptions): MockFunctionContext;
147
reset(): void;
148
restoreAll(): void;
149
}
150
```
151
152
[Mocking System](./mocking.md)
153
154
## Types
155
156
```javascript { .api }
157
type TestFn = (t: TestContext) => any | Promise<any>;
158
type SuiteFn = (t: SuiteContext) => void;
159
type ItFn = (t: ItContext) => any | Promise<any>;
160
161
interface TestContext {
162
test(name: string, options: TestOptions, fn: TestFn): Promise<void>;
163
test(name: string, fn: TestFn): Promise<void>;
164
test(fn: TestFn): Promise<void>;
165
diagnostic(message: string): void;
166
skip(message?: string): void;
167
todo(message?: string): void;
168
signal: AbortSignal;
169
}
170
171
interface SuiteContext {
172
signal: AbortSignal;
173
}
174
175
interface ItContext {
176
signal: AbortSignal;
177
}
178
```