<p>To understand the functional tests, I think it's important to start with an understanding of how <code>bitcoind</code> works and how the RPC interface is used.</p>
<p>Start Bitcoin Core in a terminal window in regtest mode (a local test network that does not connect to any peers by default):</p>
<pre><code>$ bitcoind -regtest
</code></pre>
<p>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.</p>
<p>In a second window, get a list of commands:</p>
<pre><code>$ bitcoin-cli -regtest help
</code></pre>
<p>You can get help for any specific command:</p>
<pre><code>$  bitcoin-cli -regtest help getnewaddress
getnewaddress ( &quot;label&quot; &quot;address_type&quot; )

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=&quot;&quot;) The label name for the address to be linked to. It can also be set to the empty string &quot;&quot; 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 &quot;legacy&quot;, &quot;p2sh-segwit&quot;, and &quot;bech32&quot;.

Result:
&quot;str&quot;    (string) The new bitcoin address

Examples:
&gt; bitcoin-cli getnewaddress 
&gt; curl --user myusername --data-binary '{&quot;jsonrpc&quot;: &quot;1.0&quot;, &quot;id&quot;: &quot;curltest&quot;, &quot;method&quot;: &quot;getnewaddress&quot;, &quot;params&quot;: []}' -H 'content-type: text/plain;' http://127.0.0.1:8332/
</code></pre>
<p>Give it a try!</p>
<pre><code>$ bitcoin-cli -regtest getnewaddress
bcrt1qua6ku8kkx4m57tg6q44wh00h58vpk7lm8h82sy
</code></pre>
<p>Now go take a look at a simple test like <a href="https://github.com/bitcoin/bitcoin/blob/7ff64311bee570874c4f0dfa18f518552188df08/test/functional/wallet_resendwallettransactions.py#L42" rel="nofollow noreferrer">wallet_resendwallettransactions.py</a> and note the syntax <code>node.getnewaddress()</code> -- by this point you probably know exactly what that does and what the return value will be.</p>
<p>To go deeper and understand how the test framework launches and configures individual nodes, read <code>test_framework.py</code>. You'll notice many of the functional tests pass configuration parameters to the <code>start_nodes()</code> function.</p>
<p>To get a dictionary of those command line parameters, execute:</p>
<pre><code>$ bitcoind -help
</code></pre>
<p>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.</p>

CC BY-SA 4.0
2020-09-14T02:04:26.597Z
Either I completely missed it, or this answer does not answer how to _debug_ the tests.
Andrew Savinykh
CC BY-SA 4.0
2020-09-13T14:30:50.210Z
2020-09-13T14:30:50.210Z
pinhead
<p>There are a few different resources I would point you to.</p>
<ul>
<li>For more information on functional tests in Bitcoin Core (with guidance on writing them) I would check out the functional tests <a href="https://github.com/bitcoin/bitcoin/blob/master/test/functional/README.md" rel="nofollow noreferrer">README</a>.</li>
<li>For a case study on debugging the functional tests Sjors Provoost wrote a <a href="https://medium.com/provoost-on-crypto/debugging-bitcoin-core-functional-tests-cc0aa6e7fd3e" rel="nofollow noreferrer">blog post</a> back in 2017. (Some of it may now be outdated but the general thought process is excellent.)</li>
<li>There are a couple of presentations Fabian Jahr did at Bitcoin Edge Dev++ on the <a href="https://diyhpl.us/wiki/transcripts/scalingbitcoin/tel-aviv-2019/edgedevplusplus/bitcoin-core-functional-test-framework/" rel="nofollow noreferrer">functional test framework</a> and <a href="https://diyhpl.us/wiki/transcripts/scalingbitcoin/tel-aviv-2019/edgedevplusplus/debugging-bitcoin/" rel="nofollow noreferrer">debugging</a>.</li>
<li>Fabian held a <a href="https://diyhpl.us/wiki/transcripts/advancing-bitcoin/2020/2020-02-07-fabian-jahr-debugging-workshop/" rel="nofollow noreferrer">workshop</a> at Advancing Bitcoin on Debugging Bitcoin Core</li>
<li>Fabian has also been drafting a debugging <a href="https://github.com/fjahr/debugging_bitcoin" rel="nofollow noreferrer">doc</a> 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.</li>
<li>Finally Gloria Zhao has been drafting a <a href="https://github.com/gzhao408/bitcoin-notes/blob/master/test_framework_intro.md" rel="nofollow noreferrer">doc</a> with more information on the functional test framework.</li>
</ul>
<p>That should be enough to get you started! Any questions feel welcome to post them on the #bitcoin-core-pr-reviews channel on IRC.</p>

CC BY-SA 4.0
2020-09-13T14:13:49.783Z
2020-12-07T15:07:19.280Z
2020-12-07T15:07:19.280Z
Michael Folkson
<p>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?</p>

<bitcoin-core-development><debugging><functional-test>
How do I get started debugging Bitcoin Core functional tests?
Michael Folkson
# How do I get started debugging Bitcoin Core functional tests?

(Asked by: username_0 on 2020-09-13)

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?

**Tags:** bitcoin-core-development, debugging, functional-test


---

## 2 answers

### Answer by username_1 on 2020-09-13. Score: 4

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](https://github.com/bitcoin/bitcoin/blob/7ff64311bee570874c4f0dfa18f518552188df08/test/functional/wallet_resendwallettransactions.py#L42) 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.

> **Comments:**
> **username_2**: Either I completely missed it, or this answer does not answer how to _debug_ the tests.  

---

### Answer by username_0 on 2020-09-13. Score: 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](https://github.com/bitcoin/bitcoin/blob/master/test/functional/README.md).
* For a case study on debugging the functional tests Sjors Provoost wrote a [blog post](https://medium.com/provoost-on-crypto/debugging-bitcoin-core-functional-tests-cc0aa6e7fd3e) 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](https://diyhpl.us/wiki/transcripts/scalingbitcoin/tel-aviv-2019/edgedevplusplus/bitcoin-core-functional-test-framework/) and [debugging](https://diyhpl.us/wiki/transcripts/scalingbitcoin/tel-aviv-2019/edgedevplusplus/debugging-bitcoin/).
* Fabian held a [workshop](https://diyhpl.us/wiki/transcripts/advancing-bitcoin/2020/2020-02-07-fabian-jahr-debugging-workshop/) at Advancing Bitcoin on Debugging Bitcoin Core
* Fabian has also been drafting a debugging [doc](https://github.com/fjahr/debugging_bitcoin) 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](https://github.com/gzhao408/bitcoin-notes/blob/master/test_framework_intro.md) 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.


---

