test: add docs for common.debuglog behaviour

Author: Sarat Addepalli

test/common/README.md

@@ -59,11 +59,20 @@ Platform normalizes the `dd` command
 
 ### debuglog([fmt, ]msg[, msgs])
 * `fmt` [<string>] Optional format string
-* `msg` [<string>] The string to be printed to stderr
+* `msg` [<string>] The string to be printed
 * `msgs` [<string>] Additional arguments to the function
 
-Prints messages (optionally, formatted using `fmt`) to `process.stderr`,
-using `util.debuglog('test')`.
+Prints messages (optionally, formatted using `fmt`). Since [`util.debuglog()`]
+is used internally (invoked as `util.debuglog('test')`), these messages will be
+visible only when `NODE_DEBUG` environment variable is set with `test`.
+
+```sh
+// when NODE_DEBUG is not set, or doesn\'t contain `test`, prints nothing.
+$ NODE_DEBUG=fs,net ./node test/fixtures/common-debuglog.js hello world
+// when NODE_DEBUG contains `test`, messages are printed to `process.stderr`
+$ NODE_DEBUG=test,fs,net ./node test/fixtures/common-debuglog.js hello world
+TEST 89440: hello world
+```
 
 ### disableCrashOnUnhandledRejection()
 
@@ -810,3 +819,4 @@ implementation with tests from
 [`hijackstdio.hijackStdErr()`]: #hijackstderrlistener
 [`hijackstdio.hijackStdOut()`]: #hijackstdoutlistener
 [internationalization]: https://github.com/nodejs/node/wiki/Intl
+[`util.debuglog()`]: https://nodejs.org/api/util.html#util_util_debuglog_section

test/fixtures/common-debuglog.js

@@ -3,4 +3,4 @@
 const common = require('../common');
 
 // argv[0] is the execPath, argv[1] is the test script filename
-common.debuglog.apply(null, process.argv.slice(2));
+common.debuglog(...process.argv.slice(2));

test/parallel/test-common-debuglog.js

@@ -2,15 +2,15 @@
 
 require('../common');
 const assert = require('assert');
-const path = require('path');
+const fixtures = require('../common/fixtures');
 const { spawnSync } = require('child_process');
 
 const message = 'message';
 
 {
   process.env.NODE_DEBUG = 'test';
   const { stderr } = spawnSync(process.execPath, [
-    path.resolve(__dirname, '../fixtures/common-debuglog.js'),
+    fixtures.path('common-debuglog.js'),
     message
   ], { encoding: 'utf8' });
 
@@ -21,7 +21,7 @@ const message = 'message';
 {
   delete process.env.NODE_DEBUG;
   const { stderr } = spawnSync(process.execPath, [
-    path.resolve(__dirname, '../fixtures/common-debuglog.js'),
+    fixtures.path('common-debuglog.js'),
     message
   ], { encoding: 'utf8' });
 
@@ -31,7 +31,7 @@ const message = 'message';
 {
   process.env.NODE_DEBUG = 'fs';
   const { stderr } = spawnSync(process.execPath, [
-    path.resolve(__dirname, '../fixtures/common-debuglog.js'),
+    fixtures.path('common-debuglog.js'),
     message
   ], { encoding: 'utf8' });