snare 3.5.1

Ergonomic in-process network testing on top of snare-interpose: write the code under test against std, describe the peer with a tester builder
Documentation

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 snare::prelude::*;
use std::io::{BufRead, BufReader, Write};
use std::net::TcpStream;

let sim = Sim::new();
sim.run(|| {
    // The "server" the code under test talks to — scripted by the test.
    let server = connect_tester::<Line>("127.0.0.2:9000")
        .then_action(|msg, _from| TesterAction::Send(Line(format!("echo:{}", msg.0))));

    // The code under test: a real TcpStream. Its socket calls are serviced from memory.
    let client = std::thread::spawn(|| {
        let mut s = TcpStream::connect("127.0.0.2:9000").unwrap();
        s.write_all(b"hello\n").unwrap();
        let mut line = String::new();
        BufReader::new(s).read_line(&mut line).unwrap();
        line
    });

    run_testers!(server);
    assert_eq!(client.join().unwrap(), "echo:hello\n");
});

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
#![cfg(snare)]

use snare::prelude::*;

#[test]
fn deterministic() {
    Sim::new().run(|| { /* ... */ });
}

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, /dev and 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.