empower

Power Assert feature enhancer for assert function/object.

DESCRIPTION

empower is a core module of power-assert family. empower enhances standard assert function or any assert-like object to work with power-assert feature added code instrumented by espower.

empower works with standard assert function (best fit with Mocha), and also supports assert-like objects/functions provided by various testing frameworks such as QUnit, buster.js, and nodeunit.

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

CHANGELOG

See CHANGELOG

API

var enhancedAssert = empower(originalAssert, formatter, [options])

empower function takes function or object(originalAssert) and formatter function created by power-assert-formatter then returns PowerAssert feature added function/object base on originalAssert. If destructive option is falsy, originalAssert will be unchanged. If destructive option is truthy, originalAssert will be manipulated directly and returned enhancedAssert will be the same instance of originalAssert.

originalAssert

originalAssert is an instance of standard assert function or any assert-like object. see SUPPORTED ASSERTION LIBRARIES and ASSERTION LIBRARIES KNOWN TO WORK section. Be careful that originalAssert will be manipulated directly if destructive option is truthy.

formatter

formatter function created by power-assert-formatter.

options

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

options.destructive

If truthy, modify originalAssert destructively.

If false, empower mimics originalAssert as new object/function, so originalAssert will not be changed. If true, originalAssert will be manipulated directly and returned enhancedAssert will be the same instance of originalAssert.

options.modifyMessageOnRethrow

If truthy, modify message property of AssertionError on rethrow.

options.saveContextOnRethrow

If truthy, add powerAssertContext property to AssertionError on rethrow.

modifyMessageOnRethrow option and saveContextOnRethrow option makes behavior matrix as below.

options.patterns

[
    'assert(value, [message])',
    'assert.ok(value, [message])',
    'assert.equal(actual, expected, [message])',
    'assert.notEqual(actual, expected, [message])',
    'assert.strictEqual(actual, expected, [message])',
    'assert.notStrictEqual(actual, expected, [message])',
    'assert.deepEqual(actual, expected, [message])',
    'assert.notDeepEqual(actual, expected, [message])',
    'assert.deepStrictEqual(actual, expected, [message])',
    'assert.notDeepStrictEqual(actual, expected, [message])'
]

Target patterns for power assert feature instrumentation.

Pattern detection is done by escallmatch. Any arguments enclosed in bracket (for example, [message]) means optional parameters. Without bracket means mandatory parameters.

var options = empower.defaultOptions();

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

{
    destructive: false,
    modifyMessageOnRethrow: false,
    saveContextOnRethrow: false,
    patterns: [
        'assert(value, [message])',
        'assert.ok(value, [message])',
        'assert.equal(actual, expected, [message])',
        'assert.notEqual(actual, expected, [message])',
        'assert.strictEqual(actual, expected, [message])',
        'assert.notStrictEqual(actual, expected, [message])',
        'assert.deepEqual(actual, expected, [message])',
        'assert.notDeepEqual(actual, expected, [message])',
        'assert.deepStrictEqual(actual, expected, [message])',
        'assert.notDeepStrictEqual(actual, expected, [message])'
    ]
}

SUPPORTED ASSERTION LIBRARIES

• Node assert API
• Jxck/assert

ASSERTION LIBRARIES KNOWN TO WORK

• QUnit.assert
• nodeunit
• buster-assertions

INSTALL

via npm

Install

$ npm install --save-dev empower

use empower npm module on browser

empower function is exported

<script type="text/javascript" src="./path/to/node_modules/empower/build/empower.js"></script>

via bower

Install

$ bower install --save-dev empower

Then load (empower function is exported)

<script type="text/javascript" src="./path/to/bower_components/empower/build/empower.js"></script>

OUR SUPPORT POLICY

We support Node under maintenance. In other words, we stop supporting old Node version when their maintenance ends.

We also support "modern enough" browsers such as Chrome, Firefox, Safari, Edge etc.

Any other environments are not supported officially (means that we do not test against them on CI service). empower is known to work with old browsers, and trying to keep them working though.

AUTHOR

• Takuto Wada

CONTRIBUTORS

• James Talmage (jamestalmage)

LICENSE

Licensed under the MIT license.

1.3.1 (2018-09-08)

Bug Fixes

• to work well with Jest, treat power-assert message as "not generated" to avoid message override

1.3.0 (2018-06-12)

Features

• set stackStartFunction to self if undefined (8d734cf1)

Chore

• update empower-core to 1.2.0, nothing has changed but has integrated into power-assert-runtime monorepo. (1a3d2f66)

1.2.3 (2017-06-09)

Bug Fixes

• Re-instantiate AssertionError under Node v8 (and v7)

1.2.2 (2017-06-03)

Bug Fixes

• dealing with err.name on Node v8

1.2.1 (2016-06-05)

• remove xtend from dependencies (366f5c9)
• update empower-core to 0.6.1 (9194fe8)

1.2.0 (2016-06-01)

Features

• Extract core functionality to empower-core

1.1.0 (2015-11-07)

Features

• support async-await state flags (by @jamestalmage)

1.0.2 (2015-10-22)

Bug Fixes

• make _capt and _expr methods not enumerable

1.0.1 (2015-09-08)

• apply licensify on build (282259b)

1.0.0 (2015-05-25)

Features

• transfer to power-assert-js organization (0cd9a89a)
• support deepStrictEqual and notDeepStrictEqual (bbaa9121)
• use ponyfills for older browsers (efea6e17)

0.11.0 (2015-04-18)

Features

• empower:
  • ship npm module with built bundle for browsers (e9448d3b)

0.10.0 (2014-11-11)

• empower:
  • update escallmatch (f7a0d970)

0.9.1 (2014-10-07)

Bug Fixes

• empower: power-assert output doesn't appear in Node 0.11.x (53e882e0)

0.9.0 (2014-09-01)

0.8.0 (2014-08-12)

Features

• empower:
  • modularized by browserify
  • use escallmatch module to describe target patterns (533a21a0)
  • support assertion methods with three or more arguments (d31dca86)
  • if not in patterns, do not empower assertion function itself (1d73a756)
  • option targetMethods does not required any more (8ffcc49f)
  • rename saveContextOnFail option to saveContextOnRethrow (1f6133b2)
  • rename modifyMessageOnFail option to modifyMessageOnRethrow (0c8a88f0)

Breaking Changes

• saveContextOnFail option is renamed to saveContextOnRethrow

There is nothing to change unless you are using saveContextOnFail option.

If you are using saveContextOnFail option, change your code from the following:

empower(originalAssert, formatter, {saveContextOnFail: true})

To:

empower(originalAssert, formatter, {saveContextOnRethrow: true})

(1f6133b2)

• modifyMessageOnFail option is renamed to modifyMessageOnRethrow

There is nothing to change unless you are using modifyMessageOnFail option.

If you are using modifyMessageOnFail option, change your code from the following:

empower(originalAssert, formatter, {modifyMessageOnFail: true})

To:

empower(originalAssert, formatter, {modifyMessageOnRethrow: true})

(0c8a88f0)

• option targetMethods does not required any more

If you already customize enhancement pattern using targetMethods, you need to migarte. To migrate, change your code from the following:

var yourAssert = require('./your-assert');
var empower = require('empower');
var formatter = require('power-assert-formatter')();
var options = {
    targetMethods: {
        oneArg: [
            'okay'
        ],
        twoArgs: [
            'equal',
            'customEqual'
        ]
    }
};
var assert = empower(yourAssert, formatter, options);

To:

var yourAssert = require('./your-assert');
var empower = require('empower');
var formatter = require('power-assert-formatter')();
var options = {
    patterns: [
        'yourAssert(value, [message])',
        'yourAssert.okay(value, [message])',
        'yourAssert.equal(actual, expected, [message])',
        'yourAssert.customEqual(actual, expected, [message])'
    ]
};
var assert = empower(yourAssert, formatter, options);

(8ffcc49f)