Changeset View
Changeset View
Standalone View
Standalone View
doc/unit-tests.md
### Compiling/running unit tests | ### Compiling/running unit tests | ||||
Unit tests are not part of the default build but can be built on demand. | Unit tests are not part of the default build but can be built on demand. | ||||
All the unit tests can be built and run with a single command: `ninja check`. | All the unit tests can be built and run with a single command: `ninja check`. | ||||
#### bitcoind unit tests | #### ecashd unit tests | ||||
The `bitcoind` unit tests can be built with `ninja test_bitcoin`. | The `ecashd` unit tests can be built with `ninja test_ecash`. | ||||
They can also be built and run in a single command with `ninja check-bitcoin`. | They can also be built and run in a single command with `ninja check-bitcoin`. | ||||
To run the `bitcoind` tests manually, launch `src/test/test_bitcoin`. | To run the `ecashd` tests manually, launch `src/test/test_ecash`. | ||||
To add more `bitcoind` tests, add `BOOST_AUTO_TEST_CASE` functions to the | To add more `ecashd` tests, add `BOOST_AUTO_TEST_CASE` functions to the | ||||
existing .cpp files in the `src/test/` directory or add new .cpp files that | existing .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. | ||||
#### bitcoin-qt unit tests | #### ecash-qt unit tests | ||||
The `bitcoin-qt` tests can be built with `ninja test_bitcoin-qt` or | The `ecash-qt` tests can be built with `ninja test_ecash-qt` or | ||||
built and run in a single command with `ninja check-bitcoin-qt`. | built and run in a single command with `ninja check-ecash-qt`. | ||||
To run the `bitcoin-qt` tests manually, launch `src/qt/test/test_bitcoin-qt`. | To run the `ecash-qt` tests manually, launch `src/qt/test/test_ecash-qt`. | ||||
To add more `bitcoin-qt` tests, add them to the `src/qt/test/` directory and | To add more `ecash-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. | ||||
#### bitcoin-seeder unit tests | #### bitcoin-seeder unit tests | ||||
The `bitcoin-seeder` unit tests can be built with `ninja test-seeder` or | The `bitcoin-seeder` unit tests can be built with `ninja test-seeder` or | ||||
built and run in a single command with `ninja check-seeder`. | built and run in a single command with `ninja check-seeder`. | ||||
To run the `bitcoin-seeder` tests manually, launch | To run the `bitcoin-seeder` tests manually, launch | ||||
`src/seeder/test/test-seeder`. | `src/seeder/test/test-seeder`. | ||||
To add more `bitcoin-seeder` tests, add `BOOST_AUTO_TEST_CASE` functions to the | To add more `bitcoin-seeder` tests, add `BOOST_AUTO_TEST_CASE` functions to the | ||||
existing .cpp files in the `src/seeder/test/` directory or add new .cpp files | existing .cpp files in the `src/seeder/test/` directory or add new .cpp files | ||||
that implement new `BOOST_AUTO_TEST_SUITE` sections. | that implement new `BOOST_AUTO_TEST_SUITE` sections. | ||||
### Running individual tests | ### Running individual tests | ||||
`test_bitcoin` has some built-in command-line arguments; for | `test_ecash` 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_ecash --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_ecash --run_test=getarg_tests/doubledash | ||||
Run `test_bitcoin --help` for the full list. | Run `test_ecash --help` for the full list. | ||||
### Adding test cases | ### Adding test cases | ||||
The build system is setup to compile an executable called `test_bitcoin` | The build system is setup to compile an executable called `test_ecash` | ||||
that runs all of the unit tests. The main source file for the test library | that runs all of the unit tests. The main source file for the test library | ||||
is found in `util/setup_common.cpp`. To add a new unit test file to our | is found in `util/setup_common.cpp`. To add a new unit test file to our | ||||
test suite you need to add the file to `src/test/CMakeLists.txt`. | test suite you need to add the file to `src/test/CMakeLists.txt`. | ||||
The pattern is to create one test file for each class or source file for | 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 | which you want to create unit tests. The file naming convention is | ||||
`<source_filename>_tests.cpp` and such files should wrap their tests in | `<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, | a test suite called `<source_filename>_tests`. For an example of this pattern, | ||||
see `uint256_tests.cpp`. | see `uint256_tests.cpp`. | ||||
For further reading, I found the following websites to be helpful in | For further reading, I found the following websites to be helpful in | ||||
explaining how the boost unit test framework works: | explaining how the boost unit test framework works: | ||||
[https://legalizeadulthood.wordpress.com/2009/07/04/c-unit-tests-with-boost-test-part-1/](https://legalizeadulthood.wordpress.com/2009/07/04/c-unit-tests-with-boost-test-part-1/) | [https://legalizeadulthood.wordpress.com/2009/07/04/c-unit-tests-with-boost-test-part-1/](https://legalizeadulthood.wordpress.com/2009/07/04/c-unit-tests-with-boost-test-part-1/) | ||||
[http://www.alittlemadness.com/2009/03/31/c-unit-testing-with-boosttest/](http://archive.is/dRBGf) | [http://www.alittlemadness.com/2009/03/31/c-unit-testing-with-boosttest/](http://archive.is/dRBGf) | ||||
### Logging and debugging in unit tests | ### Logging and debugging in unit tests | ||||
To write to logs from unit tests you need to use specific message methods | To write to logs from unit tests you need to use specific message methods | ||||
provided by Boost. The simplest is `BOOST_TEST_MESSAGE`. | provided by Boost. The simplest is `BOOST_TEST_MESSAGE`. | ||||
For debugging you can launch the test_bitcoin executable with `gdb`or `lldb` and | For debugging you can launch the test_ecash executable with `gdb`or `lldb` and | ||||
start debugging, just like you would with bitcoind. | start debugging, just like you would with ecashd. | ||||
This is a simple example of debugging unit tests with GDB on Linux: | This is a simple example of debugging unit tests with GDB on Linux: | ||||
``` | ``` | ||||
cd /build/src/test | cd /build/src/test | ||||
gdb test_bitcoin | gdb test_ecash | ||||
break interpreter.cpp:295 # No path is necessary, just the file name and line number | break interpreter.cpp:295 # No path is necessary, just the file name and line number | ||||
run | run | ||||
# GDB hits the breakpoint | # GDB hits the breakpoint | ||||
p/x opcode # print the value of the variable (in this case, opcode) in hex | p/x opcode # print the value of the variable (in this case, opcode) in hex | ||||
c # continue | c # continue | ||||
``` | ``` | ||||
This is a simple example of debugging unit tests with LLDB (OSX or Linux): | This is a simple example of debugging unit tests with LLDB (OSX or Linux): | ||||
``` | ``` | ||||
cd /build/src/test | cd /build/src/test | ||||
lldb -- test_bitcoin | lldb -- test_ecash | ||||
break set --file interpreter.cpp --line 295 | break set --file interpreter.cpp --line 295 | ||||
run | run | ||||
``` | ``` |