Synopsis :

MOCK_CLASS( name )            // defines a class
MOCK_BASE_CLASS( name, base ) // defines a class deriving from a base class

The preferred form for defining a mock class is with using MOCK_CLASS and MOCK_BASE_CLASS, however using a regular struct or class is also perfectly fine.

Example :

MOCK_CLASS(mock_class)
{};

BOOST_AUTO_TEST_CASE(demonstrates_instantiating_a_mock_class)
{
    mock_class c;
}

Example :

template<typename T>
MOCK_CLASS(mock_class)
{};

BOOST_AUTO_TEST_CASE(demonstrates_instantiating_a_template_mock_class)
{
    mock_class<int> c;
}

Example :

struct base_class
{};

MOCK_BASE_CLASS(mock_class, base_class)
{};

BOOST_AUTO_TEST_CASE(demonstrates_instantiating_a_derived_mock_class)
{
    mock_class c;
}

Example :

template<typename T>
struct base_class
{};

template<typename T>
MOCK_BASE_CLASS(mock_class, base_class<T>)
{};

BOOST_AUTO_TEST_CASE(demonstrates_instantiating_a_template_derived_mock_class)
{
    mock_class<int> c;
}

Example :

struct name : mock::object // equivalent to using MOCK_CLASS
{};

Example :

template<typename T>
struct name : mock::object // equivalent to using MOCK_CLASS
{};

Example :

class base
{};

struct name : base, mock::object // equivalent to using MOCK_BASE_CLASS
{
    // this is required for the shortest form of MOCK_METHOD to work when not using MOCK_BASE_CLASS
    using base_type = base;
};

Example :

template<typename T>
struct base
{};

template<typename T>
struct name : base<T>, mock::object
{
    using base_type = base<T>;
};

Deriving from mock::object is optional but provides the additional following benefits :

Synopsis :

MOCK_METHOD( [calling convention] name, arity[, signature[, identifier]] )             // generates both const and non-const methods
MOCK_CONST_METHOD( [calling convention] name, arity[, signature[, identifier]] )       // generates only the const version of the method
MOCK_NON_CONST_METHOD( [calling convention] name, arity[, signature[, identifier]] )   // generates only the non-const version of the method

Synopsis :

MOCK_METHOD( [calling convention] name, arity, signature, identifier )               // generates both const and non-const methods
MOCK_CONST_METHOD( [calling convention] name, arity, signature, identifier )         // generates only the const version of the method
MOCK_NON_CONST_METHOD( [calling convention] name, arity, signature, identifier )     // generates only the non-const version of the method

Example :

struct base_class
{
    virtual ~base_class() = default;
    virtual void method(int) = 0;
};

MOCK_BASE_CLASS(mock_class, base_class)
{
    MOCK_METHOD(method, 1) // only possible when referring unambiguously to a base class method
};

Example :

struct base_class
{
    virtual ~base_class() = default;
    virtual void method(int, const std::string&) = 0;
    virtual void method(float) = 0;
};

MOCK_BASE_CLASS(mock_class, base_class)
{
    // both the signature and identifier must be specified because of ambiguity due to overloading
    MOCK_METHOD(method, 2, void(int, const std::string&), identifier_1)
    // the identifier must differ from the previous one in order to fully disambiguate methods
    MOCK_METHOD(method, 1, void(float), identifier_2)
};

Example :

struct base_class
{
    virtual ~base_class() = default;
    virtual void method(float) = 0;
    virtual void method(float) const = 0;
};

MOCK_BASE_CLASS(mock_class, base_class)
{
    MOCK_METHOD(method, 1, void(float)) // this generates both const and non-const versions
};

Example :

struct base_class
{
    virtual ~base_class() = default;
    virtual void method(float) = 0;
    virtual void method(float) const = 0;
};

MOCK_BASE_CLASS(mock_class, base_class)
{
    // this generates only the const version
    MOCK_CONST_METHOD(method, 1, void(float), identifier_1)
    // this generates only the non-const version, with a different identifier
    MOCK_NON_CONST_METHOD(method, 1, void(float), identifier_2)
};

Example :

MOCK_CLASS(mock_class)
{
    MOCK_NON_CONST_METHOD(operator=,
                          1,
                          mock_class &(const mock_class&),
                          assignment) // operators require a custom identifier
};

Example :

template<typename T>
MOCK_CLASS(mock_class)
{
    // includes a template parameter of the class
    MOCK_METHOD(method, 1, void(const T&))
};

Example :

MOCK_CLASS(mock_class)
{
    // the signature must be wrapped in MOCK_PROTECT_SIGNATURE if the return type contains a comma
    MOCK_METHOD(method, 0, MOCK_PROTECT_SIGNATURE(std::map<int, int>()))
};

Example for msvc :

MOCK_CLASS(mock_class)
{
    // all parameters must be provided when specifying a different calling convention
    MOCK_METHOD(__stdcall method, 0, void(), method)
};

Example for gcc :

[member_function_example_10]

Synopsis :

MOCK_STATIC_METHOD( [calling convention] name, arity, signature[, identifier] )     // if 'identifier' is omitted it will default to 'name'

Example :

MOCK_CLASS(mock_class)
{
    MOCK_STATIC_METHOD(method, 1, float(int))
};

Example :

template<typename T>
MOCK_CLASS(mock_class)
{
    MOCK_STATIC_METHOD(method, 1, void(T)) // includes a template parameter of the class
};

Example for msvc :

MOCK_CLASS(mock_class)
{
    // all parameters must be provided when specifying a different calling convention
    MOCK_STATIC_METHOD(__stdcall method, 0, void(), method)
};

Example for gcc :

[static_member_function_example_4]

Synopsis :

MOCK_CONSTRUCTOR( [calling convention] name, arity, parameters, identifier )

Example :

MOCK_CLASS(mock_class)
{
    MOCK_CONSTRUCTOR(mock_class, 2, (int, const std::string&), identifier)
};

Example :

template<typename T>
MOCK_CLASS(mock_class)
{
    MOCK_CONSTRUCTOR(mock_class, 2, (int, const std::string&), identifier)
    MOCK_CONSTRUCTOR(mock_class, 2, (T, const std::string&), identifier_2) // includes a template parameter of the class
};

Example for msvc :

MOCK_CLASS(mock_class)
{
    MOCK_CONSTRUCTOR(__stdcall mock_class, 0, (), constructor)
};

Example for gcc :

[constructor_example_4]

Synopsis :

MOCK_DESTRUCTOR( [calling convention] ~name, identifier )

Example :

MOCK_CLASS(mock_class)
{
    MOCK_DESTRUCTOR(~mock_class, destructor)
};

Example for msvc :

MOCK_CLASS(mock_class)
{
    MOCK_DESTRUCTOR(__stdcall ~mock_class, destructor)
};

Example for gcc :

[destructor_example_3]

Synopsis :

MOCK_CONVERSION_OPERATOR( [calling convention] name, type, identifier )               // generates both const and non-const operators
MOCK_CONST_CONVERSION_OPERATOR( [calling convention] name, type, identifier )         // generates only a const operator
MOCK_NON_CONST_CONVERSION_OPERATOR( [calling convention] name, type, identifier )     // generates only a non-const operator

Example :

MOCK_CLASS(mock_class)
{
    MOCK_CONVERSION_OPERATOR(operator, int, conversion_to_int)
    MOCK_CONST_CONVERSION_OPERATOR(operator, const std::string&, conversion_to_string)
};

Example :

template<typename T>
MOCK_CLASS(mock_class)
{
    MOCK_CONVERSION_OPERATOR(operator, T, conversion_to_T) // includes a template parameter of the class
    MOCK_CONST_CONVERSION_OPERATOR(operator, const std::string&, const_conversion_to_string)
    MOCK_NON_CONST_CONVERSION_OPERATOR(operator, const std::string&, non_const_conversion_to_string)
};

Example for msvc :

MOCK_CLASS(mock_class)
{
    MOCK_CONVERSION_OPERATOR(__stdcall operator, int, conversion_to_int)
};

Example for gcc :

[conversion_operator_example_4]

Synopsis :

MOCK_FUNCTION( [calling convention] name, arity, signature[, identifier] ) // if 'identifier' is omitted it will default to 'name'

Example :

MOCK_FUNCTION(f, 1, void(int))

BOOST_AUTO_TEST_CASE(demonstrates_instantiating_a_mock_function)
{
    MOCK_EXPECT(f).once().with(3);
    f(3);
}

Example for msvc :

// all parameters must be provided when specifying a different calling convention
MOCK_FUNCTION(__stdcall f, 0, void(), f)

Example for gcc :

[function_example_3]

Synopsis :

MOCK_FUNCTOR( [calling convention] name, signature );

Example :

BOOST_AUTO_TEST_CASE(demonstrates_instantiating_a_mock_functor)
{
    MOCK_FUNCTOR(f, void(int));
    MOCK_EXPECT(f).once().with(3);
    f(3);
}

Example :

template<typename T>
struct mock_class
{
    MOCK_FUNCTOR(f, void(T));
};

BOOST_AUTO_TEST_CASE(demonstrates_instantiating_a_mock_functor_inside_a_class)
{
    mock_class<int> c;
    MOCK_EXPECT(c.f).once().with(3);
    c.f(3);
}

MOCK_EXPECT( identifier ).invocation( arguments ).with( constraints ).in( sequences ).action( value );

MOCK_CLASS(mock_class)
{
    MOCK_METHOD(method, 1, int(int), method)
    MOCK_METHOD(method, 2, void(const std::string&, float), method2)
};

BOOST_AUTO_TEST_CASE(demonstrates_configuring_mock_objects)
{
    mock_class c;
    mock::sequence s;
    MOCK_EXPECT(c.method).once().with(0).in(s).returns(42);
    MOCK_EXPECT(c.method2).never().with("ok", mock::any);
    MOCK_EXPECT(c.method2).at_least(2).in(s).throws(std::runtime_error("error !"));
    BOOST_TEST(c.method(0) == 42);
    BOOST_CHECK_THROW(c.method("not ok", 1.f), std::runtime_error);
    BOOST_CHECK_THROW(c.method("not ok", 2.f), std::runtime_error);
}

An invocation defines how many times a mock object is to be exercised.

Synopsis :

MOCK_EXPECT( identifier );                     // any number of times including never
MOCK_EXPECT( identifier ).once();
MOCK_EXPECT( identifier ).never();
MOCK_EXPECT( identifier ).exactly( count );
MOCK_EXPECT( identifier ).at_least( min );
MOCK_EXPECT( identifier ).at_most( max );
MOCK_EXPECT( identifier ).between( min, max ); // throws std::invalid_argument if 'min' > 'max'

Example :

MOCK_CLASS(mock_class)
{
    MOCK_METHOD(method, 2, void(int, const std::string&))
    MOCK_METHOD(method2, 1, void(int))
};

BOOST_AUTO_TEST_CASE(demonstrates_setting_up_invocations_on_a_mock_method)
{
    mock_class c;
    MOCK_EXPECT(c.method).once(); // can only be called once
    MOCK_EXPECT(c.method2);       // can be called an unlimited number of times
    c.method(42, "Hello world!");
    c.method2(42);
    c.method2(42);
    c.method2(42);
}

Example :

BOOST_AUTO_TEST_CASE(demonstrates_setting_up_an_invocation_on_a_mock_functor)
{
    MOCK_FUNCTOR(f, void(int, const std::string&));
    MOCK_EXPECT(f).once();
    f(42, "Hello world!");
}

Example :

MOCK_FUNCTION(f, 1, void(int))

BOOST_AUTO_TEST_CASE(demonstrates_setting_up_an_invocation_on_a_mock_function)
{
    MOCK_EXPECT(f).once();
    f(42);
}

Example :

MOCK_CLASS(mock_class)
{
    MOCK_STATIC_METHOD(method1, 1, void(int))
    MOCK_STATIC_METHOD(method2, 1, void(int))
};

BOOST_AUTO_TEST_CASE(demonstrates_setting_up_an_invocation_on_a_mock_static_method)
{
    mock_class c;
    MOCK_EXPECT(c.method1).once();
    MOCK_EXPECT(mock_class::method2).once(); // does the same (but for the other method)
    c.method1(42);
    c.method2(42);
}

Constraints validate the actual parameter values of a call to a mock object.

Synopsis :

MOCK_EXPECT( identifier ).with( constraint );                      // one constraint for all parameters
MOCK_EXPECT( identifier ).with( constraint_1, constraint_2, ... ); // one constraint for each parameter

In the following table 'expected' denotes a user supplied data whereas 'actual' stands for the one or several parameter values received in a call to a mock function.

Constraints :

Example :

MOCK_CLASS(mock_class)
{
    MOCK_METHOD(method1, 2, void(int, const std::string&))
    MOCK_METHOD(method2, 2, void(int, const std::string&))
};

BOOST_AUTO_TEST_CASE(demonstrates_adding_builtin_constraints)
{
    mock_class c;
    MOCK_EXPECT(c.method1).with(mock::equal(3), mock::equal("some string"));
    MOCK_EXPECT(c.method2).with(3, "some string"); // similar to the previous one using short-cuts
    c.method1(3, "some string");
    c.method2(3, "some string");
}

Example using a function pointer :

MOCK_CLASS(mock_class)
{
    MOCK_METHOD(method, 1, void(int))
};

bool custom_constraint(int actual)
{
    return actual == 42;
}

BOOST_AUTO_TEST_CASE(demonstrates_adding_a_custom_constraint_with_a_free_function)
{
    mock_class c;
    MOCK_EXPECT(c.method).with(&custom_constraint);
    c.method(42);
}

Example using a standard library functor :

MOCK_CLASS(mock_class)
{
    MOCK_METHOD(method, 1, void(int))
};

bool custom_constraint(int expected, int actual)
{
    return expected == actual;
}

BOOST_AUTO_TEST_CASE(demonstrates_adding_a_custom_constraint_with_a_standard_library_functor)
{
    mock_class c;
    MOCK_EXPECT(c.method).with(
      std::bind1st(std::ptr_fun(&custom_constraint), 42)); // std::ptr_fun creates an std::unary_function
    c.method(42);
}

Example using std::bind :

MOCK_CLASS(mock_class)
{
    MOCK_METHOD(method, 1, void(int))
};

bool custom_constraint(int expected, int actual)
{
    return expected == actual;
}

BOOST_AUTO_TEST_CASE(demonstrates_adding_a_custom_constraint_with_std_bind)
{
    mock_class c;
    using namespace std::placeholders;
    MOCK_EXPECT(c.method).with(std::bind(&custom_constraint, 42, _1));
    c.method(42);
}

Example using Boost.Lambda :

MOCK_CLASS(mock_class)
{
    MOCK_METHOD(method, 1, void(int))
};

BOOST_AUTO_TEST_CASE(demonstrates_adding_a_custom_constraint_with_boost_lambda)
{
    mock_class c;
    MOCK_EXPECT(c.method).with(boost::lambda::_1 == 42);
    c.method(42);
}

Example using Boost.Phoenix :

MOCK_CLASS(mock_class)
{
    MOCK_METHOD(method1, 1, void(int))
    MOCK_METHOD(method2, 1, void(int))
};

BOOST_AUTO_TEST_CASE(demonstrates_adding_a_custom_constraint_with_boost_phoenix)
{
    mock_class c;
    MOCK_EXPECT(c.method1).with(boost::phoenix::arg_names::arg1 == 42);
    MOCK_EXPECT(c.method2).with(boost::phoenix::arg_names::_1 == 42);
    c.method1(42);
    c.method2(42);
}

Example using C++11 lambdas :

MOCK_CLASS(mock_class)
{
    MOCK_METHOD(method, 1, void(int))
};

BOOST_AUTO_TEST_CASE(demonstrates_adding_a_constraint_with_cxx11_lambda)
{
    mock_class c;
    MOCK_EXPECT(c.method).with([](int actual) { return 42 == actual; });
    c.method(42);
}

Example using &&, || and ! :

MOCK_CLASS(mock_class)
{
    MOCK_METHOD(method, 2, void(int, const std::string&))
};

BOOST_AUTO_TEST_CASE(demonstrates_combining_constraints)
{
    mock_class c;
    MOCK_EXPECT(c.method).with(mock::less(4) && mock::greater(2), !mock::equal(""));
    c.method(3, "Hello World!");
}

Example using one constraint for all parameters :

MOCK_CLASS(mock_class)
{
    MOCK_METHOD(method, 2, void(const std::string&, std::size_t))
};

bool custom_constraint(const std::string& actual_1, std::size_t actual_2)
{
    return actual_1.size() <= actual_2;
}

BOOST_AUTO_TEST_CASE(demonstrates_one_constraint_for_all_arguments)
{
    mock_class c;
    MOCK_EXPECT(c.method).with(&custom_constraint);
    c.method("1234", 4);
}

A sequence enforces a given order between two or more expectations.

Synopsis :

MOCK_EXPECT( identifier_1 ).in( sequence_1, sequence_2, ... );

Each sequence is an instance of mock::sequence.

The maximum number of sequences that can be set is basically unlimited.

Example :

MOCK_CLASS(mock_class_1)
{
    MOCK_METHOD(method_1, 0, void())
};

MOCK_CLASS(mock_class_2)
{
    MOCK_METHOD(method_2, 0, void())
};

MOCK_CLASS(mock_class_3)
{
    MOCK_METHOD(method_3, 0, void())
};

BOOST_AUTO_TEST_CASE(demonstrates_enforcing_several_expectation_orders)
{
    mock_class_1 c_1;
    mock_class_2 c_2;
    mock_class_3 c_3;
    mock::sequence s_1, s_2;
    MOCK_EXPECT(c_1.method_1).in(s_1);
    MOCK_EXPECT(c_2.method_2)
      .in(s_2); // c_1.method_1 and c_2.method_2 are in different sequences and can be called in any order
    MOCK_EXPECT(c_3.method_3).in(s_1, s_2); // c_3.method_3 must be called after both c_1.method_1 and c_2.method_2
    c_2.method_2();
    c_1.method_1();
    c_3.method_3();
}

An action performs additional treatments after an expectation has been deemed valid.

Synopsis :

MOCK_EXPECT( identifier ).returns( value );    // stored internally by copy
MOCK_EXPECT( identifier ).moves( value );      // stored internally by copy/move
MOCK_EXPECT( identifier ).throws( exception ); // stored internally by copy
MOCK_EXPECT( identifier ).calls( functor );    // stored internally by copy, throws std::invalid_argument if empty

Example :

MOCK_CLASS(mock_class)
{
    MOCK_METHOD(method, 1, int(int))
};

int function(int i)
{
    return i;
}

BOOST_AUTO_TEST_CASE(demonstrates_configuring_actions)
{
    mock_class c;
    MOCK_EXPECT(c.method).once().returns(42);
    MOCK_EXPECT(c.method).once().moves(42); // returns by moving the value
    MOCK_EXPECT(c.method).once().throws(std::runtime_error("error !"));
    MOCK_EXPECT(c.method).once().calls(&function); // forwards 'method' parameter to 'function'
    MOCK_EXPECT(c.method).once().calls(
      std::bind(&function, 42)); // drops 'method' parameter and binds 42 as parameter to 'function'
    MOCK_EXPECT(c.method).once().calls([](int i) { return i; }); // uses a C++11 lambda
    BOOST_TEST(c.method(0) == 42);
    BOOST_TEST(c.method(1) == 42);
    BOOST_CHECK_THROW(c.method(0), std::runtime_error);
    BOOST_TEST(c.method(2) == 2);
    BOOST_TEST(c.method(3) == 42);
    BOOST_TEST(c.method(4) == 4);
}

Example with references :

MOCK_CLASS(mock_class)
{
    MOCK_METHOD(method, 0, int&())
};

BOOST_AUTO_TEST_CASE(demonstrates_configuring_actions_with_references)
{
    mock_class c;
    int i = 0;
    MOCK_EXPECT(c.method).returns(std::ref(i)); // wrap i to store a reference
    c.method() = 42;                            // really change i and not just the stored copy
    BOOST_CHECK_EQUAL(42, i);                   // indeed
}