Inside Bitcoin
Opening the selected file…
Inside Bitcoin
Opening the selected file…
The code behind the network, with room to understand it.
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.
1This directory contains integration tests that test bitcoind and its2utilities in their entirety. It does not contain unit tests, which3can be found in [/src/test](/src/test), [/src/wallet/test](/src/wallet/test),4etc.6This directory contains the following sets of tests:8- [fuzz](/test/fuzz) A runner to execute all fuzz targets from9[/src/test/fuzz](/src/test/fuzz).10- [functional](/test/functional) which test the functionality of11bitcoind and bitcoin-qt by interacting with them through the RPC and P2P12interfaces.13- [lint](/test/lint/) which perform various static analysis checks.15The fuzz tests, functional16tests and lint scripts can be run as explained in the sections below.18# Running tests locally20Before tests can be run locally, Bitcoin Core must be built. See the [building instructions](/doc#building) for help.22The following examples assume that the build directory is named `build`.24## Fuzz tests26See [/doc/fuzzing.md](/doc/fuzzing.md)28### Functional tests30#### Dependencies and prerequisites32The ZMQ functional test requires a python ZMQ library. To install it:34- on Unix, run `sudo apt-get install python3-zmq`35- on mac OS, run `pip3 install pyzmq`37The IPC functional test requires a python IPC library. `pip3 install pycapnp` may work, but if not, install it from source:39```sh40git clone -b v2.2.1 https://github.com/capnproto/pycapnp41pip3 install ./pycapnp42```44If that does not work, try adding `-C force-bundled-libcapnp=True` to the `pip` command.45Depending on the system, it may be necessary to install and run in a venv:47```sh48python -m venv venv49git clone -b v2.2.1 https://github.com/capnproto/pycapnp50venv/bin/pip3 install ./pycapnp -C force-bundled-libcapnp=True51venv/bin/python3 build/test/functional/interface_ipc.py52```54The functional tests assume Python UTF-8 Mode, which is the default on most55systems.56On Windows the `PYTHONUTF8` environment variable must be set to 1:58```cmd59set PYTHONUTF8=160```62#### Running the tests64Individual tests can be run by directly calling the test script, e.g.:66```67build/test/functional/feature_rbf.py68```70or can be run through the test_runner harness, eg:72```73build/test/functional/test_runner.py feature_rbf.py74```76You can run any combination (incl. duplicates) of tests by calling:78```79build/test/functional/test_runner.py <testname1> <testname2> <testname3> ...80```82Wildcard test names can be passed, if the paths are coherent and the test runner83is called from a `bash` shell or similar that does the globbing. For example,84to run all the wallet tests:86```87build/test/functional/test_runner.py test/functional/wallet*88functional/test_runner.py functional/wallet* # (called from the build/test/ directory)89test_runner.py wallet* # (called from the build/test/functional/ directory)90```92but not94```95build/test/functional/test_runner.py wallet*96```98Combinations of wildcards can be passed:100```101build/test/functional/test_runner.py ./test/functional/tool* test/functional/mempool*102test_runner.py tool* mempool*103```105Run the regression test suite with:107```108build/test/functional/test_runner.py109```111Run all possible tests with113```114build/test/functional/test_runner.py --extended115```117In order to run backwards compatibility tests, first run:119```120test/get_previous_releases.py121```123to download the necessary previous release binaries.125By default, up to 4 tests will be run in parallel by test_runner. To specify126how many jobs to run, append `--jobs=n`128The individual tests and the test_runner harness have many command-line129options. Run `build/test/functional/test_runner.py -h` to see them all.131#### Speed up test runs with a RAM disk133If you have available RAM on your system you can create a RAM disk to use as the `cache` and `tmp` directories for the functional tests in order to speed them up.134Speed-up amount varies on each system (and according to your RAM speed and other variables), but a 2-3x speed-up is not uncommon.136**Linux**138To create a 4 GiB RAM disk at `/mnt/tmp/`:140```bash141sudo mkdir -p /mnt/tmp142sudo mount -t tmpfs -o size=4g tmpfs /mnt/tmp/143```145Configure the size of the RAM disk using the `size=` option.146The size of the RAM disk needed is relative to the number of concurrent jobs the test suite runs.147For example running the test suite with `--jobs=100` might need a 4 GiB RAM disk, but running with `--jobs=32` will only need a 2.5 GiB RAM disk.149To use, run the test suite specifying the RAM disk as the `cachedir` and `tmpdir`:151```bash152build/test/functional/test_runner.py --cachedir=/mnt/tmp/cache --tmpdir=/mnt/tmp153```155Once finished with the tests and the disk, and to free the RAM, simply unmount the disk:157```bash158sudo umount /mnt/tmp159```161**macOS**163To create a 4 GiB RAM disk named "ramdisk" at `/Volumes/ramdisk/`:165```bash166diskutil erasevolume HFS+ ramdisk $(hdiutil attach -nomount ram://8388608)167```169Configure the RAM disk size, expressed as the number of blocks, at the end of the command170(`4096 MiB * 2048 blocks/MiB = 8388608 blocks` for 4 GiB). To run the tests using the RAM disk:172```bash173build/test/functional/test_runner.py --cachedir=/Volumes/ramdisk/cache --tmpdir=/Volumes/ramdisk/tmp174```176To unmount:178```bash179umount /Volumes/ramdisk180```182#### Troubleshooting and debugging test failures184##### Resource contention186The P2P and RPC ports used by the bitcoind nodes-under-test are chosen to make187conflicts with other processes unlikely. However, if there is another bitcoind188process running on the system (perhaps from a previous test which hasn't successfully189killed all its bitcoind nodes), then there may be a port conflict which will190cause the test to fail. It is recommended that you run the tests on a system191where no other bitcoind processes are running.193On linux, the test framework will warn if there is another194bitcoind process running when the tests are started.196If there are zombie bitcoind processes after test failure, you can kill them197by running the following commands. **Note that these commands will kill all198bitcoind processes running on the system, so should not be used if any non-test199bitcoind processes are being run.**201```bash202killall bitcoind203```205or207```bash208pkill -9 bitcoind209```212##### Data directory cache214A pre-mined blockchain with 200 blocks is generated the first time a215functional test is run and is stored in build/test/cache. This speeds up216test startup times since new blockchains don't need to be generated for217each test. However, the cache may get into a bad state, in which case218tests will fail. If this happens, remove the cache directory (and make219sure bitcoind processes are stopped as above):221```bash222rm -rf build/test/cache223killall bitcoind224```226##### Test logging228The tests contain logging at five different levels (DEBUG, INFO, WARNING, ERROR229and CRITICAL). From within your functional tests you can log to these different230levels using the logger included in the test_framework, e.g.231`self.log.debug(object)`. By default:233- when run through the test_runner harness, *all* logs are written to234`test_framework.log` and no logs are output to the console.235- when run directly, *all* logs are written to `test_framework.log` and INFO236level and above are output to the console.237- when run by [our CI (Continuous Integration)](/ci/README.md), no logs are output to the console. However, if a test238fails, the `test_framework.log` and bitcoind `debug.log`s will all be dumped239to the console to help troubleshooting.241These log files can be located under the test data directory (which is always242printed in the first line of test output):243- `<test data directory>/test_framework.log`244- `<test data directory>/node<node number>/regtest/debug.log`.246The node number identifies the relevant test node, starting from `node0`, which247corresponds to its position in the nodes list of the specific test,248e.g. `self.nodes[0]`.250To change the level of logs output to the console, use the `-l` command line
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.