doc: Improve test READMEs

2 files changed, 50 insertions, 18 deletions

diff --git a/src/test/README.md b/src/test/README.md
index 8901fae7bd..96dcb072bc 100644
--- a/src/test/README.md
+++ b/src/test/README.md
@@ -1,3 +1,15 @@
+# Unit tests
+
+The sources in this directory are unit test cases. Boost includes a
+unit testing framework, and since Bitcoin Core already uses Boost, it makes
+sense to simply use this framework rather than require developers to
+configure some other framework (we want as few impediments to creating
+unit tests as possible).
+
+The build system is set up to compile an executable called `test_bitcoin`
+that runs all of the unit tests. The main source file is called
+`setup_common.cpp`.
+
 ### Compiling/running unit tests
 
 Unit tests will be automatically compiled if dependencies were met in `./configure`
@@ -12,7 +24,7 @@ to run the bitcoind tests.
 
 To add more bitcoind 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.
+implement new `BOOST_AUTO_TEST_SUITE` sections.
 
 To run the bitcoin-qt tests manually, launch `src/qt/test/test_bitcoin-qt`
 
@@ -32,20 +44,24 @@ example, to run just the getarg_tests verbosely:
 
 Run `test_bitcoin --help` for the full list.
 
-### Note on adding test cases
-
-The sources in this directory are unit test cases.  Boost includes a
-unit testing framework, and since bitcoin already uses boost, it makes
-sense to simply use this framework rather than require developers to
-configure some other framework (we want as few impediments to creating
-unit tests as possible).
+### Adding test cases
 
-The build system is setup to compile an executable called `test_bitcoin`
-that runs all of the unit tests.  The main source file is called
-setup_common.cpp. To add a new unit test file to our test suite you need
+To add a new unit test file to our test suite you need
 to add the file to `src/Makefile.test.include`. The pattern is to create
 one test file for each class or source file for which you want to create
-unit tests.  The file naming convention is `<source_filename>_tests.cpp`
+unit tests. The file naming convention is `<source_filename>_tests.cpp`
 and such files should wrap their tests in a test suite
 called `<source_filename>_tests`. For an example of this pattern,
-examine `uint256_tests.cpp`.
+see `uint256_tests.cpp`.
+
+### Logging and debugging in unit 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
+start debugging, just like you would with bitcoind:
+
+```bash
+gdb src/test/test_bitcoin
+```
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>
 ```