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.

54,526 bytes · SHA-256 cc5e1f5bf428e3a7… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2014-present The Bitcoin Core developers
3# Distributed under the MIT software license, see the accompanying
4# file COPYING or http://www.opensource.org/licenses/mit-license.php.
5"""Base class for RPC testing."""
6
7import configparser
8from enum import Enum
9import argparse
10from datetime import datetime, timezone
11from importlib.util import find_spec
12import logging
13import os
14from pathlib import Path
15import platform
16import pdb
17import random
18import re
19import shutil
20import subprocess
21import sys
22import tempfile
23import time
24
25from .address import create_deterministic_address_bcrt1_p2tr_op_true
26from . import coverage
27from .messages import CAddress
28from .p2p import NetworkThread
29from .test_node import TestNode
30from .util import (
31    Binaries,
32    MAX_NODES,
33    PortSeed,
34    assert_equal,
35    check_json_precision,
36    export_env_build_path,
37    find_vout_for_address,
38    get_binary_paths,
39    get_datadir_path,
40    initialize_datadir,
41    p2p_port,
42    wait_until_helper_internal,
43    wallet_importprivkey,
44    JSONRPCException,
45)
46
47
48class TestStatus(Enum):
49    PASSED = 1
50    FAILED = 2
51    SKIPPED = 3
52
53TEST_EXIT_PASSED = 0
54TEST_EXIT_FAILED = 1
55TEST_EXIT_SKIPPED = 77
56
57TMPDIR_PREFIX = "bitcoin_func_test_"
58
59
60class SkipTest(Exception):
61    """This exception is raised to skip a test"""
62
63    def __init__(self, message):
64        self.message = message
65
66
67class BitcoinTestMetaClass(type):
68    """Metaclass for BitcoinTestFramework.
69
70    Ensures that any attempt to register a subclass of `BitcoinTestFramework`
71    adheres to a standard whereby the subclass overrides `set_test_params` and
72    `run_test` but DOES NOT override either `__init__` or `main`. If any of
73    those standards are violated, a ``TypeError`` is raised."""
74
75    def __new__(cls, clsname, bases, dct):
76        if not clsname == 'BitcoinTestFramework':
77            if not ('run_test' in dct and 'set_test_params' in dct):
78                raise TypeError("BitcoinTestFramework subclasses must override "
79                                "'run_test' and 'set_test_params'")
80            if '__init__' in dct or 'main' in dct:
81                raise TypeError("BitcoinTestFramework subclasses may not override "
82                                "'__init__' or 'main'")
83
84        return super().__new__(cls, clsname, bases, dct)
85
86
87class BitcoinTestFramework(metaclass=BitcoinTestMetaClass):
88    """Base class for a bitcoin test script.
89
90    Individual bitcoin test scripts should subclass this class and override the set_test_params() and run_test() methods.
91
92    Individual tests can also override the following methods to customize the test setup:
93
94    - add_options()
95    - setup_chain()
96    - setup_network()
97    - setup_nodes()
98
99    The __init__() and main() methods should not be overridden.
100
101    This class also contains various public and private helper methods."""
102
103    def __init__(self, test_file) -> None:
104        """Sets test framework defaults. Do not override this method. Instead, override the set_test_params() method"""
105        self.chain: str = 'regtest'
106        self.setup_clean_chain: bool = False
107        self.noban_tx_relay: bool = False
108        self.nodes: list[TestNode] = []
109        self.extra_args = None
110        self.extra_init = None
111        self.network_thread = None
112        self.rpc_timeout = 60  # Wait for up to 60 seconds for the RPC server to respond
113        self.supports_cli = True
114        self.bind_to_localhost_only = True
115        self.parse_args(test_file)
116        self.default_wallet_name = "default_wallet"
117        self.wallet_data_filename = "wallet.dat"
118        # Optional list of wallet names that can be set in set_test_params to
119        # create and import keys to. If unset, default is len(nodes) *
120        # [default_wallet_name]. If wallet names are None, wallet creation is
121        # skipped. If list is truncated, wallet creation is skipped and keys
122        # are not imported.
123        self.wallet_names = None
124        # By default the wallet is not required. Set to true by skip_if_no_wallet().
125        # Can also be set to None to indicate that the wallet will be used if available.
126        # When False or None, we ignore wallet_names in setup_nodes().
127        self.uses_wallet = False
128        # Disable ThreadOpenConnections by default, so that adding entries to
129        # addrman will not result in automatic connections to them.
130        self.disable_autoconnect = True
131        self.set_test_params()
132        assert self.wallet_names is None or len(self.wallet_names) <= self.num_nodes
133        self.rpc_timeout = int(self.rpc_timeout * self.options.timeout_factor) # optionally, increase timeout by a factor
134
135    def main(self):
136        """Main function. This should not be overridden by the subclass test scripts."""
137
138        assert hasattr(self, "num_nodes"), "Test must set self.num_nodes in set_test_params()"
139
140        try:
141            self.setup()
142            if self.options.test_methods:
143                self.run_test_methods()
144            else:
145                self.run_test()
146
147        except SkipTest as e:
148            self.log.warning("Test Skipped: %s" % e.message)
149            self.success = TestStatus.SKIPPED
150        except subprocess.CalledProcessError as e:
151            self.log.exception(f"Called Process failed with stdout='{e.stdout}'; stderr='{e.stderr}';")
152            self.success = TestStatus.FAILED
153        except BaseException:
154            # The `exception` log will add the exception info to the message.
155            # https://docs.python.org/3/library/logging.html#logging.exception
156            self.log.exception("Unexpected exception:")
157            self.success = TestStatus.FAILED
158        finally:
159            exit_code = self.shutdown()
160            sys.exit(exit_code)
161
162    def run_test_methods(self):
163        for method_name in self.options.test_methods:
164            self.log.info(f"Attempting to execute method: {method_name}")
165            method = getattr(self, method_name)
166            method()
167            self.log.info(f"Method '{method_name}' executed successfully.")
168
169    def parse_args(self, test_file):
170        previous_releases_path = os.getenv("PREVIOUS_RELEASES_DIR") or os.getcwd() + "/releases"
171        parser = argparse.ArgumentParser(usage="%(prog)s [options]")
172        parser.add_argument("--nocleanup", dest="nocleanup", default=False, action="store_true",
173                            help="Leave bitcoinds and test.* datadir on exit or error")
174        parser.add_argument("--cachedir", dest="cachedir", default=os.path.abspath(os.path.dirname(test_file) + "/../cache"),
175                            help="Directory for caching pregenerated datadirs (default: %(default)s)")
176        parser.add_argument("--tmpdir", dest="tmpdir", help="Root directory for datadirs (must not exist)")
177        parser.add_argument("-l", "--loglevel", dest="loglevel", default="INFO",
178                            help="log events at this level and higher to the console. Can be set to DEBUG, INFO, WARNING, ERROR or CRITICAL. Passing --loglevel DEBUG will output all logs to console. Note that logs at all levels are always written to the test_framework.log file in the temporary test directory.")
179        parser.add_argument("--tracerpc", dest="trace_rpc", default=False, action="store_true",
180                            help="Print out all RPC calls as they are made")
181        parser.add_argument("--portseed", dest="port_seed", default=os.getpid(), type=int,
182                            help="The seed to use for assigning port numbers (default: current process id)")
183        parser.add_argument("--previous-releases", dest="prev_releases", action="store_true",
184                            default=os.path.isdir(previous_releases_path) and bool(os.listdir(previous_releases_path)),
185                            help="Force test of previous releases (default: %(default)s). Previous releases binaries can be downloaded via `test/get_previous_releases.py`.")
186        parser.add_argument("--coveragedir", dest="coveragedir",
187                            help="Write tested RPC commands into this directory")
188        parser.add_argument("--configfile", dest="configfile",
189                            default=os.path.abspath(os.path.dirname(test_file) + "/../config.ini"),
190                            help="Location of the test framework config file (default: %(default)s)")
191        parser.add_argument("--pdbonfailure", dest="pdbonfailure", default=False, action="store_true",
192                            help="Attach a python debugger if test fails")
193        parser.add_argument("--usecli", dest="usecli", default=False, action="store_true",
194                            help="use bitcoin-cli instead of RPC for all commands")
195        parser.add_argument("--valgrind", dest="valgrind", default=False, action="store_true",
196                            help="Run binaries under the valgrind memory error detector: Expect at least a ~10x slowdown. Does not apply to previous release binaries.")
197        parser.add_argument("--randomseed", type=int,
198                            help="set a random seed for deterministically reproducing a previous test run")
199        parser.add_argument("--timeout-factor", dest="timeout_factor", type=float, help="adjust test timeouts by a factor. Setting it to 0 disables all timeouts")
200        parser.add_argument("--v2transport", dest="v2transport", default=False, action="store_true",
201                            help="use BIP324 v2 connections between all nodes by default")
202        parser.add_argument("--v1transport", dest="v1transport", default=False, action="store_true",
203                            help="Explicitly use v1 transport (can be used to overwrite global --v2transport option)")
204        parser.add_argument("--test_methods", dest="test_methods", nargs='*',
205                            help="Run specified test methods sequentially instead of the full test. Use only for methods that do not depend on any context set up in run_test or other methods.")
206
207        self.add_options(parser)
208        # Running TestShell in a Jupyter notebook causes an additional -f argument
209        # To keep TestShell from failing with an "unrecognized argument" error, we add a dummy "-f" argument
210        # source: https://stackoverflow.com/questions/48796169/how-to-fix-ipykernel-launcher-py-error-unrecognized-arguments-in-jupyter/56349168#56349168
211        parser.add_argument("-f", "--fff", help="a dummy argument to fool ipython", default="1")
212        self.options = parser.parse_args()
213        if self.options.timeout_factor == 0:
214            self.options.timeout_factor = 999
215        self.options.timeout_factor = self.options.timeout_factor or (4 if self.options.valgrind else 1)
216        self.options.previous_releases_path = previous_releases_path
217
218        self.config = configparser.ConfigParser()
219        self.config.read_file(open(self.options.configfile))
220        self.binary_paths = get_binary_paths(self.config)
221        if self.options.v1transport:
222            self.options.v2transport=False
223
224        PortSeed.n = self.options.port_seed
225
226    def get_binaries(self, bin_dir=None):
227        return Binaries(self.binary_paths, bin_dir, use_valgrind=self.options.valgrind)
228
229    def setup(self):
230        """Call this method to start up the test framework object with options set."""
231
232        check_json_precision()
233        export_env_build_path(self.config)
234
235        self.options.cachedir = os.path.abspath(self.options.cachedir)
236
237        # Set up temp directory and start logging
238        if self.options.tmpdir:
239            self.options.tmpdir = os.path.abspath(self.options.tmpdir)
240            os.makedirs(self.options.tmpdir, exist_ok=False)
241        else:
242            self.options.tmpdir = tempfile.mkdtemp(prefix=TMPDIR_PREFIX)
243        self._start_logging()
244
245        # Seed the PRNG. Note that test runs are reproducible if and only if
246        # a single thread accesses the PRNG. For more information, see
247        # https://docs.python.org/3/library/random.html#notes-on-reproducibility.
248        # The network thread shouldn't access random. If we need to change the
249        # network thread to access randomness, it should instantiate its own
250        # random.Random object.

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.