Merge #18486: doc: Explain new test logging

7777703958 doc: Explain new test logging (MarcoFalke)

Pull request description:

  Explain logging added in #18472 and #16975

ACKs for top commit:
  jonatack:
    ACK 7777703

Tree-SHA512: 3a0aa7bab32a6753d8894d29cf82604b044b23e512102dd275b717eefda3c2212dbf43ea7e9155267350dd9f3bc5badba2eb660152db3efeab30a04f52126c95

src/test/README.md

@@ -17,26 +17,31 @@ and tests weren't explicitly disabled.
 
 After configuring, they can be run with `make check`.
 
-To run the bitcoind tests manually, launch `src/test/test_bitcoin`. To recompile
+To run the unit tests manually, launch `src/test/test_bitcoin`. To recompile
 after a test file was modified, run `make` and then run the test again. If you
 modify a non-test file, use `make -C src/test` to recompile only what's needed
-to run the bitcoind tests.
+to run the unit tests.
 
-To add more bitcoind tests, add `BOOST_AUTO_TEST_CASE` functions to the existing
+To add more unit tests, add `BOOST_AUTO_TEST_CASE` functions to the existing
 .cpp files in the `test/` directory or add new .cpp files that
 implement new `BOOST_AUTO_TEST_SUITE` sections.
 
-To run the bitcoin-qt tests manually, launch `src/qt/test/test_bitcoin-qt`
+To run the GUI unit tests manually, launch `src/qt/test/test_bitcoin-qt`
 
-To add more bitcoin-qt tests, add them to the `src/qt/test/` directory and
+To add more GUI unit tests, add them to the `src/qt/test/` directory and
 the `src/qt/test/test_main.cpp` file.
 
 ### Running individual tests
 
-test_bitcoin has some built-in command-line arguments; for
+`test_bitcoin` has some built-in command-line arguments; for
-example, to run just the getarg_tests verbosely:
+example, to run just the `getarg_tests` verbosely:
 
-    test_bitcoin --log_level=all --run_test=getarg_tests
+    test_bitcoin --log_level=all --run_test=getarg_tests -- DEBUG_LOG_OUT
+
+`log_level` controls the verbosity of the test framework, which logs when a
+test case is entered, for example. The `DEBUG_LOG_OUT` after the two dashes
+redirects the debug log, which would normally go to a file in the test datadir
+(`BasicTestingSetup::m_path_root`), to the standard terminal output.
 
 ... or to run just the doubledash test:
 
@@ -56,11 +61,15 @@ see `uint256_tests.cpp`.
 
 ### Logging and debugging in unit tests
 
+`make check` will write to a log file `foo_tests.cpp.log` and display this file
+on failure. For running individual tests verbosely, refer to the section
+[above](#running-individual-tests).
+
 To write to logs from unit tests you need to use specific message methods
 provided by Boost. The simplest is `BOOST_TEST_MESSAGE`.
 
-For debugging you can launch the test_bitcoin executable with `gdb`or `lldb` and
+For debugging you can launch the `test_bitcoin` executable with `gdb`or `lldb` and
-start debugging, just like you would with bitcoind:
+start debugging, just like you would with any other program:
 
 ```bash
 gdb src/test/test_bitcoin