Struct double::mock::Mock

pub struct Mock<C, R> where
    C: Clone + Eq + Hash,
    R: Clone,  { /* fields omitted */ }

Used for tracking function call arguments and specifying a predetermined return value or mock function.

See the crate documentation for more substantial examples, including some that demonstrate how to use Mock for methods that have multiple arguments as well as methods with argument or return types that do not implement Clone.

Methods

impl<C, R> Mock<C, R> where
    C: Clone + Eq + Hash,
    R: Clone, 

pub fn new<T: Into<R>>(return_value: T) -> Self

Creates a new Mock that will return return_value.

pub fn call(&self, args: C) -> R

Use the Mock to return a value, keeping track of the arguments used.

If specific behaviour has been configured for a specific set of arguments, this will return (in this order of precedence): 1. the return value returned by the configured closure 2. the return value returned by the configured function 3. the configured return value If no specific behaviour has been configured for the input argument set, the mock falls back to default behaviour, in this order of precedence: 1. the return value returned by the default closure (if configured) 2. the return value returned by the default function (if configured) 3. next return value in default sequence (if sequence is not empty) 4. the default return value (always configured)

Examples

use double::Mock;

let mock = Mock::<&str, _>::new("return value");
assert_eq!(mock.call("something"), "return value");

mock.return_value("different value");
assert_eq!(mock.call("something"), "different value");

mock.return_values(vec!("one", "two"));
assert_eq!(mock.call("something"), "one");
assert_eq!(mock.call("something"), "two");
assert_eq!(mock.call("something"), "different value");

mock.use_fn(str::trim);
assert_eq!(mock.call("  test  "), "test");

mock.use_closure(Box::new(|x| x.trim_left()));
assert_eq!(mock.call("  test  "), "test  ");

mock.use_fn(str::trim);
assert_eq!(mock.call("  test  "), "test");

mock.return_value_for("  banana", "tasty");
assert_eq!(mock.call("  banana"), "tasty");

mock.use_fn_for("  banana  ", str::trim);
assert_eq!(mock.call("  banana  "), "banana");

mock.use_closure_for("  banana  ", Box::new(|x| x.trim_left()));
assert_eq!(mock.call("  banana  "), "banana  ");

pub fn return_value<T: Into<R>>(&self, value: T)

Override the default return value.

Examples

use double::Mock;

let mock = Mock::<&str, &str>::new("original value");
mock.return_value("new value");

assert_eq!(mock.call("something"), "new value");

pub fn return_values<T: Into<R>>(&self, values: Vec<T>)

Provide a sequence of default return values. The specified are returned in the same order they are specified in values.

Examples

use double::Mock;

let mock = Mock::<&str, &str>::new("default");
mock.return_values(vec!("one", "two"));

assert_eq!(mock.call("hello"), "one");
assert_eq!(mock.call("bye"), "two");
// ran out of values in the sequence, fall back to the default value
assert_eq!(mock.call("farewell"), "default");

pub fn return_value_for<S: Into<C>, T: Into<R>>(&self, args: S, return_value: T)

Override the return value for a specific set of call arguments.

Examples

use double::Mock;

let mock = Mock::<&str, &str>::new("original value");
mock.return_value("new value");
mock.return_value_for("banana", "tasty");

assert_eq!(mock.call("something"), "new value");
assert_eq!(mock.call("banana"), "tasty");

pub fn use_fn(&self, default_fn: fn(_: C) -> R)

Specify a function to determine the Mock's return value based on the arguments provided to Mock::call.

Arguments of Mock::call are still tracked.

Examples

use double::Mock;

fn add_two(x: i64) -> i64 {
    x + 2
}

let mock = Mock::<i64, i64>::new(10);
mock.use_fn(add_two);

assert_eq!(mock.call(1), 3);
assert_eq!(mock.call(10), 12);

For functions with multiple arguments, use a tuple:

use double::Mock;

fn add((x, y, z): (i64, i64, i64)) -> i64 {
    x + y + z
}

let mock = Mock::<(i64, i64, i64), i64>::default();
mock.use_fn(add);

assert_eq!(mock.call((1, 1, 1)), 3);
assert_eq!(mock.call((1, 2, 3,)), 6);

pub fn use_fn_for<T: Into<C>>(&self, args: T, function: fn(_: C) -> R)

Specify a function to determine the Mock's return value based on the arguments provided to Mock::call. This function will only be invoked if the arguments match the specified args.

Arguments of Mock::call are still tracked.

Examples

use double::Mock;

fn add_two(x: i64) -> i64 {
    x + 2
}

let mock = Mock::<i64, i64>::new(10);
mock.return_value(42);
mock.use_fn_for(5, add_two);

assert_eq!(mock.call(1), 42);  // uses default value
assert_eq!(mock.call(5), 7);   // uses function since args match

For functions with multiple arguments, use a tuple:

use double::Mock;

fn add((x, y, z): (i64, i64, i64)) -> i64 {
    x + y + z
}

let mock = Mock::<(i64, i64, i64), i64>::default();
mock.return_value(42);
mock.use_fn_for((1, 2, 3), add);

assert_eq!(mock.call((1, 1, 1)), 42);
assert_eq!(mock.call((1, 2, 3)), 6);

pub fn use_closure(&self, default_fn: Box<dyn Fn(C) -> R>)

Specify a closure to determine the Mock's return value based on the arguments provided to Mock::call.

Arguments of Mock::call are still tracked.

Examples

use double::Mock;

let mock = Mock::<i64, i64>::new(10);
let add_two = |x| x + 2;
mock.use_closure(Box::new(add_two));

assert_eq!(mock.call(1), 3);
assert_eq!(mock.call(10), 12);

For functions with multiple arguments, use a tuple:

use double::Mock;

let mock = Mock::<(i64, i64, i64), i64>::default();
let add = |(x, y, z)| x + y + z;
mock.use_closure(Box::new(add));

assert_eq!(mock.call((1, 1, 1)), 3);
assert_eq!(mock.call((1, 2, 3,)), 6);

pub fn use_closure_for<T: Into<C>>(
    &self,
    args: T,
    function: Box<dyn Fn(C) -> R>
)

Specify a closure to determine the Mock's return value based on the arguments provided to Mock::call. This closure will only be invoked if the arguments match the specified args.

Arguments of Mock::call are still tracked.

Examples

use double::Mock;

let mock = Mock::<i64, i64>::new(10);
let add_two = |x| x + 2;
mock.return_value(42);
mock.use_closure_for(10, Box::new(add_two));

assert_eq!(mock.call(1), 42);
assert_eq!(mock.call(10), 12);

For functions with multiple arguments, use a tuple:

use double::Mock;

let mock = Mock::<(i64, i64, i64), i64>::default();
let add = |(x, y, z)| x + y + z;
mock.return_value(42);
mock.use_closure_for((1, 2, 3), Box::new(add));

assert_eq!(mock.call((1, 1, 1)), 42);
assert_eq!(mock.call((1, 2, 3)), 6);

pub fn called(&self) -> bool

Returns true if Mock::call has been called. use double::Mock;

let mock = Mock::<i64, ()>::default();

assert!(!mock.called());

mock.call(10);

assert!(mock.called());

pub fn num_calls(&self) -> usize

Returns the number of times Mock::call has been called.

Examples

use double::Mock;

let mock = Mock::<i64, i64>::new(0);

assert_eq!(mock.num_calls(), 0);
mock.call(5);
assert_eq!(mock.num_calls(), 1);
mock.call(10);
assert_eq!(mock.num_calls(), 2);

pub fn calls(&self) -> Vec<C>

Returns the arguments to Mock::call in order from first to last.

Examples

use double::Mock;

let mock = Mock::<&str, &str>::new("");

mock.call("first");
mock.call("second");
mock.call("third");

assert_eq!(mock.calls().as_slice(), ["first", "second", "third"]);

pub fn reset_calls(&self)

Reset the call history for the Mock.

Examples

use double::Mock;

let mock = Mock::<&str, &str>::default();

mock.call("first");
mock.call("second");

assert!(mock.called());
assert_eq!(mock.num_calls(), 2);
assert!(mock.called_with("first"));
assert!(mock.called_with("second"));

mock.reset_calls();

assert!(!mock.called());
assert_eq!(mock.num_calls(), 0);
assert!(!mock.called_with("first"));
assert!(!mock.called_with("second"));

impl<C, R> Mock<C, R> where
    C: Clone + Debug + Eq + Hash,
    R: Clone, 

pub fn called_with<T: Into<C>>(&self, args: T) -> bool

Returns true if the specified argument has been used for Mock::call.

Examples

use double::Mock;

let mock = Mock::<&str, ()>::new(());
mock.call("foo");
mock.call("bar");

assert!(mock.called_with("foo"));
assert!(mock.called_with("bar"));
assert!(!mock.called_with("baz"));

pub fn has_calls<T: Into<C>>(&self, calls: Vec<T>) -> bool

Returns true if Mock::call has been called with all of the specified calls. The calls can be made in any order. They don't have to be in the order specified by calls.

Examples

use double::Mock;

let mock = Mock::<&str, ()>::new(());
mock.call("foo");
mock.call("bar");

let expected_calls1 = vec!("foo", "bar");
assert!(mock.has_calls(expected_calls1));
let expected_calls2 = vec!("bar", "foo");
assert!(mock.has_calls(expected_calls2));
let expected_calls3 = vec!("foo");
assert!(mock.has_calls(expected_calls3));
let expected_calls4 = vec!("not_in_calls");
assert!(!mock.has_calls(expected_calls4));
let expected_calls5 = vec!("foo", "not_in_calls");
assert!(!mock.has_calls(expected_calls5));

pub fn has_calls_in_order<T: Into<C>>(&self, calls: Vec<T>) -> bool

Returns true if Mock::call has been called with all of the specified calls. The calls must be made in the order they are specified in the vector.

Examples

use double::Mock;

let mock = Mock::<(i32, i32), ()>::new(());
mock.call((42, 0));
mock.call((42, 1));
mock.call((42, 0));  // called with same args as first call!

assert!(mock.has_calls_in_order(vec!( (42, 0) )));
assert!(mock.has_calls_in_order(vec!( (42, 1) )));
assert!(mock.has_calls_in_order(vec!( (42, 0), (42, 1) )));
assert!(mock.has_calls_in_order(vec!( (42, 1), (42, 0) )));
assert!(mock.has_calls_in_order(vec!( (42, 0), (42, 1), (42, 0) )));
assert!(!mock.has_calls_in_order(vec!( (42, 0), (42, 0), (42, 1) )));
assert!(!mock.has_calls_in_order(vec!( (84, 0) )));
assert!(!mock.has_calls_in_order(vec!( (42, 0), (84, 0) )));

pub fn has_calls_exactly<T: Into<C>>(&self, calls: Vec<T>) -> bool

Returns true if Mock::call has been called with all of the specified calls and it has not been called any other times. The calls can be made in any order. They don't have to be in the order specified by calls.

Examples

use double::Mock;

let mock = Mock::<(i32, i32), ()>::new(());
mock.call((42, 0));
mock.call((42, 1));
mock.call((42, 0));

assert!(!mock.has_calls_exactly(vec!( (42, 0) )));
assert!(!mock.has_calls_exactly(vec!( (42, 1) )));
assert!(!mock.has_calls_exactly(vec!( (84, 0) )));
assert!(!mock.has_calls_exactly(vec!( (42, 0), (42, 1) )));
assert!(!mock.has_calls_exactly(vec!( (42, 1), (42, 0) )));
assert!(mock.has_calls_exactly(vec!( (42, 0), (42, 0), (42, 1) )));
assert!(mock.has_calls_exactly(vec!( (42, 0), (42, 1), (42, 0) )));
assert!(!mock.has_calls_exactly(vec!( (42, 0), (42, 1), (84, 0) )));

pub fn has_calls_exactly_in_order<T: Into<C>>(&self, calls: Vec<T>) -> bool

Returns true if Mock::call has been called with all of the specified calls and it has not been called any other times. The calls must be made in the order they are specified in calls.

Examples

use double::Mock;

let mock = Mock::<&str, ()>::new(());
mock.call("foo");
mock.call("bar");

let expected_calls1 = vec!("foo", "bar");
assert!(mock.has_calls_exactly_in_order(expected_calls1));
let expected_calls2 = vec!("bar", "foo");
assert!(!mock.has_calls_exactly_in_order(expected_calls2));
let expected_calls3 = vec!("foo");
assert!(!mock.has_calls_exactly_in_order(expected_calls3));
let expected_calls4 = vec!("bar");
assert!(!mock.has_calls_exactly_in_order(expected_calls4));

pub fn called_with_pattern(&self, pattern: &dyn Fn(&C) -> bool) -> bool

Returns true if an argument set passed into Mock::call matches the specified pattern.

A pattern is defined a function that receives a tuple containing all of a single call's arguments, checks the values of the arguments and returns true if the args "matched" the pattern and false otherwise. See the double repository's README.md for more information on this.

Examples

use double::Mock;

let mock = Mock::<(i32, i32), ()>::new(());
mock.call((42, 0));
mock.call((42, 1));

let pattern1 = |args: &(i32, i32)| args.0 == 42 && args.1 != 0;
let pattern2 = |args: &(i32, i32)| args.0 == 42 && args.1 == 0;
let pattern3 = |args: &(i32, i32)| args.0 == 84;

assert!(mock.called_with_pattern(&pattern1));
assert!(mock.called_with_pattern(&pattern2));
assert!(!mock.called_with_pattern(&pattern3));

pub fn has_patterns(&self, patterns: Vec<&dyn Fn(&C) -> bool>) -> bool

Returns true if Mock::call has been called with all of the specified patterns. The calls can be made in any order. They don't have to be in the order specified by patterns.

Examples

use double::Mock;

let mock = Mock::<(i32, i32), ()>::new(());
mock.call((42, 0));
mock.call((42, 1));

let pattern1 = |args: &(i32, i32)| args.0 == 42 && args.1 != 0;
let pattern2 = |args: &(i32, i32)| args.0 == 42 && args.1 == 0;
let pattern3 = |args: &(i32, i32)| args.0 == 84;

assert!(mock.has_patterns(vec!(&pattern1)));
assert!(mock.has_patterns(vec!(&pattern2)));
assert!(mock.has_patterns(vec!(&pattern1, &pattern2)));
assert!(mock.has_patterns(vec!(&pattern2, &pattern1)));
assert!(!mock.has_patterns(vec!(&pattern3)));
assert!(!mock.has_patterns(vec!(&pattern1, &pattern3)));

pub fn has_patterns_in_order(&self, patterns: Vec<&dyn Fn(&C) -> bool>) -> bool

Returns true if Mock::call has been called with all of the specified patterns. The patterns must be made in the order they are specified in the input vector.

Examples

use double::Mock;

let mock = Mock::<(i32, i32), ()>::new(());
mock.call((42, 0));
mock.call((42, 1));
mock.call((42, 0));  // called with same args as first call!

let pattern1 = |args: &(i32, i32)| args.0 == 42 && args.1 != 0;
let pattern2 = |args: &(i32, i32)| args.0 == 42 && args.1 == 0;
let pattern3 = |args: &(i32, i32)| args.0 == 84;

assert!(mock.has_patterns_in_order(vec!(&pattern1)));
assert!(mock.has_patterns_in_order(vec!(&pattern2)));
assert!(mock.has_patterns_in_order(vec!(&pattern1, &pattern2)));
assert!(mock.has_patterns_in_order(vec!(&pattern2, &pattern1)));
assert!(mock.has_patterns_in_order(vec!(&pattern2, &pattern1, &pattern2)));
assert!(!mock.has_patterns_in_order(vec!(&pattern1, &pattern2, &pattern1)));
assert!(!mock.has_patterns_in_order(vec!(&pattern1, &pattern1, &pattern2)));
assert!(!mock.has_patterns_in_order(vec!(&pattern2, &pattern2, &pattern1)));
assert!(!mock.has_patterns_in_order(vec!(&pattern3)));
assert!(!mock.has_patterns_in_order(vec!(&pattern1, &pattern3)));

pub fn has_patterns_exactly(&self, patterns: Vec<&dyn Fn(&C) -> bool>) -> bool

Returns true if Mock::call has been called with all of the specified patterns and it has not been called any other times. The calls can be made in any order. They don't have to be in the order specified by patterns.

Examples

use double::Mock;

let mock = Mock::<(i32, i32), ()>::new(());
mock.call((42, 0));
mock.call((42, 1));
mock.call((42, 0));

let pattern1 = |args: &(i32, i32)| args.0 == 42 && args.1 != 0;
let pattern2 = |args: &(i32, i32)| args.0 == 42 && args.1 == 0;
let pattern3 = |args: &(i32, i32)| args.0 == 84;

assert!(!mock.has_patterns_exactly(vec!(&pattern1)));
assert!(!mock.has_patterns_exactly(vec!(&pattern2)));
assert!(!mock.has_patterns_exactly(vec!(&pattern3)));
assert!(!mock.has_patterns_exactly(vec!(&pattern1, &pattern2)));
assert!(!mock.has_patterns_exactly(vec!(&pattern2, &pattern1)));
assert!(mock.has_patterns_exactly(vec!(&pattern1, &pattern1, &pattern2)));
assert!(mock.has_patterns_exactly(vec!(&pattern1, &pattern2, &pattern1)));
assert!(!mock.has_patterns_exactly(vec!(&pattern1, &pattern2, &pattern3)));

pub fn has_patterns_exactly_in_order(
    &self,
    patterns: Vec<&dyn Fn(&C) -> bool>
) -> bool

Returns true if Mock::call has been called with all of the specified patterns and it has not been called any other times. The calls must be made match the patterns in the same order as specified in the patterns vector.

Examples

use double::Mock;

let mock = Mock::<(i32, i32), ()>::new(());
mock.call((42, 0));
mock.call((42, 1));
mock.call((42, 0));  // called with same args as first call!

let pattern1 = |args: &(i32, i32)| args.0 == 42 && args.1 != 0;
let pattern2 = |args: &(i32, i32)| args.0 == 42 && args.1 == 0;
let pattern3 = |args: &(i32, i32)| args.0 == 84;

assert!(!mock.has_patterns_exactly_in_order(vec!(&pattern1)));
assert!(!mock.has_patterns_exactly_in_order(vec!(&pattern2)));
assert!(!mock.has_patterns_exactly_in_order(vec!(&pattern1, &pattern2)));
assert!(!mock.has_patterns_exactly_in_order(vec!(&pattern2, &pattern1)));
assert!(mock.has_patterns_exactly_in_order(vec!(&pattern2, &pattern1, &pattern2)));
assert!(!mock.has_patterns_exactly_in_order(vec!(&pattern1, &pattern2, &pattern1)));
assert!(!mock.has_patterns_exactly_in_order(vec!(&pattern1, &pattern1, &pattern2)));
assert!(!mock.has_patterns_exactly_in_order(vec!(&pattern2, &pattern2, &pattern1)));
assert!(!mock.has_patterns_exactly_in_order(vec!(&pattern3)));
assert!(!mock.has_patterns_exactly_in_order(vec!(&pattern1, &pattern3)));

impl<C, S> Mock<C, Option<S>> where
    C: Clone + Eq + Hash,
    S: Clone, 

pub fn return_some<T: Into<S>>(&self, return_value: T)

Return Some(return_value) from Mock::call.

Examples

use double::Mock;

let mock = Mock::<(), Option<i64>>::new(None);
mock.return_some(10);

assert_eq!(mock.call(()), Some(10));

pub fn return_none(&self)

Return None from Mock::call.

Examples

use double::Mock;

let mock = Mock::<(), Option<i64>>::new(Some(42));
mock.return_none();

assert_eq!(mock.call(()), None);

impl<C, O, E> Mock<C, Result<O, E>> where
    C: Clone + Eq + Hash,
    O: Clone,
    E: Clone, 

pub fn return_ok<T: Into<O>>(&self, return_value: T)

Return Ok(return_value) from Mock::call.

Examples

use double::Mock;

let mock = Mock::<(), Result<&str, &str>>::new(Err("oh no"));
mock.return_ok("success");

assert_eq!(mock.call(()), Ok("success"));

pub fn return_err<T: Into<E>>(&self, return_value: T)

Return Err(return_value) from Mock::call.

Examples

use double::Mock;

let mock = Mock::<(), Result<&str, &str>>::new(Ok("success"));
mock.return_err("oh no");

assert_eq!(mock.call(()), Err("oh no"));

Trait Implementations

impl<C: Clone, R: Clone> Clone for Mock<C, R> where
    C: Clone + Eq + Hash,
    R: Clone, 

fn clone(&self) -> Mock<C, R>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<C, R> Default for Mock<C, R> where
    C: Clone + Eq + Hash,
    R: Clone + Default, 

fn default() -> Self

Use R::default() as the initial return value.

Examples

use double::Mock;

let mock = Mock::<i64, i64>::default();
assert_eq!(mock.call(10), 0);

let mock = Mock::<(), String>::default();
assert_eq!(&mock.call(()), "");

let mock = Mock::<(i64, &str), Option<bool>>::default();
assert_eq!(mock.call((10, "test")), None);

impl<C, R> Debug for Mock<C, R> where
    C: Clone + Debug + Eq + Hash,
    R: Clone + Debug, 

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.