diff options
| -rw-r--r-- | src/test/README.md | 42 | ||||
| -rw-r--r-- | test/README.md | 26 |
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> ``` |