doc: add guidance on console output in tests

PR-URL: https://github.com/nodejs/node/pull/26456
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Bryan English <bryan@bryanenglish.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Ujjwal Sharma <usharma1998@gmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>

1 files changed, 26 insertions, 0 deletions

diff --git a/doc/guides/writing-tests.md b/doc/guides/writing-tests.md
index cc06238466..1c8d8daf74 100644
--- a/doc/guides/writing-tests.md
+++ b/doc/guides/writing-tests.md
@@ -281,6 +281,32 @@ assert.throws(
 );
 ```
 
+### Console output
+
+Output written by tests to stdout or stderr, such as with `console.log()` or
+`console.error()`, can be useful when writing tests, as well as for debugging
+them during later maintenance.  The output will be supressed by the test runner
+(`./tools/test.py`) unless the test fails, but will always be displayed when
+running tests directly with `node`. For failing tests, the test runner will
+include the output along with the failed test assertion in the test report.
+
+Some output can help debugging by giving context to test failures. For example,
+when troubleshooting tests that timeout in CI. With no log statements, we have
+no idea where the test got hung up. There have been cases where tests fail
+without `console.log()`, and then pass when its added, so be cautious about its
+use, particularly in tests of the I/O and streaming APIs.
+
+Excessive use of console output is discouraged as it can overwhelm the display,
+including the Jenkins console and test report displays.  Be particularly
+cautious of output in loops, or other contexts where output may be repeated many
+times in the case of failure.
+
+In some tests, it can be unclear whether a `console.log()` statement is required
+as part of the test (message tests, tests that check output from child
+processes, etc.), or is there as a debug aide. If there is any chance of
+confusion, use comments to make the purpose clear.
+
+
 ### ES.Next features
 
 For performance considerations, we only use a selected subset of ES.Next