3e1ee31043
blockchain.cpp has low unit test coverage. This commit is intended
to start improving its code coverage to reasonable levels. One or more
follow up commits will complete the task that this commit is starting
(though the usefulness of this commit is not dependent upon later
commits).
Note that these tests were not written based upon a specification of how
GetDifficulty *should* work, but rather how it actually *does* work. As
a result, if there are any bugs in the current GetDifficulty
implementation, these unit tests serve to lock them in rather than
expose them.
-- Why has blockchain.cpp been modified if this is a unit testing change?
Since the existing GetDifficulty function relies on a global variable,
chainActive, it was not suitable for unit testing purposes. Both the
existing GetDifficulty function and the unit tests now call through to
a new, more modular version of GetDifficulty that can work on any chain,
not just chainActive.
-- Why does blockchain_tests.cpp directly include blockchain.cpp instead
of blockchain.h?
While the new GetDifficulty function's signature is arguably better than
the old one's, it still isn't great, and doesn't seem to warrant inclusion
as part of the blockchain.h API, especially since only test code is
directly using it. If a better way of exposing the new GetDifficulty
function to unit tests exists, please mention it and the commit will be
updated accordingly.
-- Why is the test fixture named blockchain_difficulty_tests rather than
blockchain_tests?
The Bitcoin Core policy for naming unit test files is to match the the
file under test ("blockchain" becomes "blockchain_tests"). While this
commit complies with that, blockchain.cpp is a massive file, such that
having all of the unit tests in one file will tend towards disorder.
Since there will be a lot more tests added to this file, the intention
is to divide up different types of tests into different test fixtures
within the same file.
Compiling/running unit tests
Unit tests will be automatically compiled if dependencies were met in ./configure
and tests weren't explicitly disabled.
After configuring, they can be run with make check.
To run the bitcoind tests manually, launch src/test/test_bitcoin. To recompile
after a test file was modified, run make and then run the test again. If you
modify a non-test file, use make -C src/test to recompile only what's needed
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.
To run the bitcoin-qt tests manually, launch src/qt/test/test_bitcoin-qt
To add more bitcoin-qt tests, add them to the src/qt/test/ directory and
the src/qt/test/test_main.cpp file.
Running individual tests
test_bitcoin has some built-in command-line arguments; for example, to run just the getarg_tests verbosely:
test_bitcoin --log_level=all --run_test=getarg_tests
... or to run just the doubledash test:
test_bitcoin --run_test=getarg_tests/doubledash
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).
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
test_bitcoin.cpp. 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
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.
For further reading, I found the following website to be helpful in explaining how the boost unit test framework works: http://www.alittlemadness.com/2009/03/31/c-unit-testing-with-boosttest/.