OSSForks/node
1
0
Fork 0
mirror of https://github.com/zebrajr/node.git synced 2026-01-15 12:15:26 +00:00
Code Issues Actions 8 Packages Projects Releases Wiki Activity

doc,assert: document stackStartFunction in fail

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/13862
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
This commit is contained in:
Ruben Bridgewater
2017-07-02 18:06:35 +02:00
committed by Refael Ackermann
parent 5bbae25177
commit 7a2b3e2b6c
1 changed files with 35 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
doc/api/assert.md
View File

@@ -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