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, andsnare::mioare drop-in replacements for the corresponding standard /miomodules. When theshimfeature 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. Whenshimis off, they'repub usere-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:
[]
= "1"
[]
= { = "1", = ["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 ;
use ;
;
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. ReturnSome(pkt)to forward to the next handler in the chain,Noneto drop.then_action/then_stateful_action— same shape, but return aTesterAction(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 returningtrueends 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| ...)configuresloss_rate,duplicate_rate,reorder_jitter,inbound_latency,send_queue_depth, andmtu. Useseed_rng(...)for deterministic loss/dup tests. - TCP:
set_tcp_inbound_latency(addr, dur)delays bytes inbound toaddr;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 byInstant::now()since the virtual epoch, and the offset intoSystemTime::now());time_value()reads it;advance_time(dur)jumps it forward, even while paused.rate— how fastvalueadvances relative to real time.set_time_rate(1.0)tracks the real clock (the default),0.0pauses it sonow()stops advancing,>1.0runs fast.pause_time()/resume_time()are shorthands for rate0.0/1.0. The rate can't go negative —set_time_ratepanics on a negative or non-finite value, since a backwards clock would break the monotonicity ofInstant::now().
register_test;
pause_time; // freeze time
let t0 = now;
advance_time; // 30s "passes" instantly
assert_eq!;
set_time_rate; // 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(...)andsnare::thread::Builder::spawn(...)— same signatures asstd::thread, but they register the child against the spawning thread's test before running the closure.handle.register_as_child()(extension trait onJoinHandle,Thread, andThreadId) — for when you already have astd::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(), andregister_thread_child_of()are optional no-ops.- Plain
std::thread::spawnworks — 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:
[]
= ["--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— exposesnare::mio. Required if your SUT usesmiodirectly; 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.
SNARE_PCAPNG_DIR=/tmp/snare-pcaps
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 \
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
writecall (plus a peer ACK), so segmentation reflects when the SUT calledwrite, not real TCP-stack chunking. - UDP is captured at
send_totime 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.