0
# Test Console
1

2
Test Console is a simple and pragmatic library for testing Node.js console output. It provides utilities to capture, inspect, and suppress stdout/stderr output during testing, with both synchronous and asynchronous APIs for maximum flexibility.
3

4
## Package Information
5

6
- **Package Name**: test-console
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install test-console`
10

11
## Core Imports
12

13
```javascript
14
const { stdout, stderr } = require("test-console");
15
```
16

17
Alternative import pattern:
18

19
```javascript
20
const stdout = require("test-console").stdout;
21
const stderr = require("test-console").stderr;
22
```
23

24
## Basic Usage
25

26
```javascript
27
const { stdout } = require("test-console");
28

29
// Capture console output synchronously
30
const output = stdout.inspectSync(function() {
31
    console.log("Hello World");
32
    process.stdout.write("Direct write");
33
});
34
// output: ["Hello World\n", "Direct write"]
35

36
// Suppress console output during tests
37
stdout.ignoreSync(function() {
38
    console.log("This won't appear");
39
    // No console output during execution
40
});
41

42
// Asynchronous capture with manual restore
43
const inspect = stdout.inspect();
44
setTimeout(() => {
45
    console.log("Async output");
46
    inspect.restore();
47
    console.log(inspect.output); // ["Async output\n"]
48
}, 100);
49
```
50

51
## Capabilities
52

53
### Console Output Inspection
54

55
Capture stdout or stderr writes into arrays for testing verification. Available in both asynchronous (manual restore) and synchronous (automatic restore) variants.
56

57
```javascript { .api }
58
/**
59
 * Redirects writes to stdout into an array instead of writing to console
60
 * @param {Object} options - Optional configuration
61
 * @param {boolean} options.isTTY - Override for stdout.isTTY value
62
 * @returns {Object} inspection object with output array and restore function
63
 */
64
function inspect(options);
65

66
/**
67
 * Like inspect() but automatically restores console when done
68
 * @param {Object} options - Optional configuration  
69
 * @param {boolean} options.isTTY - Override for stdout.isTTY value
70
 * @param {Function} fn - Function to execute while inspecting
71
 * @returns {Array<string>} Array of captured writes
72
 */
73
function inspectSync(options, fn);
74
function inspectSync(fn); // Options parameter is optional
75
```
76

77
**Usage Examples:**
78

79
```javascript
80
const { stdout } = require("test-console");
81

82
// Manual restore pattern
83
const inspect = stdout.inspect();
84
console.log("foo");
85
process.stdout.write("bar");
86
inspect.restore();
87
// inspect.output: ["foo\n", "bar"]
88

89
// Automatic restore pattern
90
const output = stdout.inspectSync(function() {
91
    console.log("test");
92
    process.stdout.write("data");
93
});
94
// output: ["test\n", "data"]
95

96
// With isTTY override
97
const output = stdout.inspectSync({ isTTY: false }, function() {
98
    console.log("TTY disabled");
99
});
100

101
// Incremental testing within sync function
102
stdout.inspectSync(function(output) {
103
    console.log("first");
104
    // output: ["first\n"]
105
    console.log("second");
106
    // output: ["first\n", "second\n"]
107
});
108
```
109

110
### Console Output Suppression
111

112
Prevent stdout or stderr writes from appearing on the console during testing. Useful for suppressing noisy output during test execution.
113

114
```javascript { .api }
115
/**
116
 * Prevents writes to stdout from appearing on console
117
 * @param {Object} options - Optional configuration
118
 * @param {boolean} options.isTTY - Override for stdout.isTTY value  
119
 * @returns {Function} restore function to restore normal behavior
120
 */
121
function ignore(options);
122

123
/**
124
 * Like ignore() but automatically restores console when done
125
 * @param {Object} options - Optional configuration
126
 * @param {boolean} options.isTTY - Override for stdout.isTTY value
127
 * @param {Function} fn - Function to execute while ignoring output
128
 * @returns {undefined}
129
 */
130
function ignoreSync(options, fn);
131
function ignoreSync(fn); // Options parameter is optional
132
```
133

134
**Usage Examples:**
135

136
```javascript
137
const { stdout } = require("test-console");
138

139
// Manual restore pattern
140
const restore = stdout.ignore();
141
console.log("This won't appear");
142
restore();
143
console.log("This will appear");
144

145
// Automatic restore pattern  
146
stdout.ignoreSync(function() {
147
    console.log("Suppressed output");
148
    process.stdout.write("Also suppressed");
149
});
150

151
// Test suite integration
152
let restoreStdout;
153

154
beforeEach(function() {
155
    restoreStdout = stdout.ignore();
156
});
157

158
afterEach(function() {
159
    restoreStdout();
160
});
161
```
162

163
### stderr Support
164

165
All capabilities are available on both stdout and stderr streams with identical APIs.
166

167
```javascript { .api }
168
// stderr has identical interface to stdout
169
const stderr = require("test-console").stderr;
170

171
stderr.inspect(options);
172
stderr.inspectSync(options, fn);
173
stderr.ignore(options);  
174
stderr.ignoreSync(options, fn);
175
```
176

177
**Usage Example:**
178

179
```javascript
180
const { stderr } = require("test-console");
181

182
const output = stderr.inspectSync(function() {
183
    console.error("Error message");
184
    process.stderr.write("Direct error write");
185
});
186
// output: ["Error message\n", "Direct error write"]
187
```
188

189
## Types
190

191
```javascript { .api }
192
// Main exports
193
interface TestConsole {
194
  stdout: TestStream;
195
  stderr: TestStream;
196
}
197

198
// TestStream interface (available on both stdout and stderr)
199
interface TestStream {
200
  inspect(options?: InspectOptions): InspectResult;
201
  inspectSync(fn: Function): string[];
202
  inspectSync(options: InspectOptions, fn: Function): string[];
203
  ignore(options?: InspectOptions): Function;
204
  ignoreSync(fn: Function): void;
205
  ignoreSync(options: InspectOptions, fn: Function): void;
206
}
207

208
// Configuration options
209
interface InspectOptions {
210
  isTTY?: boolean; // Override for stream.isTTY value
211
}
212

213
// Inspect result object
214
interface InspectResult {
215
  output: string[];     // Array of captured writes
216
  restore: Function;    // Function to restore original behavior
217
}
218
```
219

220
## Error Handling
221

222
The library throws descriptive Error objects for incorrect usage:
223

224
- `inspect()` and `ignore()` called with function parameters throw errors suggesting to use the Sync versions
225
- `inspectSync()` and `ignoreSync()` called without function parameters or with wrong argument counts throw errors
226

227
**Example error messages:**
228
- `"inspect() doesn't take a function parameter. Did you mean to call inspectSync()?"`
229
- `"inspectSync() requires a function parameter. Did you mean to call inspect()?"`
230

231
## TTY Behavior
232

233
The `isTTY` option allows mocking of the stream's TTY status for testing TTY-dependent behavior:
234

235
```javascript
236
// Override isTTY to false
237
stdout.inspectSync({ isTTY: false }, function() {
238
    // process.stdout.isTTY will be false during execution
239
    console.log("TTY disabled");
240
});
241

242
// Original isTTY value is automatically restored after execution
243
```