From 4d89fcc6d6581dfbe798fd0dc76d83fda98c1b87 Mon Sep 17 00:00:00 2001 From: Sam Roberts Date: Tue, 5 Mar 2019 10:55:37 -0800 Subject: [PATCH] doc: add guidance on console output in tests PR-URL: https://github.com/nodejs/node/pull/26456 Reviewed-By: Rich Trott Reviewed-By: Anna Henningsen Reviewed-By: Bryan English Reviewed-By: Michael Dawson Reviewed-By: Colin Ihrig Reviewed-By: Ujjwal Sharma Reviewed-By: Richard Lau --- doc/guides/writing-tests.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/doc/guides/writing-tests.md b/doc/guides/writing-tests.md index cc0623846653e2..1c8d8daf74e195 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