#environment #process #integration #integration-tests #electrs #temp-dir #connected

electrsd

Utility to run a regtest electrs process, useful in integration testing environment

38 releases (breaking)

0.29.0 Sep 11, 2024
0.28.0 May 29, 2024
0.27.3 Apr 4, 2024
0.27.1 Jan 25, 2024
0.8.0 Jul 26, 2021

#13 in #connected

Download history 1368/week @ 2024-06-26 1715/week @ 2024-07-03 2332/week @ 2024-07-10 1830/week @ 2024-07-17 1340/week @ 2024-07-24 1972/week @ 2024-07-31 2375/week @ 2024-08-07 3102/week @ 2024-08-14 2448/week @ 2024-08-21 2219/week @ 2024-08-28 2353/week @ 2024-09-04 2761/week @ 2024-09-11 1753/week @ 2024-09-18 1946/week @ 2024-09-25 1951/week @ 2024-10-02 2823/week @ 2024-10-09

8,894 downloads per month
Used in 18 crates (12 directly)

MIT license

35KB
602 lines

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

Dependencies

~12–21MB
~288K SLoC