Skip to main content

Crate etcdrs_test

Crate etcdrs_test 

Source
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-node EtcdServer with a temporary data directory and random ports.
  • etcd_cluster – a multi-node EtcdCluster (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:

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_PDEATHSIG set to SIGKILL, from a thread that never exits.
  • macOS and other Unix – etcd joins the process group of a /bin/sh watchdog, 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:

  1. The ETCD environment variable, if set and non-empty.
  2. A vendored binary from etcd-bin-vendored (covers most platforms with no manual install).
  3. etcd on the system PATH.

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 to 1 or true to 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 as false.

§Feature Flags

  • rstest – enables the etcd_server and etcd_cluster fixtures.

Re-exports§

pub use server::fixtures::etcd_cluster;
pub use server::fixtures::etcd_server;

Structs§

EtcdCluster
EtcdClusterConfig
EtcdServer
A single instance of an etcd server.
EtcdServerConfig

Enums§

ClusterState
Whether a server is bootstrapping a new cluster or joining an existing one.

Functions§

etcd_cluster
etcd_server