assert: wrap validation function errors

This makes sure that validation function used by `assert.throws` and
`assert.rejects` always throw validatin errors instead of rethrowing
the received error.

That should improve the debugging experience for developers since
they have a better context where the error is coming from and they
also get to know what triggered it.

PR-URL: #28263
Reviewed-By: Rich Trott <[email protected]>
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: James M Snell <[email protected]>

doc/api/assert.md

@@ -1222,6 +1222,9 @@ assert.throws(
 
 Custom error validation:
 
+The function must return `true` to indicate all internal validations passed.
+It will otherwise fail with an AssertionError.
+
 ```js
 assert.throws(
   () => {

lib/assert.js

@@ -653,7 +653,21 @@ function expectedException(actual, expected, message, fn) {
   // Check validation functions return value.
   const res = expected.call({}, actual);
   if (res !== true) {
-    throw actual;
+    if (!message) {
+      generatedMessage = true;
+      const name = expected.name ? `"${expected.name}" ` : '';
+      message = `The ${name}validation function is expected to return "true".` +
+        ` Received ${inspect(res)}`;
+    }
+    const err = new AssertionError({
+      actual,
+      expected,
+      message,
+      operator: fn.name,
+      stackStartFn: fn
+    });
+    err.generatedMessage = generatedMessage;
+    throw err;
   }
 }
 

test/parallel/test-assert-async.js

@@ -66,6 +66,21 @@ const invalidThenableFunc = () => {
       code: 'ERR_INVALID_RETURN_VALUE'
     })
   );
+
+  const err = new Error('foobar');
+  const validate = () => { return 'baz'; };
+  promises.push(assert.rejects(
+    () => assert.rejects(Promise.reject(err), validate),
+    {
+      message: 'The "validate" validation function is expected to ' +
+               "return \"true\". Received 'baz'",
+      code: 'ERR_ASSERTION',
+      actual: err,
+      expected: validate,
+      name: 'AssertionError',
+      operator: 'rejects',
+    }
+  ));
 }
 
 {

test/parallel/test-assert.js

@@ -1326,3 +1326,20 @@ assert.throws(
              'Received "[Array]"'
   }
 );
+
+{
+  const err = new TypeError('foo');
+  const validate = (() => () => ({ a: true, b: [ 1, 2, 3 ] }))();
+  assert.throws(
+    () => assert.throws(() => { throw err; }, validate),
+    {
+      message: 'The validation function is expected to ' +
+              `return "true". Received ${inspect(validate())}`,
+      code: 'ERR_ASSERTION',
+      actual: err,
+      expected: validate,
+      name: 'AssertionError',
+      operator: 'throws',
+    }
+  );
+}