aboutsummaryrefslogtreecommitdiff
path: root/src/test/README.md
diff options
context:
space:
mode:
authorFabian Jahr <fjahr@protonmail.com>2019-09-24 14:42:18 +0200
committerFabian Jahr <fjahr@protonmail.com>2019-09-26 19:04:58 +0200
commit43e7d576f590e90ad7d1ba3d550671a7958f1188 (patch)
treefd463a532082eff65c9ef1ef3d0bbcc223755e3d /src/test/README.md
parent3ce829888861a6dc6a29da669584ada961d965fa (diff)
doc: Improve test READMEs
Diffstat (limited to 'src/test/README.md')
-rw-r--r--src/test/README.md42
1 files changed, 29 insertions, 13 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
+```