Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/power-assert-js/power-assert

Power Assert in JavaScript. Provides descriptive assertion messages through standard assert interface. No API is the best API.
https://github.com/power-assert-js/power-assert

assert power-assert

Last synced: 1 day ago
JSON representation

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

Awesome Lists containing this project

README 

        
[![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]

[![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 `



or



```

bower install --save-dev power-assert

npm install --save-dev 

```



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



[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