doc: improve assert documentation

This adds a example to `assert.throws` to document checking against
error instances. It also makes it clearer what some arguments can
receive as input.

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, 11 deletions

diff --git a/doc/api/assert.md b/doc/api/assert.md
index c868ef64e0..6d96359d00 100644
--- a/doc/api/assert.md
+++ b/doc/api/assert.md
@@ -395,6 +395,9 @@ 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.
 
+If specified, `error` can be a [`Class`][], [`RegExp`][] or a validation
+function. See [`assert.throws()`][] for more details.
+
 Besides the async nature to await the completion behaves identically to
 [`assert.doesNotThrow()`][].
 
@@ -431,8 +434,7 @@ changes:
 * `error` {RegExp|Function}
 * `message` {any}
 
-Asserts that the function `block` does not throw an error. See
-[`assert.throws()`][] for more details.
+Asserts that the function `block` does not throw an error.
 
 Please note: Using `assert.doesNotThrow()` is actually not useful because there
 is no benefit by catching an error and then rethrowing it. Instead, consider
@@ -447,6 +449,9 @@ parameter, then an `AssertionError` is thrown. If the error is of a different
 type, or if the `error` parameter is undefined, the error is propagated back
 to the caller.
 
+If specified, `error` can be a [`Class`][], [`RegExp`][] or a validation
+function. See [`assert.throws()`][] for more details.
+
 The following, for instance, will throw the [`TypeError`][] because there is no
 matching error type in the assertion:
 
@@ -483,7 +488,7 @@ assert.doesNotThrow(
   () => {
     throw new TypeError('Wrong value');
   },
-  TypeError,
+  /Wrong value/,
   'Whoops'
 );
 // Throws: AssertionError: Got unwanted exception (TypeError). Whoops
@@ -916,7 +921,7 @@ assert(0);
 added: REPLACEME
 -->
 * `block` {Function|Promise}
-* `error` {RegExp|Function|Object}
+* `error` {RegExp|Function|Object|Error}
 * `message` {any}
 
 Awaits the `block` promise or, if `block` is a function, immediately calls the
@@ -930,8 +935,10 @@ checking the error handler.
 Besides the async nature to await the completion behaves identically to
 [`assert.throws()`][].
 
-If specified, `error` can be a constructor, [`RegExp`][], a validation
-function, or an object where each property will be tested for.
+If specified, `error` can be a [`Class`][], [`RegExp`][], a validation function,
+an object where each property will be tested for, or an instance of error where
+each property will be tested for including the non-enumerable `message` and
+`name` properties.
 
 If specified, `message` will be the message provided by the `AssertionError` if
 the block fails to reject.
@@ -1011,13 +1018,15 @@ changes:
     description: The `error` parameter can now be an arrow function.
 -->
 * `block` {Function}
-* `error` {RegExp|Function|Object}
+* `error` {RegExp|Function|Object|Error}
 * `message` {any}
 
 Expects the function `block` to throw an error.
 
-If specified, `error` can be a constructor, [`RegExp`][], a validation
-function, or an object where each property will be tested for.
+If specified, `error` can be a [`Class`][], [`RegExp`][], a validation function,
+an object where each property will be tested for, or an instance of error where
+each property will be tested for including the non-enumerable `message` and
+`name` properties.
 
 If specified, `message` will be the message provided by the `AssertionError` if
 the block fails to throw.
@@ -1066,10 +1075,11 @@ assert.throws(
 Custom error object / error instance:
 
 ```js
+const err = new TypeError('Wrong value');
+err.code = 404;
+
 assert.throws(
   () => {
-    const err = new TypeError('Wrong value');
-    err.code = 404;
     throw err;
   },
   {
@@ -1078,6 +1088,16 @@ assert.throws(
     // Note that only properties on the error object will be tested!
   }
 );
+
+// Fails due to the different `message` and `name` properties:
+assert.throws(
+  () => {
+    const otherErr = new Error('Not found');
+    otherErr.code = 404;
+    throw otherErr;
+  },
+  err // This tests for `message`, `name` and `code`.
+);
 ```
 
 Note that `error` cannot be a string. If a string is provided as the second
@@ -1118,6 +1138,7 @@ assert.throws(throwingFirst, /Second$/);
 Due to the confusing notation, it is recommended not to use a string as the
 second argument. This might lead to difficult-to-spot errors.
 
+[`Class`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes
 [`Error.captureStackTrace`]: errors.html#errors_error_capturestacktrace_targetobject_constructoropt
 [`Error`]: errors.html#errors_class_error
 [`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map