diff options
author | Ruben Bridgewater <ruben@bridgewater.de> | 2017-07-02 18:06:35 +0200 |
---|---|---|
committer | Refael Ackermann <refack@gmail.com> | 2017-07-02 22:43:17 -0400 |
commit | 7a2b3e2b6cc92b2d694041ab852e860f459dadcd (patch) | |
tree | 1bef4fd83e78e05d3225ef7c5d67e0b3b2af840b /doc/api/assert.md | |
parent | 5bbae2517768f4bf7d462991d257e514f8ba6d25 (diff) | |
download | android-node-v8-7a2b3e2b6cc92b2d694041ab852e860f459dadcd.tar.gz android-node-v8-7a2b3e2b6cc92b2d694041ab852e860f459dadcd.tar.bz2 android-node-v8-7a2b3e2b6cc92b2d694041ab852e860f459dadcd.zip |
doc,assert: document stackStartFunction in fail
PR-URL: https://github.com/nodejs/node/pull/13862
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Diffstat (limited to 'doc/api/assert.md')
-rw-r--r-- | doc/api/assert.md | 44 |
1 files changed, 35 insertions, 9 deletions
diff --git a/doc/api/assert.md b/doc/api/assert.md index 502150fd8d..c92ae3f3f1 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -257,7 +257,7 @@ property set equal to the value of the `message` parameter. If the `message` parameter is undefined, a default error message is assigned. ## assert.fail([message]) -## assert.fail(actual, expected, message, operator) +## assert.fail(actual, expected[, message[, operator[, stackStartFunction]]]) <!-- YAML added: v0.1.21 --> @@ -265,29 +265,54 @@ added: v0.1.21 * `expected` {any} * `message` {any} (default: 'Failed') * `operator` {string} (default: '!=') +* `stackStartFunction` {function} (default: `assert.fail`) Throws an `AssertionError`. If `message` is falsy, the error message is set as the values of `actual` and `expected` separated by the provided `operator`. -Otherwise, the error message is the value of `message`. -If no arguments are provided at all, a default message will be used instead. +If just the two `actual` and `expected` arguments are provided, `operator` will +default to `'!='`. If `message` is provided only it will be used as the error +message, the other arguments will be stored as properties on the thrown object. +If `stackStartFunction` is provided, all stack frames above that function will +be removed from stacktrace (see [`Error.captureStackTrace`]). If no arguments +are given, the default message `Failed` will be used. ```js const assert = require('assert'); assert.fail(1, 2, undefined, '>'); -// AssertionError: 1 > 2 +// AssertionError [ERR_ASSERTION]: 1 > 2 + +assert.fail(1, 2, 'fail'); +// AssertionError [ERR_ASSERTION]: fail assert.fail(1, 2, 'whoops', '>'); -// AssertionError: whoops +// AssertionError [ERR_ASSERTION]: whoops +``` + +*Note*: Is the last two cases `actual`, `expected`, and `operator` have no +influence on the error message. + +```js +assert.fail(); +// AssertionError [ERR_ASSERTION]: Failed assert.fail('boom'); -// AssertionError: boom +// AssertionError [ERR_ASSERTION]: boom assert.fail('a', 'b'); -// AssertionError: 'a' != 'b' +// AssertionError [ERR_ASSERTION]: 'a' != 'b' +``` -assert.fail(); -// AssertionError: Failed +Example use of `stackStartFunction` for truncating the exception's stacktrace: +```js +function suppressFrame() { + assert.fail('a', 'b', undefined, '!==', suppressFrame); +} +suppressFrame(); +// AssertionError [ERR_ASSERTION]: 'a' !== 'b' +// at repl:1:1 +// at ContextifyScript.Script.runInThisContext (vm.js:44:33) +// ... ``` ## assert.ifError(value) @@ -594,6 +619,7 @@ For more information, see [MDN's guide on equality comparisons and sameness][mdn-equality-guide]. [`Error`]: errors.html#errors_class_error +[`Error.captureStackTrace`]: errors.html#errors_error_capturestacktrace_targetobject_constructoropt [`Map`]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Map [`Object.is()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is [`RegExp`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions |