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.

9,694 bytes · SHA-256 2917a04d7817b8b3… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2025-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"""
6Verify framework startup failures only raise one exception since
7multiple exceptions being raised muddies the waters of what actually
8went wrong. We should maintain this bar of only raising one exception as
9long as additional maintenance and complexity is low.
10
11Test relaunches itself into child processes in order to trigger failures
12without the parent process' BitcoinTestFramework also failing.
13"""
14
15from test_framework.util import (
16    assert_raises_message,
17    rpc_port,
18)
19from test_framework.test_framework import BitcoinTestFramework
20
21from hashlib import md5
22from os import linesep
23import re
24import subprocess
25import sys
26import time
27
28class FeatureFrameworkStartupFailures(BitcoinTestFramework):
29    def set_test_params(self):
30        self.num_nodes = 1
31
32    def setup_network(self):
33        # Don't start the node yet, as we want to measure during run_test.
34        self.add_nodes(self.num_nodes, self.extra_args)
35
36    # Launches a child test process that runs this same file, but instantiates
37    # a child test. Verifies that it raises only the expected exception, once.
38    def _verify_startup_failure(self, test, internal_args, expected_exception):
39        name = test.__name__
40        def format_child_output(output):
41            return f"\n<{name} OUTPUT BEGIN>\n{output.strip()}\n<{name} OUTPUT END>\n"
42
43        # Inherit sys.argv from parent, only overriding tmpdir to a subdirectory
44        # so children don't fail due to colliding with the parent dir.
45        assert self.options.tmpdir, "Framework should always set tmpdir."
46        subdir = md5(expected_exception.encode('utf-8')).hexdigest()[:8]
47        args = [sys.executable] + sys.argv + [f"--tmpdir={self.options.tmpdir}/{subdir}", f"--internal_test={name}"] + internal_args
48
49        try:
50            output = subprocess.run(args, timeout=60 * self.options.timeout_factor,
51                                    stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True).stdout
52        except subprocess.TimeoutExpired as e:
53            sys.exit("Unexpected child process timeout!\n"
54                     "WARNING: Timeouts like this halt execution of TestNode logic, "
55                     "meaning dangling bitcoind processes are to be expected.\n" +
56                     (format_child_output(e.output.decode("utf-8")) if e.output else "<EMPTY OUTPUT>"))
57
58        errors = []
59        if (n := output.count("Traceback")) != 1:
60            errors.append(f"Found {n}/1 tracebacks - expecting exactly one with no knock-on exceptions.")
61        if (n := len(re.findall(expected_exception, output))) != 1:
62            errors.append(f"Found {n}/1 occurrences of the specific exception: {expected_exception}")
63        if (n := output.count("Test failed. Test logging available at")) != 1:
64            errors.append(f"Found {n}/1 test failure output messages.")
65
66        assert not errors, (f"Child test did NOT contain (only) expected errors:\n{linesep.join(errors)}\n" +
67                            format_child_output(output))
68
69        self.log.debug("Child test did contain (only) expected errors:\n" +
70                       format_child_output(output))
71
72    def run_test(self):
73        self.log.info("Verifying _verify_startup_failure() functionality (self-check).")
74        assert_raises_message(
75            AssertionError,
76            ( "Child test did NOT contain (only) expected errors:\n"
77             f"Found 0/1 tracebacks - expecting exactly one with no knock-on exceptions.{linesep}"
78             f"Found 0/1 occurrences of the specific exception: NonExistentError{linesep}"
79              "Found 0/1 test failure output messages."),
80            self._verify_startup_failure,
81            TestSuccess, [],
82            "NonExistentError",
83        )
84
85        self.log.info("Parent process is measuring node startup duration in order to obtain a reasonable timeout value for later tests...")
86        node_start_time = time.time()
87        self.nodes[0].start()
88        self.nodes[0].wait_for_rpc_connection()
89        node_start_duration = time.time() - node_start_time
90        self.nodes[0].stop_node()
91        self.log.info(f"...measured {node_start_duration:.1f}s.")
92
93        self.log.info("Verifying inability to connect to bitcoind's RPC interface due to wrong port results in one exception containing at least one OSError.")
94        self._verify_startup_failure(
95            TestWrongRpcPortStartupFailure, [f"--internal_node_start_duration={node_start_duration}"],
96            r"AssertionError: \[node 0\] Unable to connect to bitcoind after \d+s \(ignored errors: {[^}]*'OSError \w+'?: \d+[^}]*}, latest: '[\w ]+'/\w+\([^)]+\)\)"
97        )
98
99        self.log.info("Verifying timeout while waiting for init errors that do not occur results in only one exception.")
100        self._verify_startup_failure(
101            TestMissingInitErrorTimeout, [f"--internal_node_start_duration={node_start_duration}"],
102            r"AssertionError: \[node 0\] bitcoind should have exited within \d+s with an error \(cmd:"
103        )
104
105        self.log.info("Verifying startup failure due to invalid arg results in only one exception.")
106        self._verify_startup_failure(
107            TestInitErrorStartupFailure, [],
108            r"FailedToStartError: \[node 0\] bitcoind exited with status 1 during initialization\. Error: Error parsing command line arguments: Invalid parameter -nonexistentarg"
109        )
110
111        self.log.info("Verifying start() then stop_node() on a node without wait_for_rpc_connection() in between raises an assert.")
112        self._verify_startup_failure(
113            TestStartStopStartupFailure, [],
114            r"AssertionError: \[node 0\] Should only call stop_node\(\) on a running node after wait_for_rpc_connection\(\) succeeded\. Did you forget to call the latter after start\(\)\? Not connected to process: \d+"
115        )
116
117class InternalTestMixin:
118    def add_options(self, parser):
119        # Just here to silence unrecognized argument error, we actually read the value in the if-main at the bottom.
120        parser.add_argument("--internal_test", dest="internal_never_read", help="ONLY TO BE USED WHEN TEST RELAUNCHES ITSELF")
121
122class InternalDurationTestMixin(InternalTestMixin):
123    def add_options(self, parser):
124        # Receives the previously measured duration for node startup + RPC connection establishment.
125        parser.add_argument("--internal_node_start_duration", dest="node_start_duration", help="ONLY TO BE USED WHEN TEST RELAUNCHES ITSELF", type=float)
126        InternalTestMixin.add_options(self, parser)
127
128    def get_reasonable_rpc_timeout(self):
129        # 2 * the measured test startup duration should be enough.
130        # Divide by timeout_factor to counter multiplication in BitcoinTestFramework.
131        return max(3, 2 * self.options.node_start_duration) / self.options.timeout_factor
132
133class TestWrongRpcPortStartupFailure(InternalDurationTestMixin, BitcoinTestFramework):
134    def set_test_params(self):
135        self.num_nodes = 1
136        # Override RPC listen port to something TestNode isn't expecting so that
137        # we are unable to establish an RPC connection.
138        self.extra_args = [[f"-rpcport={rpc_port(2)}"]]
139        # Override the timeout to avoid waiting unnecessarily long to realize
140        # nothing is on that port.
141        self.rpc_timeout = self.get_reasonable_rpc_timeout()
142
143    def run_test(self):
144        assert False, "Should have failed earlier during startup."
145
146class TestMissingInitErrorTimeout(InternalDurationTestMixin, BitcoinTestFramework):
147    def set_test_params(self):
148        self.num_nodes = 1
149        # Override the timeout to avoid waiting unnecessarily long for an init
150        # error which never occurs.
151        self.rpc_timeout = self.get_reasonable_rpc_timeout()
152
153    def setup_network(self):
154        self.add_nodes(self.num_nodes, self.extra_args)
155        self.nodes[0].assert_start_raises_init_error()
156        assert False, "assert_start_raises_init_error() should raise an exception due to timeout since we don't expect an init error."
157
158    def run_test(self):
159        assert False, "Should have failed earlier during startup."
160
161class TestInitErrorStartupFailure(InternalTestMixin, BitcoinTestFramework):
162    def set_test_params(self):
163        self.num_nodes = 1
164        self.extra_args = [["-nonexistentarg"]]
165
166    def run_test(self):
167        assert False, "Should have failed earlier during startup."
168
169class TestStartStopStartupFailure(InternalTestMixin, BitcoinTestFramework):
170    def set_test_params(self):
171        self.num_nodes = 1
172
173    def setup_network(self):
174        self.add_nodes(self.num_nodes, self.extra_args)
175        self.nodes[0].start()
176        self.nodes[0].stop_node()
177        assert False, "stop_node() should raise an exception when we haven't called wait_for_rpc_connection()"
178
179    def run_test(self):
180        assert False, "Should have failed earlier during startup."
181
182class TestSuccess(InternalTestMixin, BitcoinTestFramework):
183    def set_test_params(self):
184        self.num_nodes = 1
185
186    def setup_network(self):
187        pass # Don't need to start our node.
188
189    def run_test(self):
190        pass # Just succeed.
191
192
193if __name__ == '__main__':
194    if class_name := next((m[1] for arg in sys.argv[1:] if (m := re.match(r'--internal_test=(.+)', arg))), None):
195        internal_test = globals().get(class_name)
196        assert internal_test, f"Unrecognized test: {class_name}"
197        internal_test(__file__).main()
198    else:
199        FeatureFrameworkStartupFailures(__file__).main()
200

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.