doc: update assert's validation functions

Using `assert.throws()` or `assert.rejects()` in combination with
validation function can be very powerful. Using them by returning
any value besides `true` makes debugging very difficult though
because there's no context or reason why the error validation failed.
Thus, it is recommended to throw an error in such cases instead of
returning anything besides `true`.

PR-URL: https://github.com/nodejs/node/pull/27781
Reviewed-By: Rich Trott <rtrott@gmail.com>

1 files changed, 8 insertions, 4 deletions

diff --git a/doc/api/assert.md b/doc/api/assert.md
index 22383a16b6..16aa242ec0 100644
--- a/doc/api/assert.md
+++ b/doc/api/assert.md
@@ -1210,10 +1210,14 @@ assert.throws(
   () => {
     throw new Error('Wrong value');
   },
-  function(err) {
-    if ((err instanceof Error) && /value/.test(err)) {
-      return true;
-    }
+  (err) => {
+    assert(err instanceof Error);
+    assert(/value/.test(err));
+    // Returning anything from validation functions besides `true` is not
+    // recommended. Doing so results in the caught error being thrown again.
+    // That is usually not the desired outcome. Throw an error about the
+    // specific validation that failed instead (as done in this example).
+    return true;
   },
   'unexpected error'
 );