Merge bitcoin/bitcoin#30890: doc: unit test runner help fixup and imp…

…rovements

282f0e9 Unit test runner documentation fix and improvements (Jon Atack)

Pull request description:

  Running `test_bitcoin --help` prints the list of arguments that may be passed, not the list of tests, so fix that.

  Improve the content and order of the unit test documentation.

ACKs for top commit:
  pablomartin4btc:
    re-ACK 282f0e9
  tdb3:
    re ACK 282f0e9

Tree-SHA512: 0d25108ab641bcd9b53f99d139afeec90a34f44d5b00c3c677f7539d87782440a28fadc348663b8c28ace43552834737b9c1e8f5517c68edc8547695a9cb5063

src/test/README.md

@@ -10,14 +10,19 @@ The build system is set up to compile an executable called `test_bitcoin`
 that runs all of the unit tests. The main source file for the test library is found in
 `util/setup_common.cpp`.
 
+The examples in this document assume the build directory is named
+`build`. You'll need to adapt them if you named it differently.
+
 ### Compiling/running unit tests
 
 Unit tests will be automatically compiled if dependencies were met
 during the generation of the Bitcoin Core build system
 and tests weren't explicitly disabled.
 
-Assuming the build directory is named `build`, the unit tests can be run
-with `ctest --test-dir build`, which includes unit tests from subtrees.
+The unit tests can be run with `ctest --test-dir build`, which includes unit
+tests from subtrees.
+
+Run `test_bitcoin --list_content` for the full list of tests.
 
 To run the unit tests manually, launch `build/src/test/test_bitcoin`. To recompile
 after a test file was modified, run `cmake --build build` and then run the test again. If you
@@ -35,34 +40,45 @@ the `src/qt/test/test_main.cpp` file.
 
 ### Running individual tests
 
-`test_bitcoin` accepts the command line arguments from the boost framework.
-For example, to run just the `getarg_tests` suite of tests:
+The `test_bitcoin` runner accepts command line arguments from the Boost
+framework. To see the list of arguments that may be passed, run:
+
+```
+test_bitcoin --help
+```
+
+For example, to run only the tests in the `getarg_tests` file, with full logging:
 
 ```bash
 build/src/test/test_bitcoin --log_level=all --run_test=getarg_tests
 ```
 
-`log_level` controls the verbosity of the test framework, which logs when a
-test case is entered, for example.
+or
 
-`test_bitcoin` also accepts some of the command line arguments accepted by
-`bitcoind`. Use `--` to separate these sets of arguments:
+```bash
+build/src/test/test_bitcoin -l all -t getarg_tests
+```
+
+or to run only the doubledash test in `getarg_tests`
 
 ```bash
-build/src/test/test_bitcoin --log_level=all --run_test=getarg_tests -- -printtoconsole=1
+build/src/test/test_bitcoin --run_test=getarg_tests/doubledash
 ```
 
-The `-printtoconsole=1` after the two dashes sends debug logging, which
-normally goes only to `debug.log` within the data directory, also to the
-standard terminal output.
+The `--log_level=` (or `-l`) argument controls the verbosity of the test output.
 
-... or to run just the doubledash test:
+The `test_bitcoin` runner also accepts some of the command line arguments accepted by
+`bitcoind`. Use `--` to separate these sets of arguments:
 
 ```bash
-build/src/test/test_bitcoin --run_test=getarg_tests/doubledash
+build/src/test/test_bitcoin --log_level=all --run_test=getarg_tests -- -printtoconsole=1
 ```
 
-`test_bitcoin` creates a temporary working (data) directory with a randomly
+The `-printtoconsole=1` after the two dashes sends debug logging, which
+normally goes only to `debug.log` within the data directory, to the
+standard terminal output as well.
+
+Running `test_bitcoin` creates a temporary working (data) directory with a randomly
 generated pathname within `test_common bitcoin/`, which in turn is within
 the system's temporary directory (see
 [`temp_directory_path`](https://en.cppreference.com/w/cpp/filesystem/temp_directory_path)).
@@ -97,8 +113,6 @@ If you run an entire test suite, such as `--run_test=getarg_tests`, or all the t
 (by not specifying `--run_test`), a separate directory
 will be created for each individual test.
 
-Run `test_bitcoin --help` for the full list of tests.
-
 ### Adding test cases
 
 To add a new unit test file to our test suite, you need