test: make crashOnUnhandleRejection opt-out

This commit removes `common.crashOnUnhandledRejection()` and adds
`common.disableCrashOnUnhandledRejection()`.

To reduce the risk of mistakes and make writing tests that involve
promises simpler, always install the unhandledRejection hook in tests
and provide a way to disable it for the rare cases where it's needed.

PR-URL: https://github.com/nodejs/node/pull/21849
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Gus Caplan <me@gus.host>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

1 files changed, 9 insertions, 19 deletions

diff --git a/doc/guides/writing-tests.md b/doc/guides/writing-tests.md
index e4a9e296ff..2059a709ff 100644
--- a/doc/guides/writing-tests.md
+++ b/doc/guides/writing-tests.md
@@ -225,34 +225,24 @@ countdown.dec(); // The countdown callback will be invoked now.
 
 #### Testing promises
 
-When writing tests involving promises, either make sure that the
-`onFulfilled` or the `onRejected` handler is wrapped in
-`common.mustCall()` or `common.mustNotCall()` accordingly, or
-call `common.crashOnUnhandledRejection()` in the top level of the
-test to make sure that unhandled rejections would result in a test
-failure. For example:
+When writing tests involving promises, it is generally good to wrap the
+`onFulfilled` handler, otherwise the test could successfully finish if the
+promise never resolves (pending promises do not keep the event loop alive). The
+`common` module automatically adds a handler that makes the process crash - and
+hence, the test fail - in the case of an `unhandledRejection` event. It is
+possible to disable it with `common.disableCrashOnUnhandledRejection()` if
+needed.
 
 ```javascript
 const common = require('../common');
 const assert = require('assert');
 const fs = require('fs').promises;
 
-// Use `common.crashOnUnhandledRejection()` to make sure unhandled rejections
-// will fail the test.
-common.crashOnUnhandledRejection();
-
-// Or, wrap the `onRejected` handler in `common.mustNotCall()`.
-fs.writeFile('test-file', 'test').catch(common.mustNotCall());
-
-// Or, wrap the `onFulfilled` handler in `common.mustCall()`.
-// If there are assertions in the `onFulfilled` handler, wrap
-// the next `onRejected` handler in `common.mustNotCall()`
-// to handle potential failures.
+// Wrap the `onFulfilled` handler in `common.mustCall()`.
 fs.readFile('test-file').then(
   common.mustCall(
     (content) => assert.strictEqual(content.toString(), 'test2')
-  ))
-  .catch(common.mustNotCall());
+  ));
 ```
 
 ### Flags