Merge #16953: doc: Improve test READMEs

43e7d576f590e90ad7d1ba3d550671a7958f1188 doc: Improve test READMEs (Fabian Jahr)

Pull request description:

  General improvements on READMEs for unit tests and functional tests:
  - Give unit test readme a headline
  - Move general information on `src/test` folder to the top
  - Add information on logging and debugging unit tests
  - Improve debugging and logging information in functional testing
  - Include all available log levels in functional tests

ACKs for top commit:
  laanwj:
    ACK 43e7d576f590e90ad7d1ba3d550671a7958f1188

Tree-SHA512: 22b27644992ba5d99a885cd51b7a474806714396fcea1fd2d6285e41bdf3b28835ad8c81449099e3ee15a63d57b3ab9acb89c425d9855ed1d9b4af21db35ab03

1 files changed, 21 insertions, 5 deletions

diff --git a/test/README.md b/test/README.md
index 8f08b7afe4..26fd525064 100644
--- a/test/README.md
+++ b/test/README.md
@@ -136,8 +136,10 @@ killall bitcoind
 
 ##### Test logging
 
-The tests contain logging at different levels (debug, info, warning, etc). By
-default:
+The tests contain logging at five different levels (DEBUG, INFO, WARNING, ERROR
+and CRITICAL). From within your functional tests you can log to these different
+levels using the logger included in the test_framework, e.g.
+`self.log.debug(object)`. By default:
 
 - when run through the test_runner harness, *all* logs are written to
   `test_framework.log` and no logs are output to the console.
@@ -182,18 +184,32 @@ call methods that interact with the bitcoind nodes-under-test.
 If further introspection of the bitcoind instances themselves becomes
 necessary, this can be accomplished by first setting a pdb breakpoint
 at an appropriate location, running the test to that point, then using
-`gdb` to attach to the process and debug.
+`gdb` (or `lldb` on macOS) to attach to the process and debug.
 
-For instance, to attach to `self.node[1]` during a run:
+For instance, to attach to `self.node[1]` during a run you can get
+the pid of the node within `pdb`.
+
+```
+(pdb) self.node[1].process.pid
+```
+
+Alternatively, you can find the pid by inspecting the temp folder for the specific test
+you are running. The path to that folder is printed at the beginning of every
+test run:
 
 ```bash
 2017-06-27 14:13:56.686000 TestFramework (INFO): Initializing test directory /tmp/user/1000/testo9vsdjo3
 ```
 
-use the directory path to get the pid from the pid file:
+Use the path to find the pid file in the temp folder:
 
 ```bash
 cat /tmp/user/1000/testo9vsdjo3/node1/regtest/bitcoind.pid
+```
+
+Then you can use the pid to start `gdb`:
+
+```bash
 gdb /home/example/bitcoind <pid>
 ```