doc,assert: document stackStartFunction in fail · nodejs/node@abf6355
@@ -192,29 +192,47 @@ If the values are not equal, an `AssertionError` is thrown with a `message`
192192property set equal to the value of the `message` parameter. If the `message`
193193parameter is undefined, a default error message is assigned.
194194195-## assert.fail(actual, expected, message, operator)
195+## assert.fail(actual, expected[, message[, operator[, stackStartFunction]]])
196196<!-- YAML
197197added: v0.1.21
198198-->
199199* `actual` {any}
200200* `expected` {any}
201201* `message` {any}
202202* `operator` {string}
203+* `stackStartFunction` {function} (default: `assert.fail`)
203204204205Throws an `AssertionError`. If `message` is falsy, the error message is set as
205206the values of `actual` and `expected` separated by the provided `operator`.
206207Otherwise, the error message is the value of `message`.
208+If `stackStartFunction` is provided, all stack frames above that function will
209+be removed from stacktrace (see [`Error.captureStackTrace`]).
207210208211```js
209212const assert = require('assert');
210213211214assert.fail(1, 2, undefined, '>');
212215// AssertionError: 1 > 2
213216217+assert.fail(1, 2, 'fail');
218+// AssertionError: fail
219+214220assert.fail(1, 2, 'whoops', '>');
215221// AssertionError: whoops
216222```
217223224+Example use of `stackStartFunction` for truncating the exception's stacktrace:
225+```js
226+function suppressFrame() {
227+assert.fail('a', 'b', undefined, '!==', suppressFrame);
228+}
229+suppressFrame();
230+// AssertionError: 'a' !== 'b'
231+// at repl:1:1
232+// at ContextifyScript.Script.runInThisContext (vm.js:44:33)
233+// ...
234+```
235+218236## assert.ifError(value)
219237<!-- YAML
220238added: v0.1.97
@@ -492,5 +510,6 @@ assert.throws(myFunction, /missing foo/, 'did not throw with expected message');
492510[`assert.ok()`]: #assert_assert_ok_value_message
493511[`assert.throws()`]: #assert_assert_throws_block_error_message
494512[`Error`]: errors.html#errors_class_error
513+[`Error.captureStackTrace`]: errors.html#errors_error_capturestacktrace_targetobject_constructoropt
495514[`RegExp`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
496515[`TypeError`]: errors.html#errors_class_typeerror