snare 1.4.1

Network communication testing library for rust
Documentation

snare

A pseudo-integration testing library for code that talks over TCP, UDP, or mio. Snare swaps out std::net, std::thread, and mio with drop-in modules that, under tests, route every byte through an in-process mock — and re-export the real types otherwise, so the same code runs against the real network in production with zero overhead.

The point is to write tests that exercise actual TcpStream::connect, UdpSocket::send_to, Poll::poll, etc. paths in your code without binding to real ports, racing the OS scheduler, or pulling in a tokio runtime just to drive a fake server.

How it works

There are two pieces:

  • The shim. snare::net, snare::thread, and snare::mio are drop-in replacements for the corresponding standard / mio modules. When the shim feature is on (which you only turn on for [dev-dependencies]) every socket call is intercepted and serviced from a per-test in-memory state slot. When shim is off, they're pub use re-exports — your release build sees zero indirection.

  • The tester. A small builder API (connect_tester, then_action, with_cyclic_action, until_condition, ...) describes what the "other side of the wire" should do: respond to packets, fire cyclic sends, inject errors, close the connection after N messages, etc. run_testers! drives the loop until every tester's finish condition fires.

So in a typical test you write the SUT against snare::net::TcpStream, spawn it on a snare::thread::spawn, and on the test thread build a NetTester that plays the role of the peer.

Setup

Use snare as a regular dep without shim, and as a dev-dep with shim enabled. Cargo merges the two feature sets and only turns shim on under the test profile:

[dependencies]
snare = "1"

[dev-dependencies]
snare = { version = "1", features = ["shim", "mio-compat"] }

mio-compat is only needed if your SUT uses mio directly. Drop it otherwise.

In your code, replace these imports project-wide:

Replace With
std::net::{TcpListener, TcpStream, UdpSocket} snare::net
std::thread snare::thread
std::time::{Instant, SystemTime} snare::time
mio::{Poll, Waker, Token, Interest, event, net} snare::mio

The release build resolves these to the real things; tests resolve them to the shim. No #[cfg(test)] toggling at the call site.

Writing a test

Every test that touches the shim has to start with register_test() — this is what carves out the per-test state slot. Threads the test or SUT spawns need to be attached to that slot, which snare::thread::spawn handles for you. If you reach for std::thread::spawn, chain .register_as_child() on the join handle, or call register_thread_child_of(...) from inside the spawned closure.

A minimal test where the SUT sends a UDP packet and the tester echoes one byte back:

use std::{net::SocketAddr, time::Duration};
use snare::{
    Packetable, SocketType, TesterAction, TimerState, UdpSocket,
    connect_tester, register_test, run_testers,
};

#[derive(Clone, Debug)]
struct Bytes(Vec<u8>);

impl Packetable for Bytes {
    const CAN_BE_FLATTENED: bool = false;
    const SOCKET_TYPE: SocketType = SocketType::Udp;
    fn encode(&self) -> Vec<u8> { self.0.clone() }
    fn decode(data: &[u8]) -> Option<(Self, usize)> {
        (!data.is_empty()).then(|| (Bytes(data.to_vec()), data.len()))
    }
}

#[test]
fn echoes_first_byte() {
    register_test();

    let server_addr: SocketAddr = ([127, 0, 0, 1], 4000).into();
    let client_addr: SocketAddr = ([127, 0, 0, 1], 4001).into();

    let mut tester = connect_tester::<Bytes>(server_addr)
        .then_action(|pkt, src| TesterAction::Send(src, Bytes(vec![pkt.0[0]])))
        .until_stateful_condition::<TimerState>(|t| t.poll_elapsed() >= Duration::from_secs(1));

    // The SUT — a thread that sends and reads back.
    snare::thread::spawn(move || {
        let sock = UdpSocket::bind(client_addr).unwrap();
        sock.send_to(b"hi", server_addr).unwrap();
        let mut buf = [0u8; 16];
        let (n, _) = sock.recv_from(&mut buf).unwrap();
        assert_eq!(&buf[..n], b"h");
    });

    run_testers!(tester);
}

The same shape works for TCP — set SOCKET_TYPE = SocketType::Tcp, implement decode to handle partial reads (return None when the buffer doesn't yet contain a complete frame; snare will keep calling you as more bytes arrive), and use snare::net::TcpStream / TcpListener in the SUT.

Tester API

NetTester is built up with chained then_* and with_* calls:

  • then_test / then_stateful_test — packet handlers. Return Some(pkt) to forward to the next handler in the chain, None to drop.
  • then_action / then_stateful_action — same shape, but return a TesterAction (send a reply, close the socket, inject an error, ...).
  • then_edit_state — mutate state per packet without inspecting it.
  • with_cyclic_action / with_stateful_cyclic_action — fire on a fixed interval, regardless of incoming traffic.
  • with_state — eagerly initialize a state slot with a configured value.
  • until_condition / until_stateful_condition — finish conditions. Any returning true ends the tester. With none configured, the tester ends once there are no pending packets.
  • peek_state — borrow state after the run for assertions.

State is typed and stored in an AnyMap per tester, so handlers ask for the type they need (<MyCounter>) and snare lazy-inits a Default if absent.

TesterAction covers: Send, RaiseSocketError, CloseSocket, Multiple, Quiesce / QuiesceWithMode, ResetTcp, SetListenerBehavior, SetTcpInboundLatency, SetTcpRecvWindow, SetUdpPolicy. The last few are how you mutate link policy mid-test from inside a tester closure.

Fault injection and link policy

The same primitives are available directly (not via a tester) for setup that runs before run_testers!:

  • UDP: set_udp_policy(addr, |p| ...) configures loss_rate, duplicate_rate, reorder_jitter, inbound_latency, send_queue_depth, and mtu. Use seed_rng(...) for deterministic loss/dup tests.
  • TCP: set_tcp_inbound_latency(addr, dur) delays bytes inbound to addr; set_tcp_recv_window(addr, Some(n)) caps the SUT's receive buffer so writes back-pressure.
  • Listeners: set_listener_behavior(addr, Refusing | DelayingUntil(t) | Accepting) controls how connects resolve.
  • Connection lifecycle: reset_tcp(addr) synthesizes a peer RST; quiesce(addr, dur) suppresses mio readiness in one or both directions for a window.
  • Recording log: recorded_events() returns a timestamped log of every send/close/quiesce/reset/error that crossed the test boundary. Useful for "did we hit the retry path?" style assertions. clear_recorded_events() scopes the log to one phase.

Virtual clock

snare::time is a drop-in for std::time. Point your SUT at snare::time::Instant / snare::time::SystemTime (Duration is untouched) and, under the shim, both read from a per-test virtual clock instead of the OS. Off the shim it re-exports std::time, so release builds see the real clock with zero overhead.

The clock has two knobs:

  • value — what the clock reads right now. set_time_value(dur) sets it (the elapsed reported by Instant::now() since the virtual epoch, and the offset into SystemTime::now()); time_value() reads it; advance_time(dur) jumps it forward, even while paused.
  • rate — how fast value advances relative to real time. set_time_rate(1.0) tracks the real clock (the default), 0.0 pauses it so now() stops advancing, >1.0 runs fast. pause_time() / resume_time() are shorthands for rate 0.0 / 1.0. The rate can't go negative — set_time_rate panics on a negative or non-finite value, since a backwards clock would break the monotonicity of Instant::now().
snare::register_test();
snare::pause_time();                              // freeze time
let t0 = snare::time::Instant::now();
snare::advance_time(Duration::from_secs(30));     // 30s "passes" instantly
assert_eq!(t0.elapsed(), Duration::from_secs(30));

snare::set_time_rate(60.0);                        // now 1 real sec = 1 virtual min

The clock resolves through the same thread-chain hierarchy as the network shims — every thread the test owns shares one clock — and collapses to a single process-wide clock under --cfg snare_global, just like the rest of the shim state.

snare::thread::sleep is tied to this clock too: it blocks until virtual time has advanced by its duration. So a paused clock parks the sleeper until you advance_time (or resume_time) it from another thread, and a fast clock wakes it after proportionally less real time. When a test needs to wait in real wall-clock time regardless of the rate — polling real I/O, an OS background thread — use snare::thread::real_sleep, which is a straight alias for std::thread::sleep (and is available off the shim too). The tester loop itself still runs in real time.

Thread tracking

Every shim call resolves a per-thread "which test owns me?" lookup. The test thread itself is registered by register_test(); child threads must opt in. The easy ways:

  • snare::thread::spawn(...) and snare::thread::Builder::spawn(...) — same signatures as std::thread, but they register the child against the spawning thread's test before running the closure.
  • handle.register_as_child() (extension trait on JoinHandle, Thread, and ThreadId) — for when you already have a std::thread::spawn(...) result.
  • register_thread_child_of(parent_id) — for when the registration has to happen from inside the spawned closure (e.g. you only learn the parent id at runtime).

Unregistered threads that touch the shim hit a 2s grace-period poll before panicking, so a late .register_as_child() still works under CI contention. Don't rely on that for normal code paths.

Global mode: one shared network for the whole process

Per-test isolation is the right model for #[test]s, but it's the wrong model for a long-running single-process simulation — e.g. driving real device drivers against an in-process emulator, where conductor threads, driver worker threads, and the emulator all need to see one shared virtual network and there is no "test" to scope them to.

Build with --cfg snare_global and every thread in the process funnels to one shared state slot instead of a per-test one. In this mode:

  • register_test(), register_child_thread(), and register_thread_child_of() are optional no-ops.
  • Plain std::thread::spawn works — no .register_as_child(), no grace poll, no "not a valid test thread" panic. Every thread shares the same sockets, listeners, valid-IP set, and RNG.
  • The slot auto-vivifies on first access.

Set it for the whole build (it must compile snare once with the cfg), e.g. in the sim binary's .cargo/config.toml:

[build]
rustflags = ["--cfg", "snare_global"]

or RUSTFLAGS='--cfg snare_global' cargo build. Leave it off for ordinary test builds, which want isolation. The cfg only matters when shim is on.

Features

  • shim — turn on the in-process mock. Off by default so production builds re-export the real types.
  • mio-compat — expose snare::mio. Required if your SUT uses mio directly; otherwise leave it off.

snare::time and its clock controls (set_time_rate, pause_time, ...) also live behind shim — off the feature, snare::time is a plain std::time re-export and the controls aren't compiled.

pcapng capture

Snare can write every byte that crosses the shim to a .pcapng file you can open in Wireshark. Off by default; opt in via env vars.

The shim has no real packets, so the writer fabricates Ethernet + IPv4/IPv6 + TCP/UDP framing per flow — including a synthetic 3-way handshake and ACKs — so the output renders as a normal conversation in Wireshark.

Enable for a specific test

Call snare::enable_pcapng() after register_test(). Capture only happens when SNARE_PCAPNG_DIR is set in the environment; otherwise it's a no-op, so this line is safe to leave in committed test code.

#[test]
fn my_test() {
    snare::register_test();
    snare::enable_pcapng();
    // ... rest of the test
}
SNARE_PCAPNG_DIR=/tmp/snare-pcaps cargo test my_test

Enable from outside the test

Set SNARE_PCAPNG_TESTS to a comma-separated list of test thread names (for cargo this is the test function path) to force-enable capture without touching the test code:

SNARE_PCAPNG_DIR=/tmp/snare-pcaps \
SNARE_PCAPNG_TESTS=my_test,other_mod::another_test \
  cargo test

Output

One <dir>/<test thread name>.pcapng file per test. Cargo names test threads after the test path, so they're filename-safe after a light sanitization.

Caveats

  • TCP byte streams emit one PSH/ACK segment per write call (plus a peer ACK), so segmentation reflects when the SUT called write, not real TCP-stack chunking.
  • UDP is captured at send_to time regardless of whether anything receives it — SUT↔SUT UDP delivery in the shim is framework-driven, but the tap fires unconditionally.
  • IP/TCP/UDP checksums are written as zero (Wireshark reads these as "checksum offload"); MACs are deterministic from the socket addr.