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

Power Assert in JavaScript. Provides descriptive assertion messages through standard [assert](https://nodejs.org/api/assert.html) 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]
[![Dependency Status][depstat-image]][depstat-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](https://nodejs.org/api/assert.html) 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"](https://www.slideshare.net/t_wada/power-assert-nodefest-2014) -- 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](https://speakerdeck.com/twada/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](https://nodejs.org/api/assert.html). So you can stop using power-assert and back to assert easily.
 * has [online demo site](https://azu.github.io/power-assert-demo/).
 * works both on server side and browser side.
 * available via [npm](https://www.npmjs.com/package/power-assert) and [bower](https://bower.io/search/?q=power-assert). 
 * supports sourcemaps so you can debug as usual.
 * provides [babel plugin](https://github.com/power-assert-js/babel-plugin-espower) and [babel preset](https://github.com/power-assert-js/babel-preset-power-assert).
 * provides [browserify transform](https://github.com/power-assert-js/espowerify).
 * provides [webpack loader](https://github.com/power-assert-js/webpack-espower-loader).
 * provides [grunt task](https://github.com/power-assert-js/grunt-espower) and [gulp plugin](https://github.com/power-assert-js/gulp-espower).
 * provides [command](https://github.com/power-assert-js/espower-cli).
 * provides [custom module loader](https://github.com/power-assert-js/espower-loader) and its [convenient config module](https://github.com/power-assert-js/intelli-espower-loader).
 * provides [Karma Adapter](https://github.com/power-assert-js/karma-power-assert) and [Karma Preprocessor](https://github.com/power-assert-js/karma-espower-preprocessor).
 * supports ES6+ through [babel plugin](https://github.com/power-assert-js/babel-plugin-espower).
 * supports [CoffeeScript](https://github.com/power-assert-js/espower-coffee).
 * supports [TypeScript](https://github.com/power-assert-js/espower-typescript).
 * has [TypeScript type definition](https://www.npmjs.com/package/@types/power-assert)
 * has code migration tool that transforms existing code from [chai](https://github.com/twada/chai-to-assert), [should.js](https://github.com/node-modules/should2assert) and [expect.js](https://github.com/twada/expect-js-to-assert) to assert.
 * [AVA](https://github.com/avajs/ava), the futuristic test runner, now [comes with power-assert builtin](https://github.com/avajs/ava#enhanced-assertion-messages)
 * has [Lab transformer](https://github.com/feugy/lab-espower-transformer) to enable power-assert on [Lab](https://github.com/hapijs/lab)
 * has [module loader](https://github.com/tracecomms/espower-ts-node) to get [ts-node](https://github.com/TypeStrong/ts-node) working together with power-assert
 * [Wallaby.js](https://wallabyjs.com/) supports power-assert via [Babel compiler/preprocessor](https://github.com/wallabyjs/public/issues/754#issuecomment-241624868)
 * 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](https://github.com/power-assert-js/espower). Produces descriptive message when assertion is failed.

* [`assert(value, [message])`](https://nodejs.org/api/assert.html#assert_assert_value_message)
* [`assert.ok(value, [message])`](https://nodejs.org/api/assert.html#assert_assert_ok_value_message)
* [`assert.equal(actual, expected, [message])`](https://nodejs.org/api/assert.html#assert_assert_equal_actual_expected_message)
* [`assert.notEqual(actual, expected, [message])`](https://nodejs.org/api/assert.html#assert_assert_notequal_actual_expected_message)
* [`assert.strictEqual(actual, expected, [message])`](https://nodejs.org/api/assert.html#assert_assert_strictequal_actual_expected_message)
* [`assert.notStrictEqual(actual, expected, [message])`](https://nodejs.org/api/assert.html#assert_assert_notstrictequal_actual_expected_message)
* [`assert.deepEqual(actual, expected, [message])`](https://nodejs.org/api/assert.html#assert_assert_deepequal_actual_expected_message)
* [`assert.notDeepEqual(actual, expected, [message])`](https://nodejs.org/api/assert.html#assert_assert_notdeepequal_actual_expected_message)
* [`assert.deepStrictEqual(actual, expected, [message])`](https://nodejs.org/api/assert.html#assert_assert_deepstrictequal_actual_expected_message)
* [`assert.notDeepStrictEqual(actual, expected, [message])`](https://nodejs.org/api/assert.html#assert_assert_notdeepstrictequal_actual_expected_message)

power-assert is fully compatible with [assert](https://nodejs.org/api/assert.html). So functions below are also available though they are not enhanced (does not produce descriptive message).

* [`assert.fail(actual, expected, message, operator)`](https://nodejs.org/api/assert.html#assert_assert_fail_actual_expected_message_operator_stackstartfunction)
* [`assert.throws(block, [error], [message])`](https://nodejs.org/api/assert.html#assert_assert_throws_block_error_message)
* [`assert.doesNotThrow(block, [message])`](https://nodejs.org/api/assert.html#assert_assert_doesnotthrow_block_error_message)
* [`assert.ifError(value)`](https://nodejs.org/api/assert.html#assert_assert_iferror_value)

Since version 1.5.0, power-assert supports ["strict mode"](https://nodejs.org/api/assert.html#assert_strict_mode) as well.

power-assert provides an [API for customization](https://github.com/power-assert-js/power-assert#customization-api).

* `assert.customize(options)`


### No API is the best API

Though power-assert is fully compatible with standard [assert](https://nodejs.org/api/assert.html) 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?](https://github.com/power-assert-js/power-assert/issues/22)
- [Does this work with substack/tape?](https://github.com/power-assert-js/power-assert/issues/30)
- [Are all dependencies required at runtime?](https://github.com/power-assert-js/power-assert/issues/24)
- [Descriptive assertion message does not appear when writing tests in ES6 with Babel](https://github.com/power-assert-js/webpack-espower-loader/issues/4#issuecomment-139605343)
- [Incomplete increment/decrement assertion messages?](https://github.com/power-assert-js/power-assert/issues/32)
- [Cannot capture not invokable method error](https://github.com/power-assert-js/power-assert/issues/36)
- What is the ['Critical dependencies' warning shown by webpack](https://github.com/power-assert-js/babel-plugin-espower/issues/14#issuecomment-197272436) and how to [suppress warnings](https://github.com/power-assert-js/babel-plugin-espower/issues/14#issuecomment-197909419)?
- [Causes `TypeError: assert._capt is not a function`](https://github.com/power-assert-js/power-assert/issues/42)
- [How to deal with `assert` calls in production](https://github.com/power-assert-js/power-assert/issues/43#issuecomment-208851919)
- [Support JSX tags?](https://github.com/power-assert-js/power-assert/issues/34#issuecomment-269848058)
- [Any tool to migrate `should/expect` code to `power-assert`?](https://github.com/power-assert-js/power-assert/issues/74)
- [Conflicts with babel-plugin-istanbul?](https://github.com/power-assert-js/babel-preset-power-assert/issues/4)
- [power-assert message does not appear in Node8](https://github.com/power-assert-js/power-assert/issues/85)


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](https://github.com/power-assert-js/power-assert#be-sure-to-transform-test-code)


CHANGELOG
---------------------------------------
See [CHANGELOG](https://github.com/power-assert-js/power-assert/blob/master/CHANGELOG.md)


EXAMPLE
---------------------------------------

See [HOW TO USE](https://github.com/power-assert-js/power-assert#how-to-use) section for more details.

__Note:__ There is an [online demo site](https://azu.github.io/power-assert-demo/) available.


### Target test code (using Mocha in this example)

```javascript
'use strict';

const assert = require('assert');

describe('Array', function(){
    let ary;
    beforeEach(() => {
        ary = [1,2,3];
    });
    describe('#indexOf()', () => {
        it('should return index when the value is present', () => {
            const zero = 0, two = 2;
            assert(ary.indexOf(zero) === two);
        });
        it('should return -1 when the value is not present', () => {
            const minusOne = -1, two = 2;
            assert.ok(ary.indexOf(two) === minusOne, 'THIS IS AN ASSERTION MESSAGE');
        });
    });
});

describe('various types', () => {
    let types;
    class Person {
        constructor(name, age) {
            this.name = name;
            this.age = age;
        }
    }
    beforeEach(() => {
        types = [
            'string', 98.6, true, false, null, undefined,
            ['nested', 'array'],
            {object: true},
            NaN, Infinity,
            /^not/,
            new Person('alice', 3)
        ];
    });
    it('demo', () => {
        const index = types.length -1,
            bob = new Person('bob', 5);
        assert(types[index].name === bob.name);
    });
});
```

### 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](https://github.com/power-assert-js/espower-loader) (with [intelli-espower-loader](https://github.com/power-assert-js/intelli-espower-loader))
 - [babel-preset-power-assert](https://github.com/power-assert-js/babel-preset-power-assert)
 - [babel-plugin-espower](https://github.com/power-assert-js/babel-plugin-espower)
 - [espowerify](https://github.com/power-assert-js/espowerify)
 - [webpack-espower-loader](https://github.com/power-assert-js/webpack-espower-loader).
 - [espower-cli](https://github.com/power-assert-js/espower-cli)
 - [grunt-espower](https://github.com/power-assert-js/grunt-espower)
 - [gulp-espower](https://github.com/power-assert-js/gulp-espower)
 - [karma-espower-preprocessor](https://github.com/power-assert-js/karma-espower-preprocessor)
 - [espower-coffee](https://github.com/power-assert-js/espower-coffee)
 - [espower-typescript](https://github.com/power-assert-js/espower-typescript)
 - [espower-traceur](https://github.com/power-assert-js/espower-traceur)

If you are using Node.js only, the easiest way is to use [intelli-espower-loader](https://github.com/power-assert-js/intelli-espower-loader). Steps are as follows.


### Setup

`npm install --save-dev mocha power-assert intelli-espower-loader`


### Run

Put tests into `test` directory then run. You will see the power-assert output appears.

      $ $(npm bin)/mocha --require intelli-espower-loader path/to/test/mocha_node.js
    
    
      Array
        #indexOf()
          1) should return index when the value is present
          2) should return -1 when the value is not present
    
      various types
        3) demo
    
    
      0 passing (43ms)
      3 failing
    
      1) Array #indexOf() should return index when the value is present:
    
          AssertionError:   # test/example2.js:13
    
      assert(ary.indexOf(zero) === two)
             |   |       |     |   |
             |   |       |     |   2
             |   -1      0     false
             [1,2,3]
    
      [number] two
      => 2
      [number] ary.indexOf(zero)
      => -1
    
          + expected - actual
    
          -false
          +true
    
          at Context.it (test/example2.js:13:13)
    
      2) Array #indexOf() should return -1 when the value is not present:
    
          AssertionError: THIS IS AN ASSERTION MESSAGE   # test/example2.js:17
    
      assert.ok(ary.indexOf(two) === minusOne, 'THIS IS AN ASSERTION MESSAGE')
                |   |       |    |   |
                |   |       |    |   -1
                |   1       2    false
                [1,2,3]
    
      [number] minusOne
      => -1
      [number] ary.indexOf(two)
      => 1
    
          + expected - actual
    
          -false
          +true
    
          at Context.it (test/example2.js:17:20)
    
      3) various types demo:
    
          AssertionError:   # test/example2.js:43
    
      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
    
    
          + expected - actual
    
          -false
          +true
    
          at Context.it (test/example2.js:43:9)



SEED PROJECTS
---------------------------------------

Some seed projects are available to help you start with power-assert.

| module | env | tech stack |
|:-------|:------------|:------------|
| [power-assert-node-seed](https://github.com/azu/power-assert-node-seed) | Node.js | power-assert + [intelli-espower-loader](https://github.com/power-assert-js/intelli-espower-loader) |
| [power-assert-testem-seed](https://github.com/azu/power-assert-testem-seed) | Browsers(by [testem](https://github.com/testem/testem)) | power-assert + [gulp-espower](https://github.com/power-assert-js/gulp-espower) + [testem](https://github.com/airportyh/testem). |
| [power-assert-karma-seed](https://github.com/azu/power-assert-karma-seed) | Browsers(by [Karma](https://karma-runner.github.io/)) | power-assert + [espowerify](https://github.com/power-assert-js/espowerify) + [browserify](http://browserify.org/) + [Karma](https://karma-runner.github.io/). |


HOW TO USE
---------------------------------------

There are some ways to use power-assert. (If you want to see running examples, see [SEED PROJECTS](#seed-projects))

1. `power-assert` + `Babel` + `babel-preset-power-assert`: The only way to enable power-assert if you are using [Babel6+](https://babeljs.io/).
2. `power-assert` + `espower-loader` or `intelli-espower-loader` : Simple and recommended (but only works under Node).
3. `power-assert` + `espower-coffee` or `espower-typescript`: Use power-assert with AltJS. Recommended but only works under Node.
4. `power-assert` + `browserify` + `espowerify`: if you are using [browserify](http://browserify.org/) but not with Babel.
5. `power-assert` + `webpack` + `webpack-espower-loader`: if you are using [webpack](https://webpack.github.io/) but not with Babel.
6. `power-assert` + `espower-cli` or `grunt-espower` or `gulp-espower` : Generate instrumented code so works anywhere.


### using `babel-preset-power-assert` or `babel-plugin-espower`

If you are writing your code with Babel, you can instrument Power Assert feature with Babel and babel-preset-power-assert (or babel-plugin-espower).

see [babel-plugin-espower README](https://github.com/power-assert-js/babel-plugin-espower) and [babel-preset-power-assert README](https://github.com/power-assert-js/babel-preset-power-assert)


### using `espower-loader` or `intelli-espower-loader`

If you are writing Node.js app/module, you can instrument Power Assert feature without code generation by using `espower-loader`.

see [espower-loader README](https://github.com/power-assert-js/espower-loader).

FYI: You may be interested in [intelli-espower-loader](https://github.com/power-assert-js/intelli-espower-loader) to go one step further. With [intelli-espower-loader](https://github.com/power-assert-js/intelli-espower-loader), you don't need to create loader file (like `enable-power-assert.js`). Just define test directory in `package.json` wow!


### using `espower-typescript`

If you are writing Node.js app/module in TypeScript, you can instrument Power Assert feature without code generation by using `espower-typescript`.

see [espower-typescript README](https://github.com/power-assert-js/espower-typescript).


### using `espower-coffee`

If you are writing Node.js app/module in CoffeeScript, you can instrument Power Assert feature without code generation by using `espower-coffee`.

see [espower-coffee README](https://github.com/power-assert-js/espower-coffee).


### using `espowerify`

If you are using [browserify](http://browserify.org/) but not with Babel, you can instrument Power Assert feature via `espowerify`.

see [espowerify README](https://github.com/power-assert-js/espowerify).


### using `webpack-espower-loader`

If you are using [webpack](https://webpack.github.io/) but not with Babel, you can instrument Power Assert feature via `webpack-espower-loader`.

see [webpack-espower-loader README](https://github.com/power-assert-js/webpack-espower-loader).


### using `espower-cli`

If you don't want to use grunt, gulp, browserify, and so on, you can use `power-assert` via bower, with generated code by `espower-cli`

see [espower-cli README](https://github.com/power-assert-js/espower-cli).


### using `gulp-espower`

On the browser side and you are not using [browserify](http://browserify.org/) but [bower](https://bower.io/) and [gulp](http://gulpjs.com/), you can use `power-assert` via bower, with generated code by `gulp-espower`

see [gulp-espower README](https://github.com/power-assert-js/gulp-espower).


### using `grunt-espower`

On the browser side and you are not using [browserify](http://browserify.org/) but [bower](https://bower.io/) and [Grunt](http://gruntjs.com/), you can use `power-assert` via bower, with generated code by `grunt-espower`

see [grunt-espower README](https://github.com/power-assert-js/grunt-espower).



CUSTOMIZATION API
---------------------------------------

`power-assert` provides an API for customization.

### var assert = assert.customize(options)

Through this API, you can customize power-assert by changing some options.

```javascript
var assert = require('power-assert').customize({
    output: {
        maxDepth: 2
    }
});
```

### options

`options` has two top-level keys. `assertion` and `output`.

#### options.assertion

customization options for [empower](https://github.com/power-assert-js/empower) module. See [empower API documentation](https://github.com/power-assert-js/empower#api) for details. Note that some default values are different from `empower`'s (`modifyMessageOnRethrow: true` and `saveContextOnRethrow: true`).

#### options.output

customization options for [power-assert-formatter](https://github.com/power-assert-js/power-assert-formatter) module. See [power-assert-formatter API documentation](https://github.com/power-assert-js/power-assert-formatter#api) for details.

#### default values

customizable properties and their default values are as follows.

```javascript
var assert = require('power-assert').customize({
    assertion: {
        destructive: false,
        modifyMessageOnRethrow: true,
        saveContextOnRethrow: true,
        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])'
        ]
    },
    output: {
        lineDiffThreshold: 5,
        maxDepth: 1,
        anonymous: 'Object',
        circular: '#@Circular#',
        lineSeparator: '\n',
        ambiguousEastAsianCharWidth: 2,
        widthOf: (Function to calculate width of string. Please see power-assert-formatter's documentation)
        stringify: (Function to stringify any target value. Please see power-assert-formatter's documentation)
        diff: (Function to create diff string between two strings. Please see power-assert-formatter's documentation)
        writerClass: (Constructor Function for output writer class. Please see power-assert-formatter's documentation)
        renderers: [
            './built-in/file',
            './built-in/assertion',
            './built-in/diagram',
            './built-in/binary-expression'
        ]
    }
});
```


INTERNAL DESIGN
---------------------------------------

`power-assert` family provides 1 main module, 4 core modules and many more instrumentors.


Main (facade) module is,

| module | description |
|:-------|:------------|
| [power-assert](https://github.com/power-assert-js/power-assert) | Standard `assert` function on top of `empower` and `power-assert-formatter` |

core modules are,

| module | description |
|:-------|:------------|
| [empower](https://github.com/power-assert-js/empower) | Power Assert feature enhancer for assert function/object. |
| [power-assert-formatter](https://github.com/power-assert-js/power-assert-formatter) | Power Assert output formatter. |
| [espower](https://github.com/power-assert-js/espower) | Power Assert feature instrumentor core based on the ECMAScript AST defined in [The ESTree Spec](https://github.com/estree/estree) (formerly known as [Mozilla SpiderMonkey Parser API](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/Parser_API)). |
| [espower-source](https://github.com/power-assert-js/espower-source) | Power Assert instrumentor from source to source, with source-map. (Thin wrapper of `espower`). |

and instrumentors are,

| module | description |
|:-------|:------------|
| [espower-loader](https://github.com/power-assert-js/espower-loader) | Node module loader to apply `espower` on the fly. |
| [intelli-espower-loader](https://github.com/power-assert-js/intelli-espower-loader) | configure `espower-loader` with ease. |
| [babel-preset-power-assert](https://github.com/power-assert-js/babel-preset-power-assert) | [Babel](https://babeljs.io/) preset to instrument power-assert feature into target files. |
| [babel-plugin-espower](https://github.com/power-assert-js/babel-plugin-espower) | [Babel](https://babeljs.io/) plugin to instrument power-assert feature into target files. |
| [espowerify](https://github.com/power-assert-js/espowerify) | [Browserify](http://browserify.org/) transform to apply `espower` to target files. |
| [webpack-espower-loader](https://github.com/power-assert-js/webpack-espower-loader) | Power Assert instrumentor module for [webpack](https://webpack.github.io/). |
| [espower-cli](https://github.com/power-assert-js/espower-cli) | Command line tool for power-assert. |
| [grunt-espower](https://github.com/power-assert-js/grunt-espower) | Grunt task to apply `espower` to target files. |
| [gulp-espower](https://github.com/power-assert-js/gulp-espower) | Gulp plugin to apply `espower` to target files. |
| [karma-espower-preprocessor](https://github.com/power-assert-js/karma-espower-preprocessor) | karma-preprocessor for power-assert. |
| [espower-coffee](https://github.com/power-assert-js/espower-coffee) | power-assert instrumentor for CoffeeScript. |
| [espower-typescript](https://github.com/power-assert-js/espower-typescript) | power-assert instrumentor for TypeScript. |
| [espower-traceur](https://github.com/power-assert-js/espower-traceur) | power-assert instrumentor for ES6 using [Traceur Compiler](https://github.com/google/traceur-compiler/). |
| [espower-babel](https://github.com/power-assert-js/espower-babel) | [DEPRECATED] power-assert instrumentor for ES6 using [Babel](https://babeljs.io/). |


`power-assert` provides standard [assert](https://nodejs.org/api/assert.html) compatible function with Power Assert feature.
(Best fit with [Mocha](https://mochajs.org/). If you use assert-like objects provided by various testing frameworks such as [QUnit](https://qunitjs.com/) or [nodeunit](https://github.com/caolan/nodeunit). Please use [empower](https://github.com/power-assert-js/empower) and [power-assert-formatter](https://github.com/power-assert-js/power-assert-formatter) modules directly).


Internally, `power-assert` uses [empower](https://github.com/power-assert-js/empower) module to enhance power assert feature into the standard [assert](https://nodejs.org/api/assert.html) module, to run with the power assert feature added code by [espower](https://github.com/power-assert-js/espower) module, and prettify output using [power-assert-formatter](https://github.com/power-assert-js/power-assert-formatter).


See [power-assert-demo](https://github.com/twada/power-assert-demo) project for power-assert Demo running with mocha.


SUPPORTED FRAMEWORKS
---------------------------------------

* [Mocha](https://mochajs.org/)
* [AVA](https://github.com/sindresorhus/ava)


### FRAMEWORKS KNOWN TO WORK

* [Jest](https://facebook.github.io/jest/) with Babel
* [Karma](https://karma-runner.github.io/) with Mocha
* [testem](https://github.com/testem/testem) with Mocha
* [QUnit](https://qunitjs.com/)
* [nodeunit](https://github.com/caolan/nodeunit)
* [buster-assertions](https://docs.busterjs.org/en/latest/modules/buster-assertions/)
* [Lab](https://github.com/hapijs/lab)
* [Nightmare](http://www.nightmarejs.org/)
* [Protractor](http://www.protractortest.org/)
* [eater](https://github.com/yosuke-furukawa/eater)


OUR SUPPORT POLICY
---------------------------------------

For the Transpiler side, we support Node under maintenance. In other words, we stop supporting old Node version when [their maintenance ends](https://github.com/nodejs/LTS).

For the Runtime side, we support [Node under maintenance](https://github.com/nodejs/LTS) and "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). power-assert is known to work with old browsers, and trying to keep them working though.


AUTHOR
---------------------------------------
* [Takuto Wada](https://github.com/twada)


CONTRIBUTORS
---------------------------------------
* [azu (azu)](https://github.com/azu)
* [vvakame (Masahiro Wakame)](https://github.com/vvakame)
* [yosuke-furukawa (Yosuke Furukawa)](https://github.com/yosuke-furukawa)
* [teppeis (Teppei Sato)](https://github.com/teppeis)
* [zoncoen (Kenta Mori)](https://github.com/zoncoen)
* [falsandtru (falsandtru)](https://github.com/falsandtru)
* [jamestalmage (James Talmage)](https://github.com/jamestalmage)
* [LeshaKoss (Lesha Koss)](https://github.com/LeshaKoss)
* [watilde (Daijirō Wachi)](https://github.com/watilde)


LICENSE
---------------------------------------
Licensed under the [MIT](https://github.com/power-assert-js/power-assert/blob/master/MIT-LICENSE.txt) license.



MORE OUTPUT EXAMPLES
---------------------------------------

### Target test code (using QUnit in this example)

```javascript
var q = require('qunitjs');

(function () {
    var empower = require('empower'),
        formatter = require('power-assert-formatter'),
        qunitTap = require("qunit-tap");
    empower(q.assert, formatter(), {destructive: true});
    qunitTap(q, require('util').puts, {showSourceOnFailure: false});
    q.config.autorun = false;
})();

q.test('spike', function (assert) {
    assert.ok(true);

    var hoge = 'foo';
    var fuga = 'bar';
    assert.ok(hoge === fuga, 'comment');

    var piyo = 3;
    assert.ok(fuga === piyo);

    var longString = 'very very loooooooooooooooooooooooooooooooooooooooooooooooooooong message';
    var anotherLongString = 'yet another loooooooooooooooooooooooooooooooooooooooooooooooooooong message';
    assert.ok(longString === anotherLongString);

    assert.ok(4 === piyo);

    assert.ok(4 !== 4);

    var falsyStr = '';
    assert.ok(falsyStr);

    var falsyNum = 0;
    assert.ok(falsyNum);

    var ary1 = ['foo', 'bar'];
    var ary2 = ['aaa', 'bbb', 'ccc'];
    assert.ok(ary1.length === ary2.length);
    assert.deepEqual(ary1, ary2);

    var actual = 16;
    assert.ok(5 < actual && actual < 13);

    actual = 4;
    assert.ok(5 < actual && actual < 13);

    actual = 10;
    assert.ok(actual < 5 || 13 < actual);


    var propName = 'bar',
        foo = {
            bar: {
                baz: false
            }
        };

    assert.ok(foo.bar.baz);
    assert.ok(foo['bar'].baz);
    assert.ok(foo[propName]['baz']);


    var truth = true;
    assert.ok(!truth);


    var func = function () { return false; };
    assert.ok(func());


    var obj = {
        age: function () {
            return 0;
        }
    };
    assert.ok(obj.age());


    var isFalsy = function (arg) {
        return !(arg);
    };
    var positiveInt = 50;
    assert.ok(isFalsy(positiveInt));


    var sum = function () {
        var result = 0;
        for (var i = 0; i < arguments.length; i += 1) {
            result += arguments[i];
        }
        return result;
    };
    var one = 1, two = 2, three = 3, seven = 7, ten = 10;
    assert.ok(sum(one, two, three) === seven);
    assert.ok(sum(sum(one, two), three) === sum(sum(two, three), seven));
    assert.ok((three * (seven * ten)) === three);


    var math = {
        calc: {
            sum: function () {
                var result = 0;
                for (var i = 0; i < arguments.length; i += 1) {
                    result += arguments[i];
                }
                return result;
            }
        }
    };
    assert.ok(math.calc.sum(one, two, three) === seven);
});

q.load();
```


### `espower` code above then running under Node.js
    
```
# module: undefined
# test: spike
ok 1 - okay
not ok 2 - comment # path/to/examples/qunit_node.js:17
#
# assert.ok(hoge === fuga, 'comment')
#           |    |   |
#           |    |   "bar"
#           |    false
#           "foo"
#
# --- [string] fuga
# +++ [string] hoge
# @@ -1,3 +1,3 @@
# -bar
# +foo
#
# , test: spike
not ok 3 - # path/to/examples/qunit_node.js:20
#
# assert.ok(fuga === piyo)
#           |    |   |
#           |    |   3
#           |    false
#           "bar"
#
# [number] piyo
# => 3
# [string] fuga
# => "bar"

# , test: spike
not ok 4 - # path/to/examples/qunit_node.js:24
#
# assert.ok(longString === anotherLongString)
#           |          |   |
#           |          |   "yet another loooooooooooooooooooooooooooooooooooooooooooooooooooong message"
#           |          false
#           "very very loooooooooooooooooooooooooooooooooooooooooooooooooooong message"
#
# --- [string] anotherLongString
# +++ [string] longString
# @@ -1,15 +1,13 @@
# -yet anoth
# +very v
#  er
# +y
#   loo
#
# , test: spike
not ok 5 - # path/to/examples/qunit_node.js:26
#
# assert.ok(4 === piyo)
#             |   |
#             |   3
#             false
#
# [number] piyo
# => 3
# [number] 4
# => 4
# , test: spike
not ok 6 - # path/to/examples/qunit_node.js:28
#
# assert.ok(4 !== 4)
#             |
#             false
# , test: spike
not ok 7 - # path/to/examples/qunit_node.js:31
#
# assert.ok(falsyStr)
#           |
#           ""
# , test: spike
not ok 8 - # path/to/examples/qunit_node.js:34
#
# assert.ok(falsyNum)
#           |
#           0
# , test: spike
not ok 9 - # path/to/examples/qunit_node.js:38
#
# assert.ok(ary1.length === ary2.length)
#           |    |      |   |    |
#           |    |      |   |    3
#           |    |      |   ["aaa","bbb","ccc"]
#           |    2      false
#           ["foo","bar"]
#
# [number] ary2.length
# => 3
# [number] ary1.length
# => 2
# , test: spike
not ok 10 - # path/to/examples/qunit_node.js:39
#
# assert.deepEqual(ary1, ary2)
#                  |     |
#                  |     ["aaa","bbb","ccc"]
#                  ["foo","bar"]
# , expected: [
#   "aaa",
#   "bbb",
#   "ccc"
# ], got: [
#   "foo",
#   "bar"
# ], test: spike
not ok 11 - # path/to/examples/qunit_node.js:42
#
# assert.ok(5 < actual && actual < 13)
#             | |      |  |      |
#             | |      |  16     false
#             | 16     false
#             true
# , test: spike
not ok 12 - # path/to/examples/qunit_node.js:45
#
# assert.ok(5 < actual && actual < 13)
#             | |      |
#             | 4      false
#             false
# , test: spike
not ok 13 - # path/to/examples/qunit_node.js:48
#
# assert.ok(actual < 5 || 13 < actual)
#           |      |   |     | |
#           |      |   |     | 10
#           |      |   false false
#           10     false
# , test: spike
not ok 14 - # path/to/examples/qunit_node.js:58
#
# assert.ok(foo.bar.baz)
#           |   |   |
#           |   |   false
#           |   Object{baz:false}
#           Object{bar:#Object#}
# , test: spike
not ok 15 - # path/to/examples/qunit_node.js:59
#
# assert.ok(foo['bar'].baz)
#           |  |       |
#           |  |       false
#           |  Object{baz:false}
#           Object{bar:#Object#}
# , test: spike
not ok 16 - # path/to/examples/qunit_node.js:60
#
# assert.ok(foo[propName]['baz'])
#           |  ||        |
#           |  |"bar"    false
#           |  Object{baz:false}
#           Object{bar:#Object#}
# , test: spike
not ok 17 - # path/to/examples/qunit_node.js:64
#
# assert.ok(!truth)
#           ||
#           |true
#           false
# , test: spike
not ok 18 - # path/to/examples/qunit_node.js:68
#
# assert.ok(func())
#           |
#           false
# , test: spike
not ok 19 - # path/to/examples/qunit_node.js:76
#
# assert.ok(obj.age())
#           |   |
#           |   0
#           Object{age:#function#}
# , test: spike
not ok 20 - # path/to/examples/qunit_node.js:83
#
# assert.ok(isFalsy(positiveInt))
#           |       |
#           false   50
# , test: spike
not ok 21 - # path/to/examples/qunit_node.js:94
#
# assert.ok(sum(one, two, three) === seven)
#           |   |    |    |      |   |
#           |   |    |    |      |   7
#           6   1    2    3      false
#
# [number] seven
# => 7
# [number] sum(one, two, three)
# => 6
# , test: spike
not ok 22 - # path/to/examples/qunit_node.js:95
#
# assert.ok(sum(sum(one, two), three) === sum(sum(two, three), seven))
#           |   |   |    |     |      |   |   |   |    |       |
#           |   |   |    |     |      |   12  5   2    3       7
#           6   3   1    2     3      false
#
# [number] sum(sum(two, three), seven)
# => 12
# [number] sum(sum(one, two), three)
# => 6
# , test: spike
not ok 23 - # path/to/examples/qunit_node.js:96
#
# assert.ok(three * (seven * ten) === three)
#           |     |  |     | |    |   |
#           |     |  |     | |    |   3
#           |     |  |     | 10   false
#           |     |  7     70
#           3     210
#
# [number] three
# => 3
# [number] three * (seven * ten)
# => 210
# , test: spike
not ok 24 - # path/to/examples/qunit_node.js:110
#
# assert.ok(math.calc.sum(one, two, three) === seven)
#           |    |    |   |    |    |      |   |
#           |    |    |   |    |    |      |   7
#           |    |    6   1    2    3      false
#           |    Object{sum:#function#}
#           Object{calc:#Object#}
#
# [number] seven
# => 7
# [number] math.calc.sum(one, two, three)
# => 6
# , test: spike
1..24
```

Have fun!


[power-assert-url]: https://github.com/power-assert-js/power-assert
[power-assert-banner]: https://raw.githubusercontent.com/power-assert-js/power-assert-js-logo/master/banner/banner-official-fullcolor.png

[npm-url]: https://www.npmjs.com/package/power-assert
[npm-image]: https://badge.fury.io/js/power-assert.svg

[bower-url]: https://badge.fury.io/bo/power-assert
[bower-image]: https://badge.fury.io/bo/power-assert.svg

[travis-url]: https://travis-ci.org/power-assert-js/power-assert
[travis-image]: https://secure.travis-ci.org/power-assert-js/power-assert.svg?branch=master

[depstat-url]: https://gemnasium.com/power-assert-js/power-assert
[depstat-image]: https://gemnasium.com/power-assert-js/power-assert.svg

[license-url]: https://github.com/power-assert-js/power-assert/blob/master/MIT-LICENSE.txt
[license-image]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat