Merge #17177: doc: Describe log files + consistent paths in test READMEs

9576614d2d91ca946d164dfffca441f8bcbd6e2c doc: Describe log files + consistent paths in test READMEs (Martin Erlandsson)

Pull request description:

  picks up #15830

  I saw this was almost ready to merge but the test logging part was not 100% correct. I reworked that part, the rest is the same.

ACKs for top commit:
  GChuf:
    ACK 9576614d2d91ca946d164dfffca441f8bcbd6e2c

Tree-SHA512: 3de7f1b0a1b0419df6e7b55964d00e715b6cb7874b1849ad6f120597610d7df4182c4b61b9c9691ce04f4e392ed3caead4c623374be2066ac31319e702d45d09

2 files changed, 31 insertions, 19 deletions

diff --git a/test/README.md b/test/README.md
index 26fd525064..11adc11278 100644
--- a/test/README.md
+++ b/test/README.md
@@ -88,7 +88,7 @@ By default, up to 4 tests will be run in parallel by test_runner. To specify
 how many jobs to run, append `--jobs=n`
 
 The individual tests and the test_runner harness have many command-line
-options. Run `test_runner.py -h` to see them all.
+options. Run `test/functional/test_runner.py -h` to see them all.
 
 #### Troubleshooting and debugging test failures
 
@@ -101,7 +101,7 @@ killed all its bitcoind nodes), then there may be a port conflict which will
 cause the test to fail. It is recommended that you run the tests on a system
 where no other bitcoind processes are running.
 
-On linux, the test_framework will warn if there is another
+On linux, the test framework will warn if there is another
 bitcoind process running when the tests are started.
 
 If there are zombie bitcoind processes after test failure, you can kill them
@@ -130,7 +130,7 @@ tests will fail. If this happens, remove the cache directory (and make
 sure bitcoind processes are stopped as above):
 
 ```bash
-rm -rf cache
+rm -rf test/cache
 killall bitcoind
 ```
 
@@ -149,6 +149,15 @@ levels using the logger included in the test_framework, e.g.
   fails, the `test_framework.log` and bitcoind `debug.log`s will all be dumped
   to the console to help troubleshooting.
 
+These log files can be located under the test data directory (which is always
+printed in the first line of test output):
+  - `<test data directory>/test_framework.log`
+  - `<test data directory>/node<node number>/regtest/debug.log`.
+
+The node number identifies the relevant test node, starting from `node0`, which
+corresponds to its position in the nodes list of the specific test,
+e.g. `self.nodes[0]`.
+
 To change the level of logs output to the console, use the `-l` command line
 argument.
 
@@ -157,7 +166,7 @@ aggregate log by running the `combine_logs.py` script. The output can be plain
 text, colorized text or html. For example:
 
 ```
-combine_logs.py -c <test data directory> | less -r
+test/functional/combine_logs.py -c <test data directory> | less -r
 ```
 
 will pipe the colorized logs from the test into less.
diff --git a/test/functional/README.md b/test/functional/README.md
index 197c2afbe4..a9b83076eb 100644
--- a/test/functional/README.md
+++ b/test/functional/README.md
@@ -4,13 +4,13 @@
 
 #### Example test
 
-The [example_test.py](example_test.py) is a heavily commented example of a test case that uses both
-the RPC and P2P interfaces. If you are writing your first test, copy that file
-and modify to fit your needs.
+The file [test/functional/example_test.py](example_test.py) is a heavily commented example
+of a test case that uses both the RPC and P2P interfaces. If you are writing your first test, copy
+that file and modify to fit your needs.
 
 #### Coverage
 
-Running `test_runner.py` with the `--coverage` argument tracks which RPCs are
+Running `test/functional/test_runner.py` with the `--coverage` argument tracks which RPCs are
 called by the tests and prints a report of uncovered RPCs in the summary. This
 can be used (along with the `--extended` argument) to find out which RPCs we
 don't have test cases for.
@@ -82,7 +82,7 @@ P2P messages. These can be found in the following source files:
 
 #### Using the P2P interface
 
-- `messages.py` contains all the definitions for objects that pass
+- [messages.py](test_framework/messages.py) contains all the definitions for objects that pass
 over the network (`CBlock`, `CTransaction`, etc, along with the network-level
 wrappers for them, `msg_block`, `msg_tx`, etc).
 
@@ -96,32 +96,35 @@ the Bitcoin Core node application logic. For custom behaviour, subclass the
 P2PInterface object and override the callback methods.
 
 - Can be used to write tests where specific P2P protocol behavior is tested.
-Examples tests are `p2p_unrequested_blocks.py`, `p2p_compactblocks.py`.
+Examples tests are [p2p_unrequested_blocks.py](p2p_unrequested_blocks.py),
+[p2p_compactblocks.py](p2p_compactblocks.py).
 
-### test-framework modules
+### Test framework modules
+The following are useful modules for test developers. They are located in
+[test/functional/test_framework/](test_framework).
 
-#### [test_framework/authproxy.py](test_framework/authproxy.py)
+#### [authproxy.py](test_framework/authproxy.py)
 Taken from the [python-bitcoinrpc repository](https://github.com/jgarzik/python-bitcoinrpc).
 
-#### [test_framework/test_framework.py](test_framework/test_framework.py)
+#### [test_framework.py](test_framework/test_framework.py)
 Base class for functional tests.
 
-#### [test_framework/util.py](test_framework/util.py)
+#### [util.py](test_framework/util.py)
 Generally useful functions.
 
-#### [test_framework/mininode.py](test_framework/mininode.py)
+#### [mininode.py](test_framework/mininode.py)
 Basic code to support P2P connectivity to a bitcoind.
 
-#### [test_framework/script.py](test_framework/script.py)
+#### [script.py](test_framework/script.py)
 Utilities for manipulating transaction scripts (originally from python-bitcoinlib)
 
-#### [test_framework/key.py](test_framework/key.py)
+#### [key.py](test_framework/key.py)
 Test-only secp256k1 elliptic curve implementation
 
-#### [test_framework/bignum.py](test_framework/bignum.py)
+#### [bignum.py](test_framework/bignum.py)
 Helpers for script.py
 
-#### [test_framework/blocktools.py](test_framework/blocktools.py)
+#### [blocktools.py](test_framework/blocktools.py)
 Helper functions for creating blocks and transactions.
 
 ### Benchmarking with perf