doc: add guides on writing tests involving promises

Mention `common.crashOnUnhandledRejection()` and wrapping the
handlers in `common.mustCall()` or `common.mustNotCall()`.

PR-URL: https://github.com/nodejs/node/pull/20988
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

1 files changed, 31 insertions, 0 deletions

diff --git a/doc/guides/writing-tests.md b/doc/guides/writing-tests.md
index 340d527dd2..ac2844ebf4 100644
--- a/doc/guides/writing-tests.md
+++ b/doc/guides/writing-tests.md
@@ -223,6 +223,37 @@ countdown.dec();
 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:
+
+```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.
+fs.readFile('test-file').then(
+  common.mustCall(
+    (content) => assert.strictEqual(content.toString(), 'test2')
+  ))
+  .catch(common.mustNotCall());
+```
 
 ### Flags