READ THE CODE

Inside Bitcoin

The code behind the network, with room to understand it.

Stable release v32.1bitcoin/bitcoin · f0de87f04062 ↗3,020 source files · 47.5 MB stored on the server440 file guides

Release published 2026-10-28 · Snapshot fetched 2026-11-01. Latest stable release at fetch time; development branches and Git history are excluded. Only the selected code window and visible folders load here.

8,356 bytes · SHA-256 0c3b00778ee9c5d4… · View upstream ↗

1# Functional tests
2
3### Writing Functional Tests
4
5#### Example test
6
7The file [test/functional/example_test.py](example_test.py) is a heavily commented example
8of a test case that uses both the RPC and P2P interfaces. If you are writing your first test, copy
9that file and modify to fit your needs.
10
11#### Coverage
12
13Assuming the build directory is `build`,
14running `build/test/functional/test_runner.py` with the `--coverage` argument tracks which RPCs are
15called by the tests and prints a report of uncovered RPCs in the summary. This
16can be used (along with the `--extended` argument) to find out which RPCs we
17don't have test cases for.
18
19#### Style guidelines
20
21- Where possible, try to adhere to [PEP-8 guidelines](https://www.python.org/dev/peps/pep-0008/)
22- Use a python linter like flake8 before submitting PRs to catch common style
23  nits (eg trailing whitespace, unused imports, etc)
24- The oldest supported Python version is specified in [doc/dependencies.md](/doc/dependencies.md).
25  Consider using [pyenv](https://github.com/pyenv/pyenv), which checks [.python-version](/.python-version),
26  to prevent accidentally introducing modern syntax from an unsupported Python version.
27  The CI linter job also checks this, but [possibly not in all cases](https://github.com/bitcoin/bitcoin/pull/14884#discussion_r239585126).
28- See [the python lint script](/test/lint/lint-python.py) that checks for violations that
29  could lead to bugs and issues in the test code.
30- Use [type hints](https://docs.python.org/3/library/typing.html) in your code to improve code readability
31  and to detect possible bugs earlier.
32- Avoid wildcard imports.
33- If more than one name from a module is needed, use lexicographically sorted multi-line imports
34  in order to reduce the possibility of potential merge conflicts.
35- Use a module-level docstring to describe what the test is testing, and how it
36  is testing it.
37- When subclassing the BitcoinTestFramework, place overrides for the
38  `set_test_params()`, `add_options()` and `setup_xxxx()` methods at the top of
39  the subclass, then locally-defined helper methods, then the `run_test()` method.
40- Use `f'{x}'` for string formatting in preference to `'{}'.format(x)` or `'%s' % x`.
41- Use `platform.system()` for detecting the running operating system and `os.name` to
42  check whether it's a POSIX system (see also the `skip_if_platform_not_{linux,posix}`
43  methods in the `BitcoinTestFramework` class, which can be used to skip a whole test
44  depending on the platform).
45
46#### Naming guidelines
47
48- Name the test `<area>_test.py`, where area can be one of the following:
49    - `feature` for tests for full features that aren't wallet/mining/mempool, eg `feature_rbf.py`
50    - `interface` for tests for other interfaces (REST, ZMQ, etc), eg `interface_rest.py`
51    - `mempool` for tests for mempool behaviour, eg `mempool_reorg.py`
52    - `mining` for tests for mining features, eg `mining_prioritisetransaction.py`
53    - `p2p` for tests that explicitly test the p2p interface, eg `p2p_disconnect_ban.py`
54    - `rpc` for tests for individual RPC methods or features, eg `rpc_listtransactions.py`
55    - `tool` for tests for tools, eg `tool_wallet.py`
56    - `wallet` for tests for wallet features, eg `wallet_keypool.py`
57- Use an underscore to separate words
58    - exception: for tests for specific RPCs or command line options which don't include underscores, name the test after the exact RPC or argument name, eg `rpc_decodescript.py`, not `rpc_decode_script.py`
59- Don't use the redundant word `test` in the name, eg `interface_zmq.py`, not `interface_zmq_test.py`
60
61#### General test-writing advice
62
63- Instead of inline comments or no test documentation at all, log the comments to the test log, e.g.
64  `self.log.info('Create enough transactions to fill a block')`. Logs make the test code easier to read and the test
65  logic easier [to debug](/test/README.md#test-logging).
66- Set `self.num_nodes` to the minimum number of nodes necessary for the test.
67  Having additional unrequired nodes adds to the execution time of the test as
68  well as memory/CPU/disk requirements (which is important when running tests in
69  parallel).
70- Avoid stop-starting the nodes multiple times during the test if possible. A
71  stop-start takes several seconds, so doing it several times blows up the
72  runtime of the test.
73- Set the `self.setup_clean_chain` variable in `set_test_params()` to `True` to
74  initialize an empty blockchain and start from the Genesis block, rather than
75  load a premined blockchain from cache with the default value of `False`. The
76  cached data directories contain a 200-block pre-mined blockchain with the
77  spendable mining rewards being split between four nodes. Each node has 25
78  mature block subsidies (25x50=1250 BTC) in its wallet. Using them is much more
79  efficient than mining blocks in your test.
80- When calling RPCs with lots of arguments, consider using named keyword
81  arguments instead of positional arguments to make the intent of the call
82  clear to readers.
83- Many of the core test framework classes such as `CBlock` and `CTransaction`
84  don't allow new attributes to be added to their objects at runtime like
85  typical Python objects allow. This helps prevent unpredictable side effects
86  from typographical errors or usage of the objects outside of their intended
87  purpose.
88
89#### RPC and P2P definitions
90
91Test writers may find it helpful to refer to the definitions for the RPC and
92P2P messages. These can be found in the following source files:
93
94- `/src/rpc/*` for RPCs
95- `/src/wallet/rpc*` for wallet RPCs
96- `ProcessMessage()` in `/src/net_processing.cpp` for parsing P2P messages
97
98#### Using the P2P interface
99
100- `P2P`s can be used to test specific P2P protocol behavior.
101[p2p.py](test_framework/p2p.py) contains test framework p2p objects and
102[messages.py](test_framework/messages.py) contains all the definitions for objects passed
103over the network (`CBlock`, `CTransaction`, etc, along with the network-level
104wrappers for them, `msg_block`, `msg_tx`, etc).
105
106- P2P tests have two threads. One thread handles all network communication
107with the bitcoind(s) being tested in a callback-based event loop; the other
108implements the test logic.
109
110- `P2PConnection` is the class used to connect to a bitcoind.  `P2PInterface`
111contains the higher level logic for processing P2P payloads and connecting to
112the Bitcoin Core node application logic. For custom behaviour, subclass the
113P2PInterface object and override the callback methods.
114
115`P2PConnection`s can be used as such:
116
117```python
118p2p_conn = node.add_p2p_connection(P2PInterface())
119p2p_conn.send_and_ping(msg)
120```
121
122They can also be referenced by indexing into a `TestNode`'s `p2ps` list, which
123contains the list of test framework `p2p` objects connected to itself
124(it does not include any `TestNode`s):
125
126```python
127node.p2ps[0].sync_with_ping()
128```
129
130More examples can be found in [p2p_unrequested_blocks.py](p2p_unrequested_blocks.py),
131[p2p_compactblocks.py](p2p_compactblocks.py).
132
133#### Prototyping tests
134
135The [`TestShell`](test-shell.md) class exposes the BitcoinTestFramework
136functionality to interactive Python3 environments and can be used to prototype
137tests. This may be especially useful in a REPL environment with session logging
138utilities, such as
139[IPython](https://ipython.readthedocs.io/en/stable/interactive/reference.html#session-logging-and-restoring).
140The logs of such interactive sessions can later be adapted into permanent test
141cases.
142
143### Test framework modules
144The following are useful modules for test developers. They are located in
145[test/functional/test_framework/](test_framework).
146
147#### [authproxy.py](test_framework/authproxy.py)
148Taken from the [python-bitcoinrpc repository](https://github.com/jgarzik/python-bitcoinrpc).
149
150#### [test_framework.py](test_framework/test_framework.py)
151Base class for functional tests.
152
153#### [util.py](test_framework/util.py)
154Generally useful functions.
155
156#### [p2p.py](test_framework/p2p.py)
157Test objects for interacting with a bitcoind node over the p2p interface.
158
159#### [script.py](test_framework/script.py)
160Utilities for manipulating transaction scripts (originally from python-bitcoinlib)
161
162#### [key.py](test_framework/key.py)
163Test-only secp256k1 elliptic curve implementation
164
165#### [blocktools.py](test_framework/blocktools.py)
166Helper functions for creating blocks and transactions.
167

src/wallet/receive.cpp

src/wallet/coinselection.cpp

src/consensus/validation.h

src/primitives/transaction.cpp

src/script/descriptor.cpp

src/bitcoin-cli.cpp

src/rpc/blockchain.cpp

src/rpc/rawtransaction.cpp

src/init.cpp

src/crypto/sha256.cpp

src/consensus/merkle.h

src/consensus/tx_check.h

src/consensus/tx_verify.h

src/policy/feerate.h

src/policy/feerate.cpp

src/primitives/transaction_identifier.h

src/chainparamsbase.h

src/chainparamsbase.cpp

src/util/moneystr.cpp

src/crypto/ripemd160.h

src/crypto/sha1.h

src/crypto/sha512.h

src/crypto/hmac_sha256.h

src/crypto/hmac_sha512.h

src/crypto/hmac_sha256.cpp

src/crypto/hmac_sha512.cpp

src/crypto/hkdf_sha256_32.h

src/crypto/hkdf_sha256_32.cpp

src/support/cleanse.h

src/support/cleanse.cpp

src/crypto/siphash.cpp

src/crypto/muhash.h

src/crypto/chacha20.h

src/crypto/poly1305.h

src/crypto/chacha20poly1305.h

src/crypto/chacha20poly1305.cpp

src/util/chaintype.cpp

src/util/obfuscation.h

src/util/byte_units.h

src/util/overflow.h

src/blockencodings.cpp

src/net_permissions.cpp

src/policy/packages.cpp

src/policy/rbf.cpp

src/policy/truc_policy.cpp

src/policy/ephemeral_policy.cpp

src/policy/settings.cpp

src/policy/policy.cpp

src/node/transaction.cpp

src/node/coin.cpp

src/rpc/client.cpp

src/rpc/external_signer.cpp

src/rpc/request.cpp

src/rpc/server_util.cpp

src/rpc/fees.cpp

src/rpc/output_script.cpp

src/rpc/rawtransaction_util.cpp

src/rpc/rawtransaction_util.h

src/rpc/register.h

src/rpc/request.h

src/rpc/server_util.h

src/rpc/protocol.h

src/rpc/server.h

src/rpc/signmessage.cpp

src/rpc/txoutproof.cpp

src/rpc/util.cpp

src/rpc/util.h

src/wallet/rpc/addresses.cpp

src/wallet/rpc/backup.cpp

src/wallet/rpc/coins.cpp

src/wallet/rpc/encrypt.cpp

src/wallet/rpc/signmessage.cpp

src/wallet/rpc/util.cpp

src/wallet/rpc/util.h

src/wallet/coincontrol.cpp

src/wallet/coincontrol.h

src/wallet/context.cpp

src/wallet/context.h

src/wallet/crypter.cpp

src/wallet/crypter.h

src/wallet/db.cpp

src/wallet/export.cpp

src/wallet/external_signer_scriptpubkeyman.cpp

src/wallet/rpc/spend.cpp

src/wallet/rpc/transactions.cpp

src/wallet/rpc/wallet.cpp

src/wallet/feebumper.cpp

src/wallet/feebumper.h

src/index/base.h

src/index/base.cpp

src/index/txindex.h

src/index/txindex.cpp

src/index/txindex_key.h

src/index/txospenderindex.h

src/index/txospenderindex.cpp

src/index/blockfilterindex.h

src/index/blockfilterindex.cpp

src/index/coinstatsindex.h

src/index/coinstatsindex.cpp

src/index/db_key.h

src/index/disktxpos.h

src/kernel/chain.cpp

src/kernel/chain.h

src/kernel/checks.cpp

src/kernel/checks.h

src/kernel/context.cpp

src/kernel/context.h

src/kernel/cs_main.cpp

src/kernel/cs_main.h

src/kernel/disconnected_transactions.cpp

src/kernel/disconnected_transactions.h

src/kernel/mempool_removal_reason.cpp

src/kernel/mempool_removal_reason.h

src/kernel/coinstats.cpp

src/kernel/coinstats.h

src/kernel/chainparams.cpp

src/kernel/chainparams.h

src/wallet/sqlite.cpp

src/wallet/sqlite.h

src/wallet/transaction.cpp

src/wallet/transaction.h

src/wallet/dump.cpp

src/wallet/dump.h

src/wallet/init.cpp

src/wallet/walletutil.cpp

src/wallet/walletutil.h

src/wallet/wallettool.cpp

src/wallet/wallettool.h

src/wallet/export.h

src/wallet/migrate.cpp

src/wallet/migrate.h

src/wallet/db.h

src/wallet/walletdb.cpp

src/wallet/interfaces.cpp

src/wallet/scriptpubkeyman.cpp

src/wallet/scriptpubkeyman.h

src/kernel/bitcoinkernel.cpp

src/kernel/bitcoinkernel.h

src/kernel/bitcoinkernel_wrapper.h

src/node/chainstate.cpp

src/node/chainstate.h

src/node/blockstorage.cpp

src/node/blockstorage.h

src/node/mempool_persist.cpp

src/node/mempool_persist.h

src/node/utxo_snapshot.cpp

src/node/utxo_snapshot.h

src/node/kernel_notifications.cpp

src/node/kernel_notifications.h

src/node/blockmanager_args.cpp

src/kernel/blockmanager_opts.h

src/util/expected.cpp

src/policy/settings.h

src/util/types.h

src/kernel/messagestartchars.h

src/kernel/warning.h

src/util/exception.h

src/common/license_info.h

src/node/coins_view_args.h

src/node/database_args.h

src/util/batchpriority.h

src/util/ui_change_type.h

src/node/coins_view_args.cpp

src/node/peerman_args.h

src/util/serfloat.h

src/node/blockmanager_args.h

src/node/database_args.cpp

src/util/overloaded.h

src/interfaces/types.h

src/node/chainstatemanager_args.h

src/node/minisketchwrapper.h

src/util/macros.h

src/util/syserror.h

src/common/run_command.h

src/util/bytevectorhash.cpp

src/node/mempool_persist_args.cpp

src/util/exec.h

src/util/rbf.h

src/crypto/hex_base.h

src/node/mempool_persist_args.h

src/interfaces/echo.h

src/util/any.h

src/util/batchpriority.cpp

src/util/threadnames.h

src/node/coin.h

src/node/mempool_args.h

src/util/asmap.h

src/util/bytevectorhash.h

src/node/context.cpp

src/util/insert.h

src/util/readwritefile.h

src/node/peerman_args.cpp

src/node/interface_ui.cpp

src/interfaces/handler.h

src/node/mining_args.h

src/util/hasher.cpp

src/common/init.h

src/kernel/mempool_limits.h

src/common/system.h

src/crypto/sha3.h

src/util/threadinterrupt.cpp

src/node/protocol_version.h

src/util/exception.cpp

src/common/messages.h

src/node/connection_types.cpp

src/util/bip32.h

src/common/license_info.cpp

src/util/stdmutex.h

src/common/run_command.cpp

src/util/check.cpp

src/util/golombrice.h

src/node/types.h

src/node/timeoffsets.h

src/util/readwritefile.cpp

src/util/fastrange.h

src/util/signalinterrupt.h

src/util/task_runner.h

src/util/syserror.cpp

src/common/interfaces.cpp

src/common/types.h

src/util/threadinterrupt.h

src/kernel/chainstatemanager_opts.h

src/node/psbt.h

src/policy/ephemeral_policy.h

src/util/trace.h

src/common/url.cpp

src/kernel/mempool_options.h

src/util/serfloat.cpp

src/kernel/notifications_interface.h

src/node/timeoffsets.cpp

src/node/warnings.cpp

src/util/hash_type.h

src/crypto/hex_base.cpp

src/node/eviction.h

src/util/tokenbucket.h

src/crypto/aes.h

src/common/pcp.h

src/util/feefrac.cpp

src/node/transaction.h

src/util/threadnames.cpp

src/common/signmessage.h

src/util/exec.cpp

src/util/signalinterrupt.cpp

src/clientversion.cpp

src/common/signmessage.cpp

src/compat/assumptions.h

src/compat/byteswap.h

src/deploymentinfo.cpp

src/deploymentinfo.h

src/deploymentstatus.cpp

src/deploymentstatus.h

src/dummywallet.cpp

src/external_signer.h

src/init/bitcoin-gui.cpp

src/init/bitcoin-node.cpp

src/init/bitcoin-qt.cpp

src/init/bitcoin-wallet.cpp

src/init/bitcoind.cpp

src/init/common.h

src/interfaces/init.h

src/interfaces/ipc.h

src/key_io.h

src/logging/categories.h

src/logging/timer.h

src/mapport.h

src/musig.h

src/net_permissions.h

src/netgroup.h

src/netmessagemaker.h

src/node/chainstatemanager_args.cpp

src/node/connection_types.h

src/node/context.h

src/node/interface_ui.h

src/node/mempool_args.cpp

src/node/mining_args.cpp

src/node/minisketchwrapper.cpp

src/node/txreconciliation.h

src/policy/fees/estimator_args.cpp

src/policy/fees/estimator_args.h

src/policy/fees/estimator_man.cpp

src/policy/fees/estimator_man.h

src/policy/packages.h

src/policy/rbf.h

src/policy/truc_policy.h

src/pow.h

src/primitives/block.cpp

src/randomenv.h

src/rest.h

src/script/keyorigin.h

src/script/parsing.cpp

src/script/parsing.h

src/script/script_error.h

src/script/sigcache.cpp

src/script/sigcache.h

src/script/solver.h

src/script/verify_flags.h

src/semaphore_grant.h

src/signet.h

src/span.h

src/support/allocators/secure.h

src/support/allocators/zeroafterfree.h

src/util/tokenpipe.cpp

src/util/translation.h

src/util/vector.h

src/versionbits.h

src/versionbits_impl.h

src/wallet/external_signer_scriptpubkeyman.h

src/wallet/fees.h

src/wallet/load.h

src/wallet/receive.h

src/wallet/rpc/wallet.h

src/wallet/types.h

src/walletinitinterface.h

src/zmq/zmqabstractnotifier.cpp

Independent explanations by MyBitcoinExplorer. Not affiliated with or endorsed by Bitcoin Core. Guides are educational and do not replace the source or its tests.

Bitcoin Core source © its contributors, distributed under the MIT license. Original notices and bundled third-party licenses are retained in the source tree.