Merge pull request #12 from twada/escallmatch

use escallmatch module to describe target enhancement patterns
power-assert-js · Aug 12, 2014 · 3fb6f07 · 3fb6f07
2 parents 10edf49 + 6a6a3cb
commit 3fb6f07
Show file tree

Hide file tree

Showing 17 changed files with 6,163 additions and 1,180 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,86 @@
+## 0.8.0 (2014-08-12)
+
+
+#### Features
+
+
+* **empower:**
+  * [modularized by browserify](https://github.com/twada/empower/pull/12)
+  * use `escallmatch` module to describe target patterns ([533a21a0](https://github.com/twada/empower/commit/533a21a0374f23f5ca4e198c17d1e20f10d705fa))
+  * support assertion methods with three or more arguments ([d31dca86](https://github.com/twada/empower/commit/d31dca86de2b05ee88ca5df15579308368657d43))
+  * if not in patterns, do not empower assertion function itself ([1d73a756](https://github.com/twada/empower/commit/1d73a7560ef586a45a0a9259e57c143b3b60caaa))
+  * option `targetMethods` does not required any more ([8ffcc49f](https://github.com/twada/empower/commit/8ffcc49fcdb5523eb38e63a0e7cca34f752d9302))
+  * rename `saveContextOnFail` option to `saveContextOnRethrow` ([1f6133b2](https://github.com/twada/empower/commit/1f6133b24be672f32cfd3b66522a7d14ca5d22e1))
+  * rename `modifyMessageOnFail` option to `modifyMessageOnRethrow` ([0c8a88f0](https://github.com/twada/empower/commit/0c8a88f0592917ba15ac0c1bf21c8f39f39ab350))
+
+
+#### 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](https://github.com/twada/empower/commit/1f6133b24be672f32cfd3b66522a7d14ca5d22e1))
+
+* `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](https://github.com/twada/empower/commit/0c8a88f0592917ba15ac0c1bf21c8f39f39ab350))
+
+* 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:
+
+```javascript
+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:
+
+```javascript
+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](https://github.com/twada/empower/commit/8ffcc49fcdb5523eb38e63a0e7cca34f752d9302))
diff --git a/README.md b/README.md
@@ -5,6 +5,9 @@ empower
 [![NPM version](https://badge.fury.io/js/empower.svg)](http://badge.fury.io/js/empower)
 [![Dependency Status](https://gemnasium.com/twada/empower.svg)](https://gemnasium.com/twada/empower)
 [![Coverage Status](https://coveralls.io/repos/twada/empower/badge.png?branch=master)](https://coveralls.io/r/twada/empower?branch=master)
+[![License](http://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/twada/empower/blob/master/MIT-LICENSE.txt)
+[![Built with Gulp](http://img.shields.io/badge/built_with-gulp-brightgreen.svg)](http://gulpjs.com/)
+
 
 Power Assert feature enhancer for assert function/object.
 
@@ -20,6 +23,137 @@ DESCRIPTION
 Please note that `empower` is a beta version product. Pull-requests, issue reports and patches are always welcomed. See [power-assert](http://github.com/twada/power-assert) project for more documentation.
 
 
+CHANGELOG
+---------------------------------------
+See [CHANGELOG](https://github.com/twada/empower/blob/master/CHANGELOG.md)
+
+
+API
+---------------------------------------
+
+### var enhancedAssert = espower(originalAssert, formatter, [options])
+
+| return type            |
+|:-----------------------|
+| `function` or `object` |
+
+`empower` function takes function or object(`originalAssert`) and `formatter` function created by [power-assert-formatter](http://github.com/twada/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
+
+| type                   | default value |
+|:-----------------------|:--------------|
+| `function` or `object` | N/A           |
+
+`originalAssert` is an instance of standard `assert` function or any assert-like object. see [SUPPORTED ASSERTION LIBRARIES](https://github.com/twada/empower#supported-assertion-libraries) and [ASSERTION LIBRARIES KNOWN TO WORK](https://github.com/twada/empower#assertion-libraries-known-to-work) section. Be careful that `originalAssert` will be manipulated directly if `destructive` option is truthy.
+
+
+#### formatter
+
+| type       | default value |
+|:-----------|:--------------|
+| `function` | N/A           |
+
+formatter function created by [power-assert-formatter](http://github.com/twada/power-assert-formatter).
+
+
+#### options
+
+| type     | default value |
+|:---------|:--------------|
+| `object` | (return value of `empower.defaultOptions()`) |
+
+Configuration options. If not passed, default options will be used.
+
+
+#### options.destructive
+
+| type      | default value |
+|:----------|:--------------|
+| `boolean` | `false`       |
+
+If truthy, modify `originalAssert` destructively.
+
+If `false`, espower 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
+
+| type      | default value |
+|:----------|:--------------|
+| `boolean` | `false`       |
+
+If truthy, modify `message` property of AssertionError on rethrow.
+
+
+#### options.saveContextOnRethrow
+
+| type      | default value |
+|:----------|:--------------|
+| `boolean` | `false`       |
+
+If truthy, add `powerAssertContext` property to AssertionError on rethrow.
+
+
+`modifyMessageOnRethrow` option and `saveContextOnRethrow` option makes behavior matrix as below.
+
+| modifyMessageOnRethrow | saveContextOnRethrow | resulting behavior                                |
+|:-----------------------|:---------------------|:--------------------------------------------------|
+| `false` (default)      | `false` (default)    | Always modify assertion message argument directly |
+| `true`                 | `false`              | Modify `message` of AssertionError on fail        |
+| `false`                | `true`               | Do not modify `message` of AssertionError but add `powerAssertContext` property on fail |
+| `true`                 | `true`               | On fail, modify `message` of AssertionError and also add `powerAssertContext` property |
+
+
+#### options.patterns
+
+| type                | default value       |
+|:--------------------|:--------------------|
+| `Array` of `string` | objects shown below |
+
+```javascript
+[
+    '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])'
+]
+```
+
+Target patterns for power assert feature instrumentation.
+
+Pattern detection is done by [escallmatch](http://github.com/twada/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
+
+```javascript
+{
+    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])'
+    ]
+}
+```
+
+
 SUPPORTED ASSERTION LIBRARIES
 ---------------------------------------
 * [Node assert API](http://nodejs.org/api/assert.html)
@@ -33,6 +167,27 @@ ASSERTION LIBRARIES KNOWN TO WORK
 * [buster-assertions](http://docs.busterjs.org/en/latest/modules/buster-assertions/)
 
 
+INSTALL
+---------------------------------------
+
+### via npm
+
+Install
+
+    $ npm install --save-dev empower
+
+
+### 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>
+
+
 AUTHOR
 ---------------------------------------
 * [Takuto Wada](http://github.com/twada)

diff --git a/bower.json b/bower.json
@@ -30,8 +30,8 @@
     "url": "git://github.com/twada/empower.git"
   },
   "devDependencies": {
-    "espower-source": "~0.7.3",
-    "mocha": "~1.21.3",
+    "espower-source": "~0.8.0",
+    "mocha": "~1.21.4",
     "requirejs": "~2.1.14",
     "assert": "Jxck/assert",
     "buster.js": "~0.7.0"