Skip to content

Latest commit

 

History

History
85 lines (59 loc) · 4.27 KB

README.md

File metadata and controls

85 lines (59 loc) · 4.27 KB
Raw

MIT license Crates

Electrsd

Utility to run a regtest electrs process connected to a given bitcoind instance, useful in integration testing environment.

let bitcoind = bitcoind::BitcoinD::new("/usr/local/bin/bitcoind").unwrap();
let electrsd = electrsd::ElectrsD::new("/usr/local/bin/electrs", bitcoind).unwrap();
let header = electrsd.client.block_headers_subscribe().unwrap();
assert_eq!(header.height, 0);

Automatic binaries download

In your project Cargo.toml, activate the following features

electrsd = { version= "0.23", features = ["bitcoind_23_1", "electrs_0_9_1"] }

Then use it:

let bitcoind_exe = bitcoind::downloaded_exe_path().expect("bitcoind version feature must be enabled");
let bitcoind = bitcoind::BitcoinD::new(bitcoind_exe).unwrap();
let electrs_exe = electrsd::downloaded_exe_path().expect("electrs version feature must be enabled");
let electrsd = electrsd::ElectrsD::new(electrs_exe, bitcoind).unwrap();

When the ELECTRSD_DOWNLOAD_ENDPOINT/BITCOIND_DOWNLOAD_ENDPOINT environment variables are set, electrsd/bitcoind will try to download the binaries from the given endpoints.

When you don't use the auto-download feature you have the following options:

  • have electrs executable in the PATH
  • provide the electrs executable via the ELECTRS_EXEC env var
if let Ok(exe_path) = electrsd::exe_path() {
  let electrsd = electrsd::electrsD::new(exe_path).unwrap();
}

Startup options could be configured via the Conf struct using electrsD::with_conf or electrsD::from_downloaded_with_conf.

Nix

For determinisim, in nix you cannot hit the internet within the build.rs. Moreover, some downstream crates cannot remove the auto-download feature from their dev-deps. In this case you can set the ELECTRSD_SKIP_DOWNLOAD env var and provide the electrs executable in the PATH (or skip the test execution).

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:

Features

  • electrsd use a temporary directory as db dir
  • A free port is asked to the OS (a very low probability race condition is still possible)
  • The process is killed when the struct goes out of scope no matter how the test finishes
  • Automatically download electrs executable with enabled features. Since there are no official binaries, they are built using the manual workflow under this project. Supported version are:

Thanks to these features every #[test] could easily run isolated with its own environment

Deprecations

  • Starting from version 0.26 the env var ELECTRS_EXE is deprecated in favor of ELECTRS_EXEC.

Used by