or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-test-console

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/test-console@1.1.x

To install, run

npx @tessl/cli install tessl/npm-test-console@1.1.0

index.mddocs/

Test Console

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