From 979167c66259552d307f523eb3ca921dc56eae78 Mon Sep 17 00:00:00 2001 From: Ruben Bridgewater Date: Mon, 12 Mar 2018 22:15:49 +0100 Subject: [PATCH] assert: add warning about `assert.doesNotReject` The usefulness of `assert.doesNotReject` is very limited and this warns against the usage. PR-URL: https://github.com/nodejs/node/pull/19462 Reviewed-By: James M Snell Reviewed-By: Matteo Collina --- doc/api/assert.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index 103668b28268b1..57c2fcc47aad7d 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -383,10 +383,16 @@ added: REPLACEME * `message` {any} Awaits for the promise returned by function `block` to complete and not be -rejected. See [`assert.rejects()`][] for more details. +rejected. + +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. +function, and awaits for completion. See [`assert.rejects()`][] for more +details. Besides the async nature to await the completion behaves identical to [`assert.doesNotThrow()`][].