log-interceptor

Intercepts output from console.log()

Usage no npm install needed!

<script type="module">
  import logInterceptor from 'https://cdn.skypack.dev/log-interceptor';
</script>

README

log-interceptor

NPM Version Linux Build Windows Build Test Coverage Dependency Status

Intercepts output from console.log()

This module is very useful if you want to test the output written to console.log. It intercepts the output, allows for a custom callback function to handle the output, and returns all intercepted output when the end() function is called.

Inspired by PHP's Output Control functions and the testcase from jshint-stylish.

Installation

npm install --save log-interceptor

How to use

var logInterceptor = require('log-interceptor');

// start intercepting
logInterceptor();

// output to intercept
console.log('log 1');
console.log('log 2');

// end intercepting
var logs   = logInterceptor.end();
var result = ['log 1\n', 'log 2\n'];

Config options

These options can be used to change the default behavior of a log-interceptor session. You can use it in the logInterceptor() or logInterceptor.config() functions.

option type default description
passDown boolean false Pass the intercepted output down to the next level, or display it when the first level is reached.
stripColors boolean false Strip colors from the intercepted output.
trimTimestamp boolean false Check if the output starts with a timestamp ([00:00:00]). When that's the case, remove it.
trimLinebreak boolean false Trim last linebreak, this will not touch linebreaks somewhere in the middle of the output.
splitOnLinebreak boolean false Split the output and add multiple entries to the end log. Linebreaks on the end of the output will not be used to split.

For more info about the above options, check the associated utility functions.

API

logInterceptor([options][, callbackFn])

Starts the log interceptor. Both the options and callbackFn arguments are optional. When they are both not specified, the default behavior is to intercept the output and return an array with the end() function.

argument type description
options object or boolean Options wich override the default options for this level.
callbackFn function See below for detailed description.

callbackFn(originalStr, formattedStr)

By providing your own custom callback function, you can do whatever you want with the intercepted output. The original and formatted intercepted output strings are provided as the first and second argument.

argument type description
originalStr string The original intercepted output string.
formattedStr array or boolean A formatted version of the intercepted output string, as an array or false when no formatting is applied. When the splitOnLinebreak option is set to true, the array will have multiple values. Otherwise it only has one.

If you want to display the output (with only one level active), or pass it down to a level below, let the callback function return true. If you don't want that, let it return false. When you do not return a value, the default value from the passDown option is used instead.

Example of how to pass down intercepted output to a lower level:

logInterceptor(true);
// wich equals
logInterceptor({ 'passDown': true });
// but also equals
logInterceptor(function()
{
    return true;
});

Example of how you might use a custom callback function:

var customOutputLog = [];
logInterceptor({ 'trimLinebreak': true }, function(str, formatted)
{
    customOutputLog.push([str, formatted]);
    return true;
});

logInterceptor.config(option[, value])

Allows for custom config options to be set to the default config object.

argument type default description
option string The key of the option to add or change.
value boolean true Value will only be used when option is a string. When not set, it defaults to true.

logInterceptor.config(options)

When passing an object, it will be used to extend the default config object.

argument type description
options object The object to extend the default config object with.

logInterceptor.end()

Ends the current intercept session. Returns an array with intercepted output. When no more sessions are active, the original process.stdout.write function is restored.

// start intercept and allow to pass down to `process.stdout.write`
logInterceptor(true);

console.log('log 1');
console.log('log 2');

// end intercepting and restore `process.stdout.write`
var logs   = logInterceptor.end();
var result = ['log 1\n', 'log 2\n'];

logInterceptor.endAll()

Ends all intercept sessions and restores the original process.stdout.write function. Will return an array with all intercepted output from all active sessions that were not already ended, or false when no sessions where active.

// level1
logInterceptor();

console.log('log 1');

// level2: pass output down to level1
logInterceptor(true);

console.log('log 2');
console.log('log 3');

// ends intercepting, returns all output and restores `process.stdout.write`
var logs   = logInterceptor.endAll();
var result = [
    ['log 1\n', 'log 2\n', 'log 3\n'],
    ['log 2\n', 'log 3\n']
];

logInterceptor.write(str)

If you do not want a string to be intercepted while log-interceptor is active, use this function. It is basically a bound reference to the original process.stdout.write. This means by calling this function, the arguments are send to process.stdout.write with process.stdout as it's current scope (just like it should when calling the function without log-interceptor changing stuff).

argument type description
str string The string to write.

Utility functions

The utility functions are available in the logInterceptor.utils object and in the scope of the callback function wich you can pass to logInterceptor(). Ofcourse you can also use these functions in your own custom code.

utils.stripColor(str)

Strips the Ansi colors from the string with strip-ansi and returns the new string.

argument type description
str string The string to strip the colors from.

utils.trimTimestamp(str[, checkColors])

Trims timestamps (eg. [00:00:00]) from the beginning of the string and returns the new string. When checkColors is not false, the function will also check for color coded timestamps wich are created with gulp-util's log function.

argument type default description
str string The string to trim the timestamp from.
checkColors boolean true Set to false if you do not want to check for color coded timestamps.

utils.trimLinebreak(str)

Trims linebreaks (\n) from the end of the string and returns the new string.

argument type description
str string The string to trim the linebreak(s) from.

utils.splitOnLinebreak(str[, trimLinebreaks])

Splits the string on linebreaks (str.split('\n')) not on the end of the string and returns an array.

argument type default description
str string The string to split on linebreak(s).
trimLinebreaks boolean false Set to true if you want to add a single linebreak back to the end of the split lines (all values in the array).

License

GPL-2.0+ © 2015 Roel Schut