doc,test: document common.mustSucceed

doc/guides/writing-tests.md

@@ -209,6 +209,11 @@ const server = http.createServer(common.mustCall((req, res) => {
 
 ```
 
+**Note:** Many functions invoke their callback with an `err` value as the first
+argument. It is not a good idea to simply pass `common.mustCall()` to those
+because `common.mustCall()` will ignore the error. Use `common.mustSucceed()`
+instead.
+
 #### Countdown Module
 
 The common [Countdown module](https://github.com/nodejs/node/tree/master/test/common#countdown-module)

test/common/README.md

@@ -314,6 +314,15 @@ If `fn` is not provided, an empty function will be used.
 Returns a function that triggers an `AssertionError` if it is invoked. `msg` is
 used as the error message for the `AssertionError`.
 
+### `mustSucceed([fn])`
+
+* `fn` [<Function>][] default = () => {}
+* return [<Function>][]
+
+Returns a function that accepts arguments `(err, ...args)`. If `err` is not
+`undefined` or `null`, it triggers an `AssertionError`. Otherwise, it calls
+`fn(...args)`.
+
 ### `nodeProcessAborted(exitCode, signal)`
 
 * `exitCode` [<number>][]