Expand description
Integration test infrastructure for the etcdrs workspace.
This crate provides utilities for spawning real etcd server instances and clusters in tests,
along with rstest fixtures for common configurations.
§Test Fixtures
With the rstest feature enabled, this crate provides two fixtures:
etcd_server– a single-nodeEtcdServerwith a temporary data directory and random ports.etcd_cluster– a multi-nodeEtcdCluster(3 peers by default) for testing replication and failover.
Both fixtures return once a linearizable member list names exactly the servers they started. If one of those etcd processes exits first, for example because another process took one of its ports, the fixture starts over with new ports and names, up to three attempts in all.
use etcdrs_test::{etcd_server, EtcdServer};
use rstest::rstest;
#[rstest]
#[tokio::test]
async fn my_test(etcd_server: EtcdServer) {
let client = etcdrs::Client::new(&etcd_server.connect_string()).unwrap();
// ...
}§Manual Configuration
For more control, build an EtcdServerConfig or EtcdClusterConfig directly:
EtcdServerConfig::new_single_temporarycreates a single-node config with random ports and a temporary data directory.EtcdClusterConfig::with_generated_peerscreates a multi-node cluster config with the specified number of peers.
Call .start() to launch the server or cluster process.
§Data and Logs
Each server has a private directory named etcd-srvr-<random letters> in std::env::temp_dir.
etcd keeps its data in the data subdirectory, and its stdout and stderr go to etcd.log, not to
the test’s output. A restarted server reuses its data and appends to its log.
§Stopping etcd
Stopping or dropping a server kills its etcd process. etcd is also killed when the test process
exits without dropping the server, whether it exits through std::process::exit, an abort or a
SIGKILL from a CI timeout, or the server is never dropped, like one in a static or an rstest
#[once] fixture. The server’s directory is left behind in that case.
- Linux – etcd is spawned with
PR_SET_PDEATHSIGset toSIGKILL, from a thread that never exits. - macOS and other Unix – etcd joins the process group of a
/bin/shwatchdog, which kills that group once the test process exits. - Windows – etcd is put in a job object that kills it once the test process exits. etcd is spawned before it is put in the job, so a test process that exits in between leaves it running.
- Other platforms – etcd keeps running.
§etcd Binary Resolution
The etcd binary is resolved in the following order:
- The
ETCDenvironment variable, if set and non-empty. - A vendored binary from
etcd-bin-vendored(covers most platforms with no manual install). etcdon the systemPATH.
In most cases, the vendored binary handles resolution automatically and no configuration is needed.
§Environment Variables
ETCD– path to the etcd binary (see etcd Binary Resolution).ETCDRS_KEEP_TEST_DIR– set to1ortrueto prevent automatic cleanup of server directories (see Data and Logs) after a test passes. By default, they are removed when a test completes successfully; they are always kept when a test fails so you can inspect etcd’s data and log. Any other value emits a warning and is treated asfalse.
§Feature Flags
rstest– enables theetcd_serverandetcd_clusterfixtures.
Re-exports§
pub use server::fixtures::etcd_cluster;pub use server::fixtures::etcd_server;
Structs§
- Etcd
Cluster - Etcd
Cluster Config - Etcd
Server - A single instance of an etcd server.
- Etcd
Server Config
Enums§
- Cluster
State - Whether a server is bootstrapping a new cluster or joining an existing one.