snare
Deterministic, in-process simulation of the operating system for Rust tests — without changing the code under test.
Your code keeps calling std::net::TcpStream, std::fs::File, std::env::var, libc::sched_setscheduler,
clock_gettime, raw AF_PACKET/io_uring — exactly as it does in production. snare interposes at the
OS-call boundary underneath it and serves those calls from an in-memory model: a virtual network, a
virtual filesystem, a simulated host, a virtual clock. The test drives the other side of the wire.
use *;
use ;
use TcpStream;
let sim = new;
sim.run;
No shim types, no dependency injection, no trait objects threaded through the code under test. It is a
plain TcpStream.
snare patches the program's import tables so the libc and Win32 calls a managed thread makes
land in its hooks first; a hook serves the call from the model or lets it fall through to the real
OS. That reaches through std and every dependency. How it works has the
detail and the rules a test follows.
Quick start
$ cargo snare --init # snare under [target.'cfg(snare)'.dev-dependencies], cfg declared
$ cargo snare test # builds with --cfg snare, patches in the shims, runs the tests
use *;
Plain cargo test builds neither snare nor the #[cfg(snare)] tests. See The cargo snare
harness for what it sets and why, the shims it patches in, and snare::real
for a harness that needs the real machine.
What it simulates
- Time and entropy: a discrete-event virtual clock behind every clock call, seeded randomness, local time zones. Time, local time.
- Network: TCP, UDP, raw L2 (
AF_PACKET,/dev/bpf), readiness (epoll,kqueue,poll,WSAPoll), netlink, packet timestamps, faults and back-pressure, name resolution. Sockets, interfaces and routing, names and signals. - The host: CPUs, scheduling and affinity, resource limits, NIC drivers over
ethtool, qdiscs, PTP, the kernel's own threads, interrupt lines and NAPI,uname, capabilities. The simulated host. - Files: an in-memory file system, synthesized
/sys,/proc,/devand a tracefs. Files. - Signals, the environment, Windows' scheduling plane and Winsock. Everything covered, surface by surface.
The test drives the other side with scripted peers (testers), can capture what crossed the network to pcapng (packet capture), and controls the schedule and the clock (determinism and threads, the executive).
Platforms
Linux (glibc; x86_64, aarch64), macOS (aarch64, x86_64) and Windows (x86_64, aarch64); Rust 1.88 or
later. Every other target stops at a compile_error!. What each platform covers, the repository
layout and how to run snare's own tests are in Platforms and development.
Known gaps are in OPEN_BUGS.md.
Documentation
| How it works | the interposition model and the rules a test follows |
| What is simulated | every surface, in detail |
| The simulated host | SimHost, HostProfile, EasyBuilder; kernel threads, interrupts and NAPI |
| Files | VirtualFs, file timestamps, tracefs |
| Local time | time zones on each platform |
| Determinism, threads and the sim lifecycle | quiescence, clock spins, thread classes, stuck runs |
| Time, the executive and cooperative primitives | controlling time, an outside simulation owning the clock |
| Testers and recorded events | scripted peers and the event log |
| Packet capture | pcapng output |
| Interfaces, routing and NIC drivers | the topology, enumeration, ethtool, Windows adapters |
| Sockets | faults, connect faults, the socket table, timestamps, options, limits, counters |
| Names and signals | getaddrinfo and friends, signal delivery |
| The cargo snare harness | cargo snare, snare::real, the shims |
| Platforms and development | platform matrix, layout, running the tests, citations |
License
Licensed under the Apache License, Version 2.0. See LICENSE.