doc,assert: document stackStartFunction in fail

PR-URL: nodejs#13862
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

doc/api/assert.md

@@ -257,33 +257,61 @@ 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
 -->
 * `actual` {any}
 * `expected` {any}
 * `message` {any}
 * `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 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`]).
 
 ```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'
+```
+
+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)
@@ -590,6 +618,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

test/parallel/test-assert-fail.js

@@ -1,53 +1,75 @@
 'use strict';
+
 const common = require('../common');
 const assert = require('assert');
 
-// no args
+// No args
 assert.throws(
   () => { assert.fail(); },
   common.expectsError({
     code: 'ERR_ASSERTION',
     type: assert.AssertionError,
+    operator: undefined,
+    actual: undefined,
+    expected: undefined,
     message: 'undefined undefined undefined'
   })
 );
 
-// one arg = message
+// One arg = message
 assert.throws(
   () => { assert.fail('custom message'); },
   common.expectsError({
     code: 'ERR_ASSERTION',
     type: assert.AssertionError,
+    operator: undefined,
+    actual: undefined,
+    expected: undefined,
     message: 'custom message'
   })
 );
 
-// two args only, operator defaults to '!='
+// Two args only, operator defaults to '!='
 assert.throws(
   () => { assert.fail('first', 'second'); },
   common.expectsError({
     code: 'ERR_ASSERTION',
     type: assert.AssertionError,
+    operator: '!=',
+    actual: 'first',
+    expected: 'second',
     message: '\'first\' != \'second\''
   })
 );
 
-// three args
+// Three args
 assert.throws(
   () => { assert.fail('ignored', 'ignored', 'another custom message'); },
   common.expectsError({
     code: 'ERR_ASSERTION',
     type: assert.AssertionError,
+    operator: undefined,
+    actual: 'ignored',
+    expected: 'ignored',
     message: 'another custom message'
   })
 );
 
-// no third arg (but a fourth arg)
+// No third arg (but a fourth arg)
 assert.throws(
   () => { assert.fail('first', 'second', undefined, 'operator'); },
   common.expectsError({
     code: 'ERR_ASSERTION',
     type: assert.AssertionError,
+    operator: 'operator',
+    actual: 'first',
+    expected: 'second',
     message: '\'first\' operator \'second\''
   })
 );
+
+// The stackFrameFunction should exclude the foo frame
+assert.throws(
+  function foo() { assert.fail('first', 'second', 'message', '!==', foo); },
+  (err) => !/foo/m.test(err.stack)
+);