0
# TAP (Test-Anything-Protocol)
1
2
TAP is a comprehensive Test-Anything-Protocol testing framework for Node.js, built with TypeScript and providing both ESM and CommonJS support. It combines a command-line test runner with a JavaScript framework for writing test scripts, featuring a powerful plugin system where almost all functionality is implemented as plugins.
3
4
## Package Information
5
6
- **Package Name**: tap
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install tap`
10
- **Documentation**: http://www.node-tap.org/
11
12
## Core Imports
13
14
```typescript
15
import { t } from "tap";
16
// or
17
import tap from "tap";
18
```
19
20
For individual imports:
21
22
```typescript
23
import { test, ok, same, throws } from "tap";
24
```
25
26
CommonJS:
27
28
```javascript
29
const { t } = require("tap");
30
// or
31
const tap = require("tap");
32
```
33
34
## Basic Usage
35
36
```typescript
37
import { test } from "tap";
38
39
// Basic test with assertions
40
test("basic math", (t) => {
41
t.ok(2 + 2 === 4, "addition works");
42
t.same({ a: 1 }, { a: 1 }, "objects are equal");
43
t.end();
44
});
45
46
// Async test
47
test("async operations", async (t) => {
48
const result = await someAsyncFunction();
49
t.ok(result.success, "async operation succeeded");
50
});
51
52
// Test with plan
53
test("planned test", (t) => {
54
t.plan(2);
55
t.ok(true, "first assertion");
56
t.ok(true, "second assertion");
57
});
58
```
59
60
## Architecture
61
62
TAP is built around several key architectural concepts:
63
64
- **Plugin System**: Almost all functionality is implemented as plugins that extend the core TAP functionality
65
- **Test Isolation**: Each test runs in its own process to prevent test interference
66
- **Type Safety**: Complete TypeScript integration with plugin-aware types
67
- **Dual Module Support**: Works seamlessly with both ESM and CommonJS
68
- **TAP Protocol**: Outputs standard Test Anything Protocol format
69
- **Built-in Coverage**: Automatic code coverage analysis with configurable thresholds
70
71
## Main Export
72
73
The primary interface is the `t` object, which is a TAP instance providing all testing functionality:
74
75
```typescript { .api }
76
const t: TAP;
77
```
78
79
## Core Types
80
81
```typescript { .api }
82
interface TAP {
83
// Test organization methods
84
test(name: string, fn?: TestFunction): Promise<void>;
85
test(name: string, options: TestOpts, fn?: TestFunction): Promise<void>;
86
87
// Basic assertions (using MessageExtra pattern)
88
ok(value: any, ...[msg, extra]: MessageExtra): boolean;
89
notOk(value: any, ...[msg, extra]: MessageExtra): boolean;
90
pass(...[msg, extra]: MessageExtra): boolean;
91
fail(...[msg, extra]: MessageExtra): boolean;
92
93
// Test control
94
plan(count: number): void;
95
end(): void;
96
bailout(reason?: string): void;
97
timeout(ms: number): void;
98
}
99
100
interface TestOpts {
101
name?: string;
102
timeout?: number;
103
skip?: boolean | string;
104
todo?: boolean | string;
105
only?: boolean;
106
}
107
108
type MessageExtra = [] | [msg: string, extra?: Extra] | [extra: Extra];
109
110
interface Extra {
111
[key: string]: any;
112
compareOptions?: CompareOptions;
113
}
114
115
type TestFunction = (t: TAP) => void | Promise<void>;
116
```
117
118
## Capabilities
119
120
### Assertions
121
122
Comprehensive assertion library with deep equality, pattern matching, type checking, error handling, and promise testing. Includes over 30 assertion methods with TypeScript type guards and flexible parameter patterns.
123
124
```typescript { .api }
125
// Basic assertions (using MessageExtra pattern)
126
function ok(value: any, ...[msg, extra]: MessageExtra): boolean;
127
function same(found: any, wanted: any, ...[msg, extra]: MessageExtra): boolean;
128
function equal<T>(found: any, wanted: T, ...[msg, extra]: MessageExtra): found is T;
129
function throws(fn: Function | (() => any), ...[wanted, msg, extra]: ThrowsArgs): boolean | Error;
130
function rejects<T>(fnOrPromise: (() => Promise<T>) | Promise<T>, ...[wanted, msg, extra]: ThrowsArgs): Promise<boolean | Error>;
131
```
132
133
[Assertions](./assertions.md)
134
135
### Test Organization
136
137
Test creation, skipping, planning, and control flow management for organizing test suites.
138
139
```typescript { .api }
140
function test(name: string, fn?: TestFunction): Promise<void>;
141
function skip(name: string, fn?: TestFunction): Promise<void>;
142
function todo(name: string, fn?: TestFunction): Promise<void>;
143
function plan(count: number): void;
144
```
145
146
[Test Organization](./test-organization.md)
147
148
### Lifecycle Hooks
149
150
Before and after hooks for test setup and teardown at multiple levels.
151
152
```typescript { .api }
153
function before(fn: () => void | Promise<void>): void;
154
function after(fn: () => void | Promise<void>): void;
155
function beforeEach(fn: () => void | Promise<void>): void;
156
function afterEach(fn: () => void | Promise<void>): void;
157
```
158
159
[Lifecycle Hooks](./lifecycle-hooks.md)
160
161
### Mocking and Interception
162
163
Module mocking, function interception, and call capturing for isolating tests.
164
165
```typescript { .api }
166
function mockRequire(module: string, mocks?: any): void;
167
function mockImport(module: string, mocks?: any): Promise<void>;
168
function intercept(object: any, property: string, options?: InterceptOpts): void;
169
```
170
171
[Mocking and Interception](./mocking.md)
172
173
### Subprocess Testing
174
175
Test external processes, worker threads, and stdin/stdout interactions.
176
177
```typescript { .api }
178
function spawn(cmd: string, args?: string[], options?: SpawnOpts, name?: string): Promise<void>;
179
function worker(file: string, options?: WorkerOpts, name?: string): Promise<void>;
180
function stdin(input: string, options?: StdinOpts, name?: string): Promise<void>;
181
```
182
183
[Subprocess Testing](./subprocess-testing.md)
184
185
## Plugin System
186
187
TAP uses a plugin-based architecture where functionality is modular:
188
189
**Core Plugins** (automatically loaded):
190
- `@tapjs/asserts` - All assertion methods
191
- `@tapjs/core` - Core TAP functionality and base classes
192
- `@tapjs/test` - Main Test class
193
- `@tapjs/filter` - Test filtering (`only` method)
194
- `@tapjs/before` / `@tapjs/after` - Lifecycle hooks
195
- `@tapjs/mock` - Module mocking system
196
- `@tapjs/intercept` - Function/method interception
197
- `@tapjs/spawn` / `@tapjs/worker` / `@tapjs/stdin` - Subprocess testing
198
- `@tapjs/snapshot` - Snapshot testing
199
- `@tapjs/fixture` - Test fixture management
200
- `@tapjs/typescript` - TypeScript support
201
202
The plugin system ensures that types are dynamically updated based on loaded plugins, and functionality is conditionally available based on plugin configuration.
203
204
## CLI Usage
205
206
TAP includes a command-line test runner:
207
208
```bash
209
# Run all tests
210
tap
211
212
# Run specific test files
213
tap test/*.js
214
215
# Run with coverage
216
tap --coverage
217
218
# Watch mode
219
tap --watch
220
221
# TypeScript files
222
tap test/*.ts
223
```
224
225
The CLI automatically handles TypeScript compilation, coverage analysis, and TAP output formatting.