Prabhat Verma
Prabhat Verma Summer of Bitcoin Batch of 2024, worked on Bitcoin-Core

Beginner's Guide to Testing Bitcoin Core

With this article , I will be sharing how you can start testing in Bitcoin Core, specifically Unit testing and Functional testing.

Setup

To start with Bitcoin core you should have a local copy of Bitcoin-core on your machine. I have a Linux machine so I will be sharing the steps for that , for other machines you can look here

To start with Bitcoin Core, you should have a local copy on your machine. Here are the steps for a Linux machine:

Even before starting this you need to have some dependencies installed in your machine . For that you can use the following commands in your terminal.

1
sudo apt-get install build-essential libtool autotools-dev automake pkg-config bsdmainutils python3

Fork the Bitcoin Core repository on GitHub.

  1. Clone the repository to your local machine:

    1
    
    git clone git@github.com:YOURGITHUB/bitcoin.git
    
  2. Navigate to the cloned directory and build Bitcoin Core:

    1
    2
    3
    4
    5
    6
    
    cd bitcoin
    git checkout 27.x
    ./autogen.sh
    ./configure --disable-bench --disable-fuzz-binary --enable-debug --without-gui --enable-suppress-external-warnings
    make -j 8
    make install 
    

    If there were no errors with the build process then you have built the repo successfully.

Units tests vs Functional Tests

Both types of tests are crucial for Bitcoin Core. Unit tests ensure that the written code functions correctly and works as expected. Functional tests check if different layers or sets of code can work together and operate smoothly. Bitcoin core uses python for the functional tests and C++ tests using libboost for writing unit tests.

Running functional tests in bitcoin-core

For this step you need to have python 3.9 or above installed in your machine .

To run the bitcoin-core functional tests , from the bitcoin directory write this command.

1
test/functional/test_runner.py

To run extra tests you have to pass the –extended flag while running this command.

1
test/functional/test_runner.py --extended

You should get a similar response for the terminal .(some of the tests can be skipped because of various reasons. As long as there is no test failing , you should be good)

Running Unit tests in Bitcoin core

Unit tests are written using the Boost libraries , make sure you have their latest version installed on your machine .

For running unit tests you can just run

1
make check -j 8

Running Unit tests in Bitcoin core with debuggers

Both lldb and gdb are supported to be used as debuggers in Bitcoin core , For the purpose of this article , I will be using gdb.

For using gdb , it is essential that you build bitcoin-core without optimisations because some variables might have been optimised out and lead to not so informatory results.

1
2
3
4
cd bitcoin
make clean
./configure --disable-wallet --disable-fuzz -disable-fuzz-binary --enable-debug --with-gui=no CXXFLAGS="-O0 -ggdb3"
make -j 8

Now to use gdb , from bitcoin directory run the following command on your terminal

1
gdb src/test/test_bitcoin

After that , you can run test in from any test files. for eg. I want to run the ShouldFanoutToTest in txreconciliation_tests.cpp. In gdb , type this in your terminal

1
run --run_test=txreconciliation_tests/ShouldFanoutToTest

You should get a similar response on your screen.

This is it . Now you know everything to running unit and functional tests in Bitcoin-core.

```