tessl/npm-test-console

A simple and pragmatic library for testing Node.js console output.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Test Console

Name: tessl/npm-test-console
Author: tessl

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.

Package Information

Package Name: test-console
Package Type: npm
Language: JavaScript
Installation: npm install test-console

Core Imports

const { stdout, stderr } = require("test-console");

Alternative import pattern:

const stdout = require("test-console").stdout;
const stderr = require("test-console").stderr;

Basic Usage

const { stdout } = require("test-console");

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

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

// Asynchronous capture with manual restore
const inspect = stdout.inspect();
setTimeout(() => {
    console.log("Async output");
    inspect.restore();
    console.log(inspect.output); // ["Async output\n"]
}, 100);

Capabilities

Console Output Inspection

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

/**
 * Redirects writes to stdout into an array instead of writing to console
 * @param {Object} options - Optional configuration
 * @param {boolean} options.isTTY - Override for stdout.isTTY value
 * @returns {Object} inspection object with output array and restore function
 */
function inspect(options);

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

Usage Examples:

const { stdout } = require("test-console");

// Manual restore pattern
const inspect = stdout.inspect();
console.log("foo");
process.stdout.write("bar");
inspect.restore();
// inspect.output: ["foo\n", "bar"]

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

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

// Incremental testing within sync function
stdout.inspectSync(function(output) {
    console.log("first");
    // output: ["first\n"]
    console.log("second");
    // output: ["first\n", "second\n"]
});

Console Output Suppression

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

/**
 * Prevents writes to stdout from appearing on console
 * @param {Object} options - Optional configuration
 * @param {boolean} options.isTTY - Override for stdout.isTTY value  
 * @returns {Function} restore function to restore normal behavior
 */
function ignore(options);

/**
 * Like ignore() but automatically restores console when done
 * @param {Object} options - Optional configuration
 * @param {boolean} options.isTTY - Override for stdout.isTTY value
 * @param {Function} fn - Function to execute while ignoring output
 * @returns {undefined}
 */
function ignoreSync(options, fn);
function ignoreSync(fn); // Options parameter is optional

Usage Examples:

const { stdout } = require("test-console");

// Manual restore pattern
const restore = stdout.ignore();
console.log("This won't appear");
restore();
console.log("This will appear");

// Automatic restore pattern  
stdout.ignoreSync(function() {
    console.log("Suppressed output");
    process.stdout.write("Also suppressed");
});

// Test suite integration
let restoreStdout;

beforeEach(function() {
    restoreStdout = stdout.ignore();
});

afterEach(function() {
    restoreStdout();
});

stderr Support

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

// stderr has identical interface to stdout
const stderr = require("test-console").stderr;

stderr.inspect(options);
stderr.inspectSync(options, fn);
stderr.ignore(options);  
stderr.ignoreSync(options, fn);

Usage Example:

const { stderr } = require("test-console");

const output = stderr.inspectSync(function() {
    console.error("Error message");
    process.stderr.write("Direct error write");
});
// output: ["Error message\n", "Direct error write"]

Types

// Main exports
interface TestConsole {
  stdout: TestStream;
  stderr: TestStream;
}

// TestStream interface (available on both stdout and stderr)
interface TestStream {
  inspect(options?: InspectOptions): InspectResult;
  inspectSync(fn: Function): string[];
  inspectSync(options: InspectOptions, fn: Function): string[];
  ignore(options?: InspectOptions): Function;
  ignoreSync(fn: Function): void;
  ignoreSync(options: InspectOptions, fn: Function): void;
}

// Configuration options
interface InspectOptions {
  isTTY?: boolean; // Override for stream.isTTY value
}

// Inspect result object
interface InspectResult {
  output: string[];     // Array of captured writes
  restore: Function;    // Function to restore original behavior
}

Error Handling

The library throws descriptive Error objects for incorrect usage:

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

Example error messages:

"inspect() doesn't take a function parameter. Did you mean to call inspectSync()?"
"inspectSync() requires a function parameter. Did you mean to call inspect()?"

TTY Behavior

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

// Override isTTY to false
stdout.inspectSync({ isTTY: false }, function() {
    // process.stdout.isTTY will be false during execution
    console.log("TTY disabled");
});

// Original isTTY value is automatically restored after execution

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 3 months ago
Describes: pkg:npm/test-console@1.1.x
Publish Source: CLI
Badge