Utility to run a regtest bitcoind process, useful in integration testing environment.
When the auto-download feature is selected by activating one of the version feature, such as
for bitcoin core 25.0, starting a regtest node is as simple as that:
// the download feature is enabled whenever a specific version is enabled, for example `25_0` or `24_0_1`
The build script will automatically download the bitcoin core version 25.0 from bitcoin core,
verify the hashes and place it in the build directory for this crate. If you wish to download from an
alternate location, for example locally for CI, use the
BITCOIND_DOWNLOAD_ENDPOINT env var.
When you don't use the auto-download feature you have the following options:
bitcoindexecutable in the
- provide the
bitcoindexecutable via the
use RpcApi; if let Ok = exe_path
Startup options could be configured via the [
Conf] struct using [
Issues with traditional approach
I used integration testing based on external bash script launching needed external processes, there are many issues with this approach like:
- External script may interfere with local development environment 1
- Use of a single huge test to test everything 2
- If test are separated, a failing test may fail to leave a clean situation, causing other test to fail (because of the initial situation, not a real failure)
- bash script are hard, especially support different OS and versions
- It waits until bitcoind daemon become ready to accept RPC commands
bitcoinduse a temporary directory as datadir. You can specify the root of your temp directories so that you have node's datadir in a RAM disk (eg
- Free ports are asked to the OS. Since you can't reserve the given portm a low probability race condition is still possible, for this reason the process is tried to be spawn 3 times with different ports.
- The process is killed when the struct goes out of scope no matter how the test finishes
- Allows easy spawning of dependent processes like:
Thanks to these features every
#[test] could easily run isolated with its own environment.
To build docs:
The MSRV is 1.48.0 for version 0.29.* if no feature is used, otherwise is 1.57
Note: to respect 1.48.0 MSRV you need to use and older version of the which and tempfile dependencies, like it's done in the CI:
Cargo.toml is avoided because it could cause
compilation issues downstream.
For reproducibility reasons, Nix build scripts cannot hit the internet, but the
auto-download feature does exactly that. To successfully build under Nix the
user must provide the tarball locally and specify its location via the
BITCOIND_TARBALL_FILE env var.
Alternatively, use the dep without auto-download feature.