assert: add direct promises support in rejects

This adds direct promise support to `assert.rejects` and
`assert.doesNotReject`. It will now accept both, functions and ES2015
promises as input.

Besides this the documentation was updated to reflect the latest
changes.

It also refactors the tests to a non blocking way to improve the
execution performance and improves the coverage.

PR-URL: https://github.com/nodejs/node/pull/19885
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

1 files changed, 32 insertions, 22 deletions

diff --git a/doc/api/assert.md b/doc/api/assert.md
index 6a587052f2..c868ef64e0 100644
--- a/doc/api/assert.md
+++ b/doc/api/assert.md
@@ -378,22 +378,23 @@ parameter is an instance of an [`Error`][] then it will be thrown instead of the
 <!-- YAML
 added: REPLACEME
 -->
-* `block` {Function}
+* `block` {Function|Promise}
 * `error` {RegExp|Function}
 * `message` {any}
 
-Awaits for the promise returned by function `block` to complete and not be
-rejected.
+Awaits the `block` promise or, if `block` is a function, immediately calls the
+function and awaits the returned promise to complete. It will then check that
+the promise is not rejected.
+
+If `block` is a function and it throws an error synchronously,
+`assert.doesNotReject()` will return a rejected Promise with that error without
+checking the error handler.
 
 Please note: Using `assert.doesNotReject()` is actually not useful because there
 is little benefit by catching a rejection and then rejecting it again. Instead,
 consider adding a comment next to the specific code path that should not reject
 and keep error messages as expressive as possible.
 
-When `assert.doesNotReject()` is called, it will immediately call the `block`
-function, and awaits for completion. See [`assert.rejects()`][] for more
-details.
-
 Besides the async nature to await the completion behaves identically to
 [`assert.doesNotThrow()`][].
 
@@ -409,12 +410,10 @@ Besides the async nature to await the completion behaves identically to
 ```
 
 ```js
-assert.doesNotReject(
-  () => Promise.reject(new TypeError('Wrong value')),
-  SyntaxError
-).then(() => {
-  // ...
-});
+assert.doesNotReject(Promise.reject(new TypeError('Wrong value')))
+  .then(() => {
+    // ...
+  });
 ```
 
 ## assert.doesNotThrow(block[, error][, message])
@@ -916,14 +915,17 @@ assert(0);
 <!-- YAML
 added: REPLACEME
 -->
-* `block` {Function}
+* `block` {Function|Promise}
 * `error` {RegExp|Function|Object}
 * `message` {any}
 
-Awaits for promise returned by function `block` to be rejected.
+Awaits the `block` promise or, if `block` is a function, immediately calls the
+function and awaits the returned promise to complete. It will then check that
+the promise is rejected.
 
-When `assert.rejects()` is called, it will immediately call the `block`
-function, and awaits for completion.
+If `block` is a function and it throws an error synchronously,
+`assert.rejects()` will return a rejected Promise with that error without
+checking the error handler.
 
 Besides the async nature to await the completion behaves identically to
 [`assert.throws()`][].
@@ -938,22 +940,31 @@ the block fails to reject.
 (async () => {
   await assert.rejects(
     async () => {
-      throw new Error('Wrong value');
+      throw new TypeError('Wrong value');
     },
-    Error
+    {
+      name: 'TypeError',
+      message: 'Wrong value'
+    }
   );
 })();
 ```
 
 ```js
 assert.rejects(
-  () => Promise.reject(new Error('Wrong value')),
+  Promise.reject(new Error('Wrong value')),
   Error
 ).then(() => {
   // ...
 });
 ```
 
+Note that `error` cannot be a string. If a string is provided as the second
+argument, then `error` is assumed to be omitted and the string will be used for
+`message` instead. This can lead to easy-to-miss mistakes. Please read the
+example in [`assert.throws()`][] carefully if using a string as the second
+argument gets considered.
+
 ## assert.strictEqual(actual, expected[, message])
 <!-- YAML
 added: v0.1.21
@@ -1069,7 +1080,7 @@ assert.throws(
 );
 ```
 
-Note that `error` can not be a string. If a string is provided as the second
+Note that `error` cannot be a string. If a string is provided as the second
 argument, then `error` is assumed to be omitted and the string will be used for
 `message` instead. This can lead to easy-to-miss mistakes. Please read the
 example below carefully if using a string as the second argument gets
@@ -1123,7 +1134,6 @@ second argument. This might lead to difficult-to-spot errors.
 [`assert.notDeepStrictEqual()`]: #assert_assert_notdeepstrictequal_actual_expected_message
 [`assert.notStrictEqual()`]: #assert_assert_notstrictequal_actual_expected_message
 [`assert.ok()`]: #assert_assert_ok_value_message
-[`assert.rejects()`]: #assert_assert_rejects_block_error_message
 [`assert.strictEqual()`]: #assert_assert_strictequal_actual_expected_message
 [`assert.throws()`]: #assert_assert_throws_block_error_message
 [`strict mode`]: #assert_strict_mode