Skip to main content

Crate fnmock

Crate fnmock 

Source
Expand description

A Rust mocking framework for standalone functions and methods in an impl block.

fnmock lets you mock a plain function in tests without adding a trait or dependency-injection wiring. Annotate the function with mockable where it already lives. The test can then decide what the function returns and assert on how it was called.

ⓘ
#[fnmock::mockable]
fn fetch_user_name(id: u32) -> String {
    // real database call
}

fn greet(id: u32) -> String {
    format!("Hello, {}", fetch_user_name(id))
}

#[test]
fn test_greeting() {
    let mock = fetch_user_name_mock();
    mock.setup(|_| "Test".into());                  // replace what it returns ...
    mock.expect(fnmock::predicate::eq(1)).once();   // ... and expect how it is called

    assert_eq!(greet(1), "Hello, Test");

    mock.assert();
}

Every call is recorded, including calls the setup closure answers. Without setup, the real body runs. clear() resets the whole mock.

expect and expectf return an ExpectationHandle, which refines the expectation by chaining:

  • times, which takes anything that converts into a CallRange (a count or a range)
  • once
  • never
  • describe
  • in_sequence, which adds the expectation to a Sequence

A Sequence orders expectations across several functions.

§Only need one half?

Two smaller attributes each provide one half of a mock:

  • fakeable generates <fn_name>_fake() with setup, is_set and clear. It replaces the body and records nothing. It also accepts destructuring parameters, which a mock can’t record.
  • spyable generates <fn_name>_spy() with the expectation methods only. The real body always runs. It also accepts -> impl Trait and -> !, which a mock can’t produce.

§Crate layout

mockable, fakeable and spyable are the whole API you apply to production code. The types a test touches are ExpectationHandle, CallRange, Sequence and the re-exported predicate builders. Every other module (the stores, matchers and expectations) exists only because the code the macros expand to has to name it. They are fnmock internals, and you shouldn’t use them directly.

Mocks are kept per thread and their injected code is #[cfg(test)]-gated. Each #[test] therefore gets its own isolated state, and release builds compile no mock code at all. The flip side is that a mock can only be set up from a #[cfg(test)] unit test inside the crate that defines the annotated item.

See the README for installation, a walkthrough and the current limitations.

Modules§

predicate
Re-export the predicate builders so that users of the library can just use fnmock::predicate instead of having to depend on predicates directly. Predicate factories

Structs§

CallRange
A call-count range, converted from any concrete RangeBounds<usize> impl.
ExpectationHandle
What expect hands back to the test, so the expectation can be refined by chaining.
Sequence
An order the calls matching its expectations have to be made in.

Traits§

Predicate
Re-export the predicate builders so that users of the library can just use fnmock::predicate instead of having to depend on predicates directly. Trait for generically evaluating a type against a dynamically created predicate function.
PredicateBooleanExt
Re-export the predicate builders so that users of the library can just use fnmock::predicate instead of having to depend on predicates directly. Predicate extension that adds boolean logic.
PredicateBoxExt
Re-export the predicate builders so that users of the library can just use fnmock::predicate instead of having to depend on predicates directly. Predicate extension for boxing a Predicate.
PredicateFileContentExt
Re-export the predicate builders so that users of the library can just use fnmock::predicate instead of having to depend on predicates directly. Predicate extension adapting a slice Predicate.
PredicateStrExt
Re-export the predicate builders so that users of the library can just use fnmock::predicate instead of having to depend on predicates directly. Predicate extension adapting a str Predicate.

Attribute Macros§

fakeable
Re-export the derive macro. Replace a free function’s or impl method’s body in tests, without recording calls.
mockable
Re-export the derive macro. Mock a free function or the methods of an inherent impl block in tests.
spyable
Re-export the derive macro. Record a free function’s or impl method’s calls in tests and assert on them. The real body always runs.