Merge bitcoin/bitcoin#35395: doc: Improve test suite dependencies documentation
What changed, and why it matters
This commit only updates documentation. It reorganizes instructions for installing Python test-suite dependencies across operating systems and consolidates them into a single README file. No program code was changed, so it cannot directly affect security or introduce vulnerabilities.
No security action needed. Treat as a normal documentation update.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The merge commit updates markdown documentation files (doc/build-*.md and test/README.md) to centralize and clarify instructions for optional Python test dependencies (pyzmq, pycapnp, lsof, UTF-8 mode). It removes duplicated per-OS install commands and replaces them with references to test/README.md. There are no source-code, build-script, or configuration changes.
Changed components
doc/build-freebsd.mddoc/build-netbsd.mddoc/build-openbsd.mddoc/build-osx.mddoc/build-unix.mddoc/build-windows-msvc.mdtest/README.mdInspect captured patch +40 / −67
### doc/build-freebsd.md
@@ -70,13 +70,8 @@ pkg install libzmq4 pkgconf
```
#### Test Suite Dependencies
-There is an included test suite that is useful for testing code changes when developing.
-To run the test suite (recommended), you will need to have Python 3 installed:
-```bash
-pkg install python3 databases/py-sqlite3 net/py-pyzmq lsof
-```
----
+See [`test/README.md`](/test/README.md#dependencies-and-prerequisites).
## Building Bitcoin Core
### doc/build-netbsd.md
@@ -73,19 +73,7 @@ pkgin install zeromq pkgconf
#### Test Suite Dependencies
-There is an included test suite that is useful for testing code changes when developing.
-To run the test suite (recommended), you will need to have Python 3 installed:
-
-```bash
-pkgin install python313 py313-zmq lsof
-```
-
-When the `lsof` binary package was built for a different point release, it might be necessary to force its installation as follows:
-
-```bash
-echo "CHECK_OSABI=no" >> /etc/pkg_install.conf
-pkgin install lsof
-```
+See [`test/README.md`](/test/README.md#dependencies-and-prerequisites).
## Building Bitcoin Core
### doc/build-openbsd.md
@@ -70,12 +70,8 @@ pkg_add zeromq
```
#### Test Suite Dependencies
-There is an included test suite that is useful for testing code changes when developing.
-To run the test suite (recommended), you will need to have Python 3 installed:
-```bash
-pkg_add python py3-zmq # Select the newest version of the python package if necessary.
-```
+See [`test/README.md`](/test/README.md#dependencies-and-prerequisites).
## Building Bitcoin Core
### doc/build-osx.md
@@ -121,12 +121,7 @@ For more information on ZMQ, see: [zmq.md](zmq.md)
#### Test Suite Dependencies
-There is an included test suite that is useful for testing code changes when developing.
-To run the test suite (recommended), you will need to have Python 3 installed:
-
-``` bash
-brew install python
-```
+See [`test/README.md`](/test/README.md#dependencies-and-prerequisites).
---
### doc/build-unix.md
@@ -88,3 +88,7 @@ be compiled in disable-wallet mode with:
In this case there is no dependency on SQLite.
Mining is also possible in disable-wallet mode using the `getblocktemplate` RPC call.
+
+### Test Suite Dependencies
+
+See [`test/README.md`](/test/README.md#dependencies-and-prerequisites).
### doc/build-windows-msvc.md
@@ -32,15 +32,9 @@ This installs:
After installation, the commands in this guide should be executed in "Developer PowerShell for VS" or "Developer Command Prompt for VS".
The former is assumed hereinafter.
-#### Python
+#### Test Suite Dependencies
-Python is required for running the test suite.
-
-To install Python, run:
-
-```powershell
-winget install python3
-```
+See [`test/README.md`](/test/README.md#dependencies-and-prerequisites).
### 2. Clone Bitcoin Repository
### test/README.md
@@ -25,41 +25,42 @@ The following examples assume that the build directory is named `build`.
See [/doc/fuzzing.md](/doc/fuzzing.md)
-### Functional tests
+## Functional tests
-#### Dependencies and prerequisites
+### Dependencies and prerequisites
-The ZMQ functional test requires a python ZMQ library. To install it:
+The functional tests require Python to be installed. For the minimum required Python version, refer to [Dependencies](/doc/dependencies.md#build-1).
-- on Unix, run `sudo apt-get install python3-zmq`
-- on mac OS, run `pip3 install pyzmq`
+Some tests require optional dependencies: Python modules and system utilities.
+They can be installed with any suitable tool, like the system package manager, `pip` in a virtual environment, or `uv`.
-The IPC functional test requires a python IPC library. `pip3 install pycapnp` may work, but if not, install it from source:
+If an optional dependency is not installed, the corresponding tests will be skipped rather than failed.
-```sh
-git clone -b v2.2.1 https://github.com/capnproto/pycapnp
-pip3 install ./pycapnp
-```
+| Package manager | Python | sqlite3<br>(wallet tests) | zmq<br>(ZMQ tests) | capnp<br>(IPC tests) | lsof <sup><a href="#note1">[1]</a></sup><br>(network tests) |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **pip** | n/a | n/a | `pyzmq` | `pycapnp` | n/a |
+| **Debian/Ubuntu**<br>(`apt`) | `python3` | included | `python3-zmq` | n/a | n/a |
+| **macOS**<br>(`brew`) | `python3` | included | n/a | n/a | n/a |
+| **Windows**<br>(`winget`) | `python3` | included | n/a | n/a | n/a |
+| **FreeBSD**<br>(`pkg`) | `python3` | `databases/py-sqlite3` | `net/py-pyzmq` | n/a | `sysutils/lsof` |
+| **NetBSD**<br>(`pkgin`) | `python313` | included | `py313-zmq` | n/a | `lsof` |
+| **OpenBSD**<br>(`pkg_add`) | `python` | included | `py3-zmq` | n/a | n/a |
-If that does not work, try adding `-C force-bundled-libcapnp=True` to the `pip` command.
-Depending on the system, it may be necessary to install and run in a venv:
+<a id="note1"></a>1. Only used on non-Linux systems. macOS ships `lsof` in the base system. OpenBSD and Windows do not provide it, and the tests requiring it are always skipped there.
-```sh
-python -m venv venv
-git clone -b v2.2.1 https://github.com/capnproto/pycapnp
-venv/bin/pip3 install ./pycapnp -C force-bundled-libcapnp=True
-venv/bin/python3 build/test/functional/interface_ipc.py
-```
+#### UTF-8 mode
The functional tests assume Python UTF-8 Mode, which is the default on most
systems.
-On Windows the `PYTHONUTF8` environment variable must be set to 1:
-```cmd
-set PYTHONUTF8=1
+On Windows, when using Python < 3.15, the `PYTHONUTF8` environment variable must be set to 1.
+For example, in PowerShell:
+
+```powershell
+$env:PYTHONUTF8 = 1
```
-#### Running the tests
+### Running the tests
Individual tests can be run by directly calling the test script, e.g.:
@@ -128,7 +129,7 @@ how many jobs to run, append `--jobs=n`
The individual tests and the test_runner harness have many command-line
options. Run `build/test/functional/test_runner.py -h` to see them all.
-#### Speed up test runs with a RAM disk
+### Speed up test runs with a RAM disk
If 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.
Speed-up amount varies on each system (and according to your RAM speed and other variables), but a 2-3x speed-up is not uncommon.
@@ -179,9 +180,9 @@ To unmount:
umount /Volumes/ramdisk
```
-#### Troubleshooting and debugging test failures
+### Troubleshooting and debugging test failures
-##### Resource contention
+#### Resource contention
The P2P and RPC ports used by the bitcoind nodes-under-test are chosen to make
conflicts with other processes unlikely. However, if there is another bitcoind
@@ -209,7 +210,7 @@ pkill -9 bitcoind
```
-##### Data directory cache
+#### Data directory cache
A pre-mined blockchain with 200 blocks is generated the first time a
functional test is run and is stored in build/test/cache. This speeds up
@@ -223,7 +224,7 @@ rm -rf build/test/cache
killall bitcoind
```
-##### Test logging
+#### Test logging
The tests contain logging at five different levels (DEBUG, INFO, WARNING, ERROR
and CRITICAL). From within your functional tests you can log to these different
@@ -268,7 +269,7 @@ By default, the test data directory will be deleted after a successful run.
Use `--nocleanup` to leave the test data directory intact. The test data
directory is never deleted after a failed test.
-##### Attaching a debugger
+#### Attaching a debugger
A python debugger can be attached to tests at any point. Just add the line:
@@ -318,7 +319,7 @@ Often while debugging RPC calls in functional tests, the test might time out bef
process can return a response. Use `--timeout-factor 0` to disable all RPC timeouts for that particular
functional test. Ex: `build/test/functional/wallet_hd.py --timeout-factor 0`.
-### Lint tests
+## Lint tests
See the README in [test/lint](/test/lint).
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.