power-assert-formatter

What is power-assert-formatter?

The power-assert-formatter npm package is a tool used to format assertion messages in a more readable and expressive way. It is part of the power-assert family, which aims to provide better assertion messages for JavaScript testing.

What are power-assert-formatter's main functionalities?

Customizable Output

This feature allows you to customize the output of assertion messages. You can set options like `lineDiffThreshold` and `maxDepth` to control how detailed the output should be.

const assert = require('assert');
const formatter = require('power-assert-formatter');

const options = {
  lineDiffThreshold: 5,
  maxDepth: 3
};
const format = formatter(options);

try {
  assert.equal(1, 2);
} catch (e) {
  console.log(format(e));
}

Enhanced Assertion Messages

This feature enhances the default assertion messages to make them more readable and informative. It provides a clear and detailed explanation of why the assertion failed.

const assert = require('assert');
const formatter = require('power-assert-formatter');

const format = formatter();

try {
  assert.strictEqual(1, 2);
} catch (e) {
  console.log(format(e));
}

Integration with Testing Frameworks

This feature allows you to integrate power-assert-formatter with popular testing frameworks like Mocha. It helps in providing better assertion messages within the context of your tests.

const assert = require('assert');
const formatter = require('power-assert-formatter');
const mocha = require('mocha');

const format = formatter();

mocha.describe('Sample Test', function() {
  mocha.it('should fail', function() {
    try {
      assert.strictEqual(1, 2);
    } catch (e) {
      console.log(format(e));
    }
  });
});

Other packages similar to power-assert-formatter

chai

Chai is a BDD / TDD assertion library for node and the browser that can be delightfully paired with any JavaScript testing framework. It provides a variety of assertion styles and is known for its flexibility and ease of use.

should

Should.js is an expressive, readable, and powerful assertion library for node and the browser. It extends the Object prototype with a single non-enumerable getter that allows you to express assertions in a natural language style.

expect

Expect is a simple assertion library for JavaScript that works with any test framework. It provides a clean and readable syntax for writing assertions and is often used with Jest.

README

power-assert-formatter

Power Assert output formatter.

DESCRIPTION

power-assert-formatter is a formatter module for Power Assert output.

Pull-requests, issue reports and patches are always welcomed. See power-assert project for more documentation.

CHANGELOG

See CHANGELOG

API

var createFormatter = require('power-assert-formatter');

return type
function

Returns creator function for power-assert.

var formatter = createFormatter([options]);

return type
function

Create formatter function with options. options argument is optional.

options

type	default value
object	(return value of createFormatter.defaultOptions())

Configuration options. If not passed, default options will be used.

options.lineDiffThreshold

type	default value
number	5

Threshold to show diff at character level or line level. If number of lines in target string is greater than lineDiffThreshold, then line diff mode will be used to show diff output.

options.maxDepth

type	default value
number	1

Depth of object traversal. If object depth is greater than maxDepth, compound object (IOW, Array or object) will be pruned with # like ["foo",#Array#,#Object#].

options.outputOffset

type	default value
number	2

Number of spaces inserted at the left in power-assert output.

options.anonymous

type	default value
string	"Object"

Type name to show when target object is created by anonymous constructor.

options.circular

type	default value
string	"#@Circular#"

Name to show when target object is detected as circular structure.

options.lineSeparator

type	default value
string	"\n"

Line separator in power assert output.

options.ambiguousEastAsianCharWidth

type	default value
number	2

Width of 'Ambiguous' characters defined in Unicode Standard Annex #11 EAST ASIAN WIDTH. Configure options.ambiguousEastAsianCharWidth to treat ambiguous east asian character as fullwidth (= 2) or narrow (= 1). Default is 2.

options.widthOf

type	default value
function	string-width.js

Function to calculate width of string.

options.stringify

type	default value
function	stringifier module

Function to stringify any target value.

options.diff

type	default value
function	udiff.js

Function to create diff string between two strings.

options.writerClass

type	default value
function	string-writer.js

Constructor Function for output writer class.

options.renderers

type	default value
Array of (string or function )	shown below

[
    './built-in/file',
    './built-in/assertion',
    './built-in/diagram',
    './built-in/binary-expression'
]

Output renderers. Power assert output is rendered by renderers in order. You can create custom renderer and add its constructor function to customize power-assert-output.

[
    './built-in/file',
    './built-in/assertion',
    YourCustomRenderer,
    './built-in/binary-expression'
]

var options = createFormatter.defaultOptions();

Returns default options object for createFormatter function. In other words, returns

{
    lineDiffThreshold: 5,
    maxDepth: 1,
    anonymous: 'Object',
    circular: '#@Circular#',
    lineSeparator: '\n',
    ambiguousEastAsianCharWidth: 2,
    renderers: [
        './built-in/file',
        './built-in/assertion',
        './built-in/diagram',
        './built-in/binary-expression'
    ]
};

var formattedText = formatter(powerAssertContext);

return type
string

Format powerAssertContext into formattedText. powerAssertContext is an internal object structure, containing informations to render. Example of powerAssertContext is:

{
    source: {
        content: "assert.equal(foo, bar)",
        filepath: "/path/to/some_test.js",
        line: 1
    },
    args: [
        {
            value: "foo",
            events: [
                {
                    value: "foo",
                    espath: "arguments/0"
                }
            ]
        },
        {
            value: "bar",
            events: [
                {
                    value: "bar",
                    espath: "arguments/1"
                }
            ]
        }
    ]
}

Note that structure of powerAssertContext may change.

INSTALL

via npm

Install

$ npm install --save-dev power-assert-formatter

use power-assert-formatter npm module on browser

powerAssertFormatter function is exported

<script type="text/javascript" src="./path/to/node_modules/power-assert-formatter/build/power-assert-formatter.js"></script>

via bower

Install

$ bower install --save-dev power-assert-formatter

Then load (powerAssertFormatter function is exported)

<script type="text/javascript" src="./path/to/bower_components/power-assert-formatter/build/power-assert-formatter.js"></script>

AUTHOR

• Takuto Wada

CONTRIBUTORS

• James Talmage (jamestalmage)

LICENSE

Licensed under the MIT license.