How do I get started debugging Bitcoin Core functional tests?

Question

I would like to get started with debugging Bitcoin Core code. I have heard debugging Bitcoin Core functional tests is a good place to start as they are in Python rather than C++ and they are easier to understand. Any recommendations or good resources to help me do this?

Answer 1

To understand the functional tests, I think it's important to start with an understanding of how bitcoind works and how the RPC interface is used.

Start Bitcoin Core in a terminal window in regtest mode (a local test network that does not connect to any peers by default):

$ bitcoind -regtest

Keep an eye on the output! This is your debug log, and important messages are printed there -- many tests even check to make sure a certain message was printed.

In a second window, get a list of commands:

$ bitcoin-cli -regtest help

You can get help for any specific command:

$  bitcoin-cli -regtest help getnewaddress
getnewaddress ( "label" "address_type" )

Returns a new Bitcoin address for receiving payments.
If 'label' is specified, it is added to the address book 
so payments received with the address will be associated with 'label'.

Arguments:
1. label           (string, optional, default="") The label name for the address to be linked to. It can also be set to the empty string "" to represent the default label. The label does not need to exist, it will be created if there is no label by the given name.
2. address_type    (string, optional, default=set by -addresstype) The address type to use. Options are "legacy", "p2sh-segwit", and "bech32".

Result:
"str"    (string) The new bitcoin address

Examples:
> bitcoin-cli getnewaddress 
> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "getnewaddress", "params": []}' -H 'content-type: text/plain;' http://127.0.0.1:8332/

Give it a try!

$ bitcoin-cli -regtest getnewaddress
bcrt1qua6ku8kkx4m57tg6q44wh00h58vpk7lm8h82sy

Now go take a look at a simple test like wallet_resendwallettransactions.py and note the syntax node.getnewaddress() -- by this point you probably know exactly what that does and what the return value will be.

To go deeper and understand how the test framework launches and configures individual nodes, read test_framework.py. You'll notice many of the functional tests pass configuration parameters to the start_nodes() function.

To get a dictionary of those command line parameters, execute:

$ bitcoind -help

These are the key tools I think and the in-program help information is an invaluable resource. By going through functional tests and looking up the rpc commands and launch arguments, you'll eventually get an instinct for how the more complicated tests work.

Answer 2

There are a few different resources I would point you to.

• For more information on functional tests in Bitcoin Core (with guidance on writing them) I would check out the functional tests README.
• For a case study on debugging the functional tests Sjors Provoost wrote a blog post back in 2017. (Some of it may now be outdated but the general thought process is excellent.)
• There are a couple of presentations Fabian Jahr did at Bitcoin Edge Dev++ on the functional test framework and debugging.
• Fabian held a workshop at Advancing Bitcoin on Debugging Bitcoin Core
• Fabian has also been drafting a debugging doc which contains guidance on debugging both unit and functional tests. It is targeted to MacOS users currently so may not be as helpful if you are on Linux or Windows.
• Finally Gloria Zhao has been drafting a doc with more information on the functional test framework.

That should be enough to get you started! Any questions feel welcome to post them on the #bitcoin-core-pr-reviews channel on IRC.