From 5da5f6a89b9bf8672077ea9d071ae6b3df5d64f9 Mon Sep 17 00:00:00 2001
From: Rich Trott <rtrott@gmail.com>
Date: Mon, 22 Nov 2021 22:10:19 -0800
Subject: [PATCH] doc: update BUILDING.md section on running tests

Refs: https://github.com/nodejs/node/issues/40920
---
 BUILDING.md | 40 +++++++++++++++++++++-------------------
 1 file changed, 21 insertions(+), 19 deletions(-)

diff --git a/BUILDING.md b/BUILDING.md
index a3faef3e288ddc..6553ec59832f03 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -143,8 +143,8 @@ platforms. This is true regardless of entries in the table below.
     community will only address issues that reproduce on native GNU/Linux
     systems. Issues that only reproduce on WSL should be reported in the
     [WSL issue tracker](https://github.com/Microsoft/WSL/issues). Running the
-    Windows binary (`node.exe`) in WSL is not recommended. It will not work
-    without workarounds such as stdio redirection.
+    Windows binary (`node.exe`) in WSL will not work without workarounds such as
+    stdio redirection.
 
 [^6]: Running Node.js on x86 Windows should work and binaries
     are provided. However, tests in our infrastructure only run on WoW64.
@@ -300,53 +300,55 @@ To install this version of Node.js into a system directory:
 
 To verify the build:
 
-```console
-$ make test-only
+```text
+make test-only
 ```
 
 At this point, you are ready to make code changes and re-run the tests.
 
-If you are running tests before submitting a pull request, the recommended
-command is:
+If you are running tests before submitting a pull request, use:
 
-```console
-$ make -j4 test
+```text
+make test
 ```
 
 `make -j4 test` does a full check on the codebase, including running linters and
 documentation tests.
 
-Make sure the linter does not report any issues and that all tests pass. Please
-do not submit patches that fail either check.
-
-If you want to run the linter without running tests, use
+To run the linter without running tests, use
 `make lint`/`vcbuild lint`. It will lint JavaScript, C++, and Markdown files.
 
 If you are updating tests and want to run tests in a single test file
 (e.g. `test/parallel/test-stream2-transform.js`):
 
 ```text
-$ python tools/test.py test/parallel/test-stream2-transform.js
+python tools/test.py test/parallel/test-stream2-transform.js
 ```
 
 You can execute the entire suite of tests for a given subsystem
 by providing the name of a subsystem:
 
 ```text
-$ python tools/test.py -J --mode=release child-process
+python tools/test.py child-process
+```
+
+You can also execute the tests in a tests directory (such as `test/message`):
+
+```text
+python tools/test.py message
 ```
 
 If you want to check the other options, please refer to the help by using
 the `--help` option:
 
 ```text
-$ python tools/test.py --help
+python tools/test.py --help
 ```
 
 You can usually run tests directly with node:
 
 ```text
-$ ./node ./test/parallel/test-stream2-transform.js
+./node ./test/parallel/test-stream2-transform.js
 ```
 
 Remember to recompile with `make -j4` in between test runs if you change code in
@@ -355,16 +357,16 @@ the `lib` or `src` directories.
 The tests attempt to detect support for IPv6 and exclude IPv6 tests if
 appropriate. If your main interface has IPv6 addresses, then your
 loopback interface must also have '::1' enabled. For some default installations
-on Ubuntu that does not seem to be the case. To enable '::1' on the
+on Ubuntu, that does not seem to be the case. To enable '::1' on the
 loopback interface on Ubuntu:
 
-```bash
+```text
 sudo sysctl -w net.ipv6.conf.lo.disable_ipv6=0
 ```
 
 You can use
 [node-code-ide-configs](https://github.com/nodejs/node-code-ide-configs)
-to run/debug tests, if your IDE configs are present.
+to run/debug tests if your IDE configs are present.
 
 #### Running coverage