power-assert

[![power-assert][power-assert-banner]][power-assert-url]

Power Assert in JavaScript. Provides descriptive assertion messages through standard assert interface. No API is the best API.

[![Build Status][travis-image]][travis-url] [![NPM package][npm-image]][npm-url] [![Bower package][bower-image]][bower-url] [![License][license-image]][license-url]

DESCRIPTION

What is power-assert?

• is an implementation of "Power Assert" concept in JavaScript.
• provides descriptive assertion messages through standard assert interface.
• No API is the best API. With power-assert, you don't need to learn many assertion library APIs (in most cases, all you need to remember is just an assert(any_expression) function)
• Stop memorizing tons of assertion APIs. Just create expressions that return a truthy value or not and power-assert will show it to you right on the screen as part of your failure message without you having to type in a message at all.
• the core value of power-assert is absolute simplicity and stability. Especially, power-assert sticks to the simplest form of testing, assert(any_expression).
• see slides: "power-assert, mechanism and philosophy" -- talk at NodeFest 2014.
• [NEW] Now you don't need require('power-assert') any more. Keep using require('assert'), and power-assert enhances them transparently. See slides: From Library to Tool - power-assert as a General Purpose Assertion Enhancement Tool
• to gain power-assert output, you need to transform your test code to produce power-assert output.
• power-assert - power = assert. Without code transpilation, power-assert works just as normal assert does.
• fully compatible with assert. So you can stop using power-assert and back to assert easily.
• has online demo site.
• works both on server side and browser side.
• available via npm and bower.
• supports sourcemaps so you can debug as usual.
• provides babel plugin and babel preset.
• provides browserify transform.
• provides webpack loader.
• provides grunt task and gulp plugin.
• provides command.
• provides custom module loader and its convenient config module.
• provides Karma Adapter and Karma Preprocessor.
• supports ES6+ through babel plugin.
• supports CoffeeScript.
• supports TypeScript.
• has TypeScript type definition
• has code migration tool that transforms existing code from chai, should.js and expect.js to assert.
• AVA, the futuristic test runner, now comes with power-assert builtin
• has Lab transformer to enable power-assert on Lab
• has module loader to get ts-node working together with power-assert
• Wallaby.js supports power-assert via Babel compiler/preprocessor
• pull-requests, issue reports and patches are always welcomed.

power-assert provides descriptive assertion messages for your tests, like this.

  1) Array #indexOf() should return index when the value is present:
     AssertionError: # path/to/test/mocha_node.js:10

  assert(ary.indexOf(zero) === two)
         |   |       |     |   |
         |   |       |     |   2
         |   -1      0     false
         [1,2,3]

  [number] two
  => 2
  [number] ary.indexOf(zero)
  => -1

API

power-assert enhances these assert functions by espower. Produces descriptive message when assertion is failed.

• 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])

power-assert is fully compatible with assert. So functions below are also available though they are not enhanced (does not produce descriptive message).

• assert.fail(actual, expected, message, operator)
• assert.throws(block, [error], [message])
• assert.doesNotThrow(block, [message])
• assert.ifError(value)

Since version 1.5.0, power-assert supports "strict mode" as well.

power-assert provides an API for customization.

• assert.customize(options)

No API is the best API

Though power-assert is fully compatible with standard assert interface, all you need to remember is just an assert(any_expression) function in most cases.

The core value of power-assert is absolute simplicity and stability. Especially, power-assert sticks to the simplest form of testing, assert(any_expression).

    assert(types[index].name === bob.name)
           |    ||      |    |   |   |
           |    ||      |    |   |   "bob"
           |    ||      |    |   Person{name:"bob",age:5}
           |    ||      |    false
           |    |11     "alice"
           |    Person{name:"alice",age:3}
           ["string",98.6,true,false,null,undefined,#Array#,#Object#,NaN,Infinity,/^not/,#Person#]
  
    --- [string] bob.name
    +++ [string] types[index].name
    @@ -1,3 +1,5 @@
    -bob
    +alice

FAQ

• Support other assertion styles?
• Does this work with substack/tape?
• Are all dependencies required at runtime?
• Descriptive assertion message does not appear when writing tests in ES6 with Babel
• Incomplete increment/decrement assertion messages?
• Cannot capture not invokable method error
• What is the 'Critical dependencies' warning shown by webpack and how to suppress warnings?
• Causes TypeError: assert._capt is not a function
• How to deal with assert calls in production
• Support JSX tags?
• Any tool to migrate should/expect code to power-assert?
• Conflicts with babel-plugin-istanbul?
• power-assert message does not appear in Node8

INSTALL

npm install --save-dev power-assert <one of instrumentors>

or

bower install --save-dev power-assert
npm install --save-dev <one of instrumentors>

see list of instrumentors

CHANGELOG

See CHANGELOG

EXAMPLE

See HOW TO USE section for more details.

Note: There is an online demo site available.

Target test code (using Mocha in this example)

…

Be sure to transform test code

To use power-assert, you need to transform your test code for power-assert output.

Code transform is done by instrumentors below:

• espower-loader (with intelli-espower-loader)
• babel-preset-power-assert
• babel-plugin-espower
• espowerify
• webpack-espower-loader.
• espower-cli
• grunt-espower
• gulp-espower
• karma-espower-preprocessor
• espower-coffee
• [esp