0
# tap-spec
1
2
tap-spec is a TAP (Test Anything Protocol) output formatter that transforms plain TAP test results into a visually appealing, Mocha-style spec reporter format. It serves as a streaming transform tool that can be piped from TAP-producing test runners like tape, providing colored output with symbols, proper indentation, and timing information.
3
4
## Package Information
5
6
- **Package Name**: tap-spec
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install tap-spec --save-dev`
10
11
## Core Imports
12
13
```javascript
14
const tapSpec = require('tap-spec');
15
```
16
17
For ES modules:
18
19
```javascript
20
import tapSpec from 'tap-spec';
21
```
22
23
## Basic Usage
24
25
### Programmatic Usage
26
27
```javascript
28
const tapSpec = require('tap-spec');
29
const test = require('tape');
30
31
// Create a formatter with default options
32
const formatter = tapSpec();
33
34
// Pipe TAP output through the formatter
35
test.createStream()
36
.pipe(formatter)
37
.pipe(process.stdout);
38
```
39
40
### CLI Usage
41
42
```bash
43
# Via npm scripts in package.json
44
{
45
"scripts": {
46
"test": "tape test.js | tap-spec"
47
}
48
}
49
50
# Direct command line usage
51
tape test/index.js | tap-spec
52
node test.js | tspec
53
54
# With testling
55
testling test/index.js | tap-spec
56
```
57
58
## Capabilities
59
60
### TAP Stream Formatter
61
62
Creates a transform stream that formats TAP input into spec-style output with colors, symbols, and proper indentation.
63
64
```javascript { .api }
65
/**
66
* Creates a TAP formatter transform stream
67
* @param {Object} [spec] - Configuration options
68
* @param {string} [spec.padding=' '] - String used for indenting output lines
69
* @returns {Stream} Transform stream (duplex) that formats TAP input
70
*/
71
function tapSpec(spec) {
72
// Returns a duplex stream with parser input and formatted output
73
}
74
```
75
76
**⚠️ Important Note on Process Termination:**
77
78
When used programmatically, tap-spec may call `process.exit(1)` directly in the following conditions:
79
- No test plans are found in the TAP input (likely upstream failure)
80
- No tests and no assertions are detected (empty test suite or parsing error)
81
82
This means the entire Node.js process will terminate. If you need to handle these conditions gracefully in your application, consider:
83
- Wrapping the stream usage in error handling
84
- Using the `failed` property to detect failures before process termination
85
- Ensuring your TAP input is valid and contains test plans
86
87
**Configuration Options:**
88
89
```javascript { .api }
90
interface TapSpecOptions {
91
/** String used for indenting output lines (default: ' ') */
92
padding?: string;
93
}
94
```
95
96
**Stream Properties:**
97
98
```javascript { .api }
99
interface TapSpecStream extends Stream {
100
/** Set to true when test failures are encountered */
101
failed?: boolean;
102
}
103
```
104
105
**Usage Examples:**
106
107
```javascript
108
const tapSpec = require('tap-spec');
109
110
// Default formatting
111
const defaultFormatter = tapSpec();
112
113
// Custom padding
114
const customFormatter = tapSpec({ padding: ' ' });
115
116
// Check for failures
117
const formatter = tapSpec();
118
tapInput.pipe(formatter).pipe(process.stdout);
119
120
formatter.on('end', () => {
121
if (formatter.failed) {
122
process.exit(1);
123
}
124
});
125
```
126
127
### CLI Commands
128
129
Two equivalent command-line interfaces for formatting TAP output.
130
131
```bash { .api }
132
# Primary command
133
tap-spec
134
135
# Alias command
136
tspec
137
```
138
139
Both commands:
140
- Read TAP input from stdin
141
- Write formatted output to stdout
142
- Exit with status code 1 on test failures
143
- Exit with status code 1 if no tests are found
144
145
**Usage:**
146
147
```bash
148
# Pipe from test runner
149
tape test.js | tap-spec
150
node test.js | tspec
151
152
# Via npm scripts
153
npm test | tap-spec
154
155
# With other TAP producers
156
tap test.js | tap-spec
157
```
158
159
## Output Format
160
161
The formatter produces Mocha-style spec output with:
162
163
- **Test names**: Underlined section headers
164
- **Passing assertions**: Green checkmark (✓) with dimmed assertion name
165
- **Failing assertions**: Red X (✗) with assertion name and error details
166
- **Skipped tests**: Cyan dash (-) with test name (for TAP `# SKIP` directive)
167
- **Comments**: Yellow text for TAP comments
168
- **Summary statistics**: Total assertions, passing count, failing count, and duration
169
- **Failure details**: Detailed error information for failed assertions grouped by test
170
171
**Example Output:**
172
173
```
174
my test suite
175
176
✓ should pass this assertion
177
✓ should also pass this one
178
✗ should fail this assertion
179
-------------------------
180
Error details here...
181
182
Failed Tests: There was 1 failure
183
184
1) my test suite
185
✗ should fail this assertion
186
187
total: 3
188
passing: 2
189
failing: 1
190
duration: 125ms
191
```
192
193
## Error Handling
194
195
**Stream Behavior:**
196
- Stream sets `failed` property to `true` when test failures occur
197
- Handles TAP parsing errors gracefully through the tap-out dependency
198
199
**Process Termination (Both Programmatic and CLI):**
200
- Calls `process.exit(1)` when no test plans are found (upstream failure)
201
- Calls `process.exit(1)` when no tests and no assertions are detected
202
- CLI additionally exits with status code 1 on any test failures
203
204
**Failure Detection:**
205
- Check the `failed` property on the returned stream to detect test failures
206
- Monitor stream events to handle errors before potential process termination
207
208
## Dependencies
209
210
The package relies on several key dependencies that define its functionality:
211
212
- **tap-out**: TAP parser that emits structured events
213
- **through2**: Transform stream implementation
214
- **duplexer**: Combines readable and writable streams
215
- **chalk**: Terminal colors and formatting
216
- **figures**: Unicode symbols (checkmarks, X marks)
217
- **lodash**: Utility functions for data manipulation
218
- **pretty-ms**: Human-readable duration formatting
219
- **repeat-string**: String repetition utilities