1# Mockall
2
3A powerful mock object library for Rust.
4
5[![Build Status](https://api.cirrus-ci.com/github/asomers/mockall.svg)](https://cirrus-ci.com/github/asomers/mockall)
6[![Crates.io](https://img.shields.io/crates/v/mockall.svg)](https://crates.io/crates/mockall)
7[![Documentation](https://docs.rs/mockall/badge.svg)](https://docs.rs/mockall)
8
9## Overview
10
11Mock objects are a powerful technique for unit testing software.  A mock object
12is an object with the same interface as a real object, but whose responses are
13all manually controlled by test code.  They can be used to test the upper and
14middle layers of an application without instantiating the lower ones, or to
15inject edge and error cases that would be difficult or impossible to create
16when using the full stack.
17
18Statically typed languages are inherently more difficult to
19mock than dynamically typed languages. Since Rust is a statically typed language,
20previous attempts at creating a mock object library have had mixed results. Mockall
21incorporates the best elements of previous designs, resulting in it having a rich
22feature set with a terse and ergonomic interface. Mockall is written in 100% *safe*
23and *stable* Rust.
24
25## Usage
26
27Typically mockall is only used by unit tests.  To use it this way, add this to
28your `Cargo.toml`:
29
30```toml
31[dev-dependencies]
32mockall = "0.12.1"
33```
34
35Then use it like this:
36
37```rust
38#[cfg(test)]
39use mockall::{automock, mock, predicate::*};
40#[cfg_attr(test, automock)]
41trait MyTrait {
42    fn foo(&self, x: u32) -> u32;
43}
44
45#[cfg(test)]
46mod tests {
47    use super::*;
48
49    #[test]
50    fn mytest() {
51        let mut mock = MockMyTrait::new();
52        mock.expect_foo()
53            .with(eq(4))
54            .times(1)
55            .returning(|x| x + 1);
56        assert_eq!(5, mock.foo(4));
57    }
58}
59```
60
61See the [API docs](https://docs.rs/mockall) for more information.
62
63# Minimum Supported Rust Version (MSRV)
64
65Mockall is supported on Rust 1.64.0 and higher.  Mockall's MSRV will not be
66changed in the future without bumping the major or minor version.
67
68# License
69
70`mockall` is primarily distributed under the terms of both the MIT license
71and the Apache License (Version 2.0).
72
73See LICENSE-APACHE, and LICENSE-MIT for details
74
75# Acknowledgements
76
77Mockall was not built in a day.  JMock was probably the first popular mock
78object library.  Many ports and imitations have been made, including GoogleMock
79for C++.  Mockers, inspired by GoogleMock, was the first attempt to bring the
80concept to Rust.  The now-defunct Mock_derive was the first library to generate
81mock objects with procedural macros, greatly reducing the user's workload.
82Mockall also uses proc macros, and copies many of Mockers' features and
83conventions.  Mockall also takes inspiration from Simulacrum's internal design,
84and its technique for mocking generic methods.
85