fnmock
A Rust mocking framework for standalone functions and methods in an impl block.
fnmock lets you replace or observe a function's behaviour in tests without introducing a trait / dependency injection wiring. You annotate the function where it already lives, and the test controls what it returns or asserts on how it was called.
greet keeps calling fetch_user_name directly — no signature changes, no indirection.
A spy works the other way round: the real body still runs, but the test can assert on which arguments it was called with.
Installation
The attribute is applied to production code, so fnmock is a regular dependency:
[]
= "<version>"
The fake lookup and the spy's call recording are both #[cfg(test)]-gated, so release builds keep
the original function body and compile no fake or spy machinery at all. The flip side: fakes and
spies can only be set up from a #[cfg(test)] unit test inside the crate that defines the
annotated item — not from an integration test under tests/, a doctest, or another crate. See
test scope in USAGE.md.
Documentation
- USAGE.md — how to use fakes: the accessor API, methods and receivers, generics, and how test isolation works.
- docs/FAKE_FEATURES.md — what is specific to
#[fnmock::fakeable]: the attribute, the_fake()accessor, andsetup/clear/is_set. - docs/SPY_FEATURES.md — what is specific to
#[fnmock::spyable]: the attribute, the_spy()accessor, the expectation methods, and the expectation DSL:times, global counts, sequences and the matching algorithm. - docs/LIMITATIONS.md — the shared support matrix: every type, pattern, generic shape, impl block form and isolation rule fnmock has been tested against, with a column for fakes and a column for spies, each cell linked to the test that backs it — so both what works and where the two macros differ are visible at a glance.
- fnmock-tests - fnmock's test cases can be useful for examples on how to use this project.
Overview
Applying #[fnmock::fakeable] to a function or an inherent impl block generates an accessor named
after it:
| Method | Behaviour |
|---|---|
setup(closure) |
Install a fake, replacing any previous one. |
clear() |
Remove the fake; calls run the real body again. |
is_set() |
Whether a fake is currently installed. |
In an impl block every method is faked and accessors are generated as associated functions.
Applying #[fnmock::spyable] instead generates a <fn_name>_spy() accessor (or, in an impl block,
Type::<fn_name>_spy()) that lets the test set expectations on the arguments a call is made with,
without changing what the function does:
| Method | Behaviour |
|---|---|
expect(predicate, …) |
Expect calls matching one predicate per parameter. |
expectf(closure) |
Same, but matching with a closure over all parameters. |
expect_times(n) / expect_once() / expect_never() |
Expect this many calls, whatever their arguments. |
assert() |
Panic unless every expectation set on this spy is fulfilled. |
The handle returned by expect/expectf can be refined further with times, once, never,
describe and in_sequence — see docs/SPY_FEATURES.md for the full
expectation DSL.
Both fakes and spies are stored per thread, and the test harness gives each #[test] its own
thread, so tests cannot leak into one another and no reset step is needed. The flip side is that a
fake or spy is only visible on the thread that installed it — see
test isolation for what that means around tokio::spawn and
std::thread::spawn.
Work in Progress
- Mocks
License
This project is licensed under the terms of both the MIT license and the Apache License (Version 2.0).
See LICENSE-APACHE, and LICENSE-MIT for details
Author
Jakob Rzeppa - rzeppa.jakob@gmail.com