assert: add warning about assert.doesNotReject

The usefulness of `assert.doesNotReject` is very limited and this warns against the usage. PR-URL: #19462 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Matteo Collina <[email protected]>
nodejs · Mar 24, 2018 · 5d6d1fe · 5d6d1fe
1 parent 0863a0e
commit 5d6d1fe
Showing 1 changed file with 8 additions and 2 deletions.
diff --git a/doc/api/assert.md b/doc/api/assert.md
@@ -321,10 +321,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 identically to
 [`assert.doesNotThrow()`][].