doc: add a note about require('../common') in testing documentation

Aditi-1400 · targos · commit 5b2dfadd4063 · 2025-02-17T10:46:00.000+01:00
PR-URL: #56953 Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Richard Lau <rlau@redhat.com>
diff --git a/test/common/README.md b/test/common/README.md
@@ -1,6 +1,29 @@
 # Node.js Core Test Common Modules
 
 This directory contains modules used to test the Node.js implementation.
+All tests must begin by requiring the `common` module:
+
+```js
+require('../common');
+```
+
+This is not just a convenience for exporting helper functions etc; it also performs
+several other tasks:
+
+* Verifies that no unintended globals have been leaked to ensure that tests
+  don't accidentally pollute the global namespace.
+
+* Some tests assume a default umask of `0o022`. To enforce this assumption,
+  the common module sets the unmask at startup. Tests that require a
+  different umask can override this setting after loading the module.
+
+* Some tests specify runtime flags (example, `--expose-internals`) via a
+  comment at the top of the file: `// Flags: --expose-internals`.
+  If the test is run without those flags, the common module automatically
+  spawns a child process with proper flags. This ensures that the tests
+  always run under the expected conditions. Because of this behaviour, the
+  common module must be loaded first so that any code below it is not
+  executed until the process has been re-spawned with the correct flags.
 
 ## Table of contents
 
