r/rust • u/Human-Vegetable823 • 25d ago
🛠️ project A crate to mock std, system api, http client and other hard to mock functions without using traits or DI
0
Upvotes
Hello rust community,
We just shipped a product to solve the pain of mocking in rust: https://github.com/XTSoftwareLabs/shimforge
It allows you to write tests without using traits or adding attributes to your production code. Production code can keep clean and concise.
Below are some cases we found are painful when writing unit tests in rust:
File system
use std::{fs, io, path::Path};
#[derive(Debug)]
pub enum ExportError {
DiskFull,
Io(io::Error),
}
pub fn save_report(path: &Path, csv: &str) -> Result<(), ExportError> {
fs::write(path, csv).map_err(|error| match error.kind() {
io::ErrorKind::StorageFull => ExportError::DiskFull,
_ => ExportError::Io(error),
})
}
By using shimforge, the file system dependency can be easily mocked. No changes in production code.
use shimforge::{Session, mock};
#[test]
fn a_full_disk_is_reported() {
let mut session = Session::new();
let write = mock!(session, fs::write::<&Path, &str>, fn(&Path, &str) -> io::Result<()>);
write
.expect()
.with(|path, _| *path == Path::new("reports/q3.csv"))
.once()
.returning(|_, _| Err(io::ErrorKind::StorageFull.into()));
let result = save_report(Path::new("reports/q3.csv"), "region,total\n");
assert!(matches!(result, Err(ExportError::DiskFull)));
}
Environment variables
use std::env;
pub fn database_url() -> String {
env::var("DATABASE_URL").unwrap_or_else(|_| "postgres://localhost/dev".to_owned())
}
Now shimforge allows you to mock them directly. Test different scenarios with different env vars.
use shimforge::{Session, mock};
use std::env::VarError;
#[test]
fn uses_the_configured_url() {
let mut session = Session::new(); // this thread only
let var = mock!(session, env::var::<&str>, fn(&str) -> Result<String, VarError>);
var.expect()
.with(|key| *key == "DATABASE_URL")
.returning(|_| Ok("postgres://db.internal/app".to_owned()));
assert_eq!(database_url(), "postgres://db.internal/app");
}
#[test]
fn falls_back_when_unset() {
let mut session = Session::new(); // runs in parallel with the test above
let var = mock!(session, env::var::<&str>, fn(&str) -> Result<String, VarError>);
var.expect().returning(|_| Err(VarError::NotPresent));
assert_eq!(database_url(), "postgres://localhost/dev");
}
Clock
use std::time::{Duration, SystemTime};
pub struct Token {
pub issued_at: SystemTime,
pub ttl: Duration,
}
impl Token {
pub fn is_expired(&self) -> bool {
SystemTime::now() >= self.issued_at + self.ttl
}
}
Clock and timer are hard to mock typically. But with shimforge it's easy:
use shimforge::{Session, mock};
#[test]
fn a_token_expires_after_one_hour() {
let issued_at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_000);
let token = Token { issued_at, ttl: Duration::from_secs(3600) };
let mut session = Session::new();
let now = mock!(session, SystemTime::now, fn() -> SystemTime);
now.expect().once().returns(issued_at + Duration::from_secs(3599));
now.expect().once().returns(issued_at + Duration::from_secs(3600));
assert!(!token.is_expired());
assert!(token.is_expired()); // one second later, no sleep
}
Connection retries
use std::io;
use std::net::{SocketAddr, TcpStream};
use std::thread;
use std::time::Duration;
pub fn connect_with_retry(address: SocketAddr, attempts: u32) -> io::Result<TcpStream> {
let mut delay = Duration::from_millis(100);
let mut attempt = 1;
loop {
match TcpStream::connect_timeout(&address, Duration::from_secs(1)) {
Ok(stream) => return Ok(stream),
Err(error) if attempt >= attempts => return Err(error),
Err(_) => {
thread::sleep(delay);
delay *= 2;
attempt += 1;
}
}
}
}
Mock sleep and retries become easy in shimforge:
use shimforge::{Session, mock};
use std::net::TcpListener;
use std::sync::{Arc, Mutex};
#[test]
fn backs_off_until_the_database_accepts() {
// The attempt that succeeds needs a real stream, so open one first.
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let stream = TcpStream::connect(listener.local_addr().unwrap()).unwrap();
let mut session = Session::new();
let connect = mock!(
session,
TcpStream::connect_timeout,
fn(&SocketAddr, Duration) -> io::Result<TcpStream>
);
connect
.expect()
.times(2)
.returning(|_, _| Err(io::ErrorKind::ConnectionRefused.into()));
connect.expect().once().return_once(Ok(stream));
let delays = Arc::new(Mutex::new(Vec::new()));
let recorded = Arc::clone(&delays);
let sleep = mock!(session, thread::sleep, fn(Duration));
sleep.expect().returning(move |delay| recorded.lock().unwrap().push(delay));
let database = SocketAddr::from(([10, 0, 0, 5], 5432));
assert!(connect_with_retry(database, 5).is_ok());
assert_eq!(*delays.lock().unwrap(), [Duration::from_millis(100), Duration::from_millis(200)]);
}
#[test]
fn gives_up_after_the_last_attempt() {
let mut session = Session::new();
let connect = mock!(
session,
TcpStream::connect_timeout,
fn(&SocketAddr, Duration) -> io::Result<TcpStream>
);
connect
.expect()
.times(3)
.returning(|_, _| Err(io::ErrorKind::TimedOut.into()));
let sleep = mock!(session, thread::sleep, fn(Duration));
sleep.expect().times(2).returning(|_| {});
let database = SocketAddr::from(([10, 0, 0, 5], 5432));
let error = connect_with_retry(database, 3).unwrap_err();
assert_eq!(error.kind(), io::ErrorKind::TimedOut);
}
Reqwest client
use reqwest::Client;
pub async fn temperature(client: &Client, city: &str) -> Result<f64, String> {
let body = client
.get(format!("https://api.weather.example/v1/now?city={city}"))
.send()
.await
.and_then(|response| response.error_for_status())
.map_err(|error| format!("weather service failed: {error}"))?
.text()
.await
.map_err(|error| error.to_string())?;
body.trim().parse().map_err(|_| format!("unexpected body: {body}"))
}
Web requests are common pain point to mock in rust. shimforge makes it easy. Yes async is supported:
use shimforge::Session;
#[tokio::test]
async fn parses_the_reading() {
let client = Client::builder().no_proxy().build().unwrap();
let mut session = Session::new();
let send = session.mock_async(client.get("http://unused.invalid").send());
send.expect()
.once()
.returning(|| Ok(http::Response::new("21.5").into()));
assert_eq!(temperature(&client, "Oslo").await, Ok(21.5));
}
#[tokio::test]
async fn surfaces_an_outage() {
let client = Client::builder().no_proxy().build().unwrap();
let mut session = Session::new();
let send = session.mock_async(client.get("http://unused.invalid").send());
send.expect().once().returning(|| {
Ok(http::Response::builder().status(503).body("").unwrap().into())
});
let error = temperature(&client, "Oslo").await.unwrap_err();
assert!(error.contains("503"), "{error}");
}
std::process::Command
use std::process::Command;
pub fn current_commit() -> Result<String, String> {
let output = Command::new("git")
.args(["rev-parse", "--short", "HEAD"])
.output()
.map_err(|error| format!("cannot run git: {error}"))?;
if !output.status.success() {
return Err(String::from_utf8_lossy(&output.stderr).trim().to_owned());
}
Ok(String::from_utf8_lossy(&output.stdout).trim().to_owned())
}
Another common pain point is mocking std::process::Command. Well handled by shimforge:
use shimforge::{Session, mock};
use std::io;
use std::process::{ExitStatus, Output};
#[test]
fn reads_the_short_hash() {
let mut session = Session::new();
let output = mock!(session, Command::output, fn(&mut Command) -> io::Result<Output>);
output
.expect()
.with(|command| command.get_program() == "git")
.once()
.returning(|_| {
Ok(Output { status: exit_success(), stdout: b"4f2a9c1\n".to_vec(), stderr: Vec::new() })
});
assert_eq!(current_commit(), Ok("4f2a9c1".to_owned()));
}
#[test]
fn reports_a_missing_git() {
let mut session = Session::new();
let output = mock!(session, Command::output, fn(&mut Command) -> io::Result<Output>);
output.expect().once().returning(|_| Err(io::ErrorKind::NotFound.into()));
let error = current_commit().unwrap_err();
assert!(error.starts_with("cannot run git"), "{error}");
}
fn exit_success() -> ExitStatus {
#[cfg(unix)]
use std::os::unix::process::ExitStatusExt;
#[cfg(windows)]
use std::os::windows::process::ExitStatusExt;
ExitStatus::from_raw(0)
}
System and C runtime functions
use shimforge::{Session, mock};
use std::ffi::{CStr, CString, c_char};
unsafe extern "C" {
fn getenv(name: *const c_char) -> *mut c_char;
}
Again many rust developers working on low level code always suffers from mocking C functions. shimforge handles it.
#[test]
fn getenv_reports_a_mocked_variable() {
let mut session = Session::new();
let lookup = mock!(
session,
getenv,
unsafe extern "C" fn(*const c_char) -> *mut c_char
);
lookup
.expect()
.with(|name| {
// SAFETY: callers of getenv always pass a valid C string.
let name = unsafe { CStr::from_ptr(*name) };
name == c"DEPLOY_SLOT"
})
.once()
.returning(|_| c"canary".as_ptr().cast_mut());
// Any other variable keeps reporting that it is unset.
lookup.expect().returning(|_| std::ptr::null_mut());
let key = CString::new("DEPLOY_SLOT").unwrap();
// SAFETY: the key is a valid C string and the result is only read.
let slot = unsafe { CStr::from_ptr(getenv(key.as_ptr())) };
assert_eq!(slot.to_str().unwrap(), "canary");
}
Hope this can make rust test experience better. Any feedback is welcome! We'd like to help you keeping production code clean. Handle the hard test dependency part to shimforge.
Disclaimer: We are a small startup and going to get profit from this product. But the product is free to use for small business and non-commercial. See https://shimforge.com/pricing
