Changeset View
Changeset View
Standalone View
Standalone View
doc/unit-tests.md
- This file was moved from src/test/README.md.
### Compiling/running unit tests | ### Compiling/running unit tests | ||||
Unit tests will be automatically compiled if dependencies were met in `./configure` | Unit tests will be automatically compiled if dependencies were met in `./configure` | ||||
and tests weren't explicitly disabled. | and tests weren't explicitly disabled. | ||||
After configuring, they can be run with `make check`. | After configuring, they can be run with `make check`. | ||||
To run the bitcoind tests manually, launch `src/test/test_bitcoin`. | To run the bitcoind tests manually, launch `src/test/test_bitcoin`. | ||||
To add more bitcoind tests, add `BOOST_AUTO_TEST_CASE` functions to the existing | 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 | .cpp files in the `src/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` | 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 | To add more bitcoin-qt tests, add them to the `src/qt/test/` directory and | ||||
the `src/qt/test/test_main.cpp` file. | the `src/qt/test/test_main.cpp` file. | ||||
### Running individual tests | ### Running individual tests | ||||
test_bitcoin has some built-in command-line arguments; for | test_bitcoin has some built-in command-line arguments; for | ||||
example, to run just the getarg_tests verbosely: | example, to run just the getarg_tests verbosely: | ||||
test_bitcoin --log_level=all --run_test=getarg_tests | test_bitcoin --log_level=all --run_test=getarg_tests | ||||
... or to run just the doubledash test: | ... or to run just the doubledash test: | ||||
test_bitcoin --run_test=getarg_tests/doubledash | test_bitcoin --run_test=getarg_tests/doubledash | ||||
Run `test_bitcoin --help` for the full list. | Run `test_bitcoin --help` for the full list. | ||||
### Note on adding test cases | ### 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` | 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 | 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 | 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 | 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 | 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 | and such files should wrap their tests in a test suite | ||||
called `<source_filename>_tests`. For an example of this pattern, | called `<source_filename>_tests`. For an example of this pattern, | ||||
examine `uint256_tests.cpp`. | examine `uint256_tests.cpp`. | ||||
For further reading, I found the following website to be helpful in | For further reading, I found the following website to be helpful in | ||||
explaining how the boost unit test framework works: | explaining how the boost unit test framework works: | ||||
[http://www.alittlemadness.com/2009/03/31/c-unit-testing-with-boosttest/](http://www.alittlemadness.com/2009/03/31/c-unit-testing-with-boosttest/). | [http://www.alittlemadness.com/2009/03/31/c-unit-testing-with-boosttest/](http://www.alittlemadness.com/2009/03/31/c-unit-testing-with-boosttest/). | ||||
### Debugging unit tests | |||||
Simple example of debugging unit tests with GDB on Linux: | |||||
``` | |||||
cd /build/src/test | |||||
gdb test_bitcoin | |||||
break interpreter.cpp:295 # No path is necessary, just the file name and line number | |||||
run | |||||
# GDB hits the breakpoint | |||||
p/x opcode # print the value of the variable (in this case, opcode) in hex | |||||
c # continue | |||||
``` | |||||
Simple example of debugging unit tests with LLDB (OSX or Linux): | |||||
``` | |||||
cd /build/src/test | |||||
lldb -- test_bitcoin | |||||
break set --file interpreter.cpp --line 295 | |||||
run | |||||
``` |