Download | News | Support | Project |
This section describes the library syntax exhaustively.
All source code snippets assume the following prerequisite :
#define BOOST_AUTO_TEST_MAIN #include <boost/test/auto_unit_test.hpp> #include <turtle/mock.hpp>
Mock objects can be assigned and copied around freely, unless they derive from a type which disables it.
Copies of a mock object share the same internal state, meaning setting an expectation on one of them will impact all of them. Thus it is possible to let an object under test copy a mock object and still be able to set, verify or reset expectations.
The library defines a set of convenient macros for creating mock objects of different kinds :
Creating a mock object involves two parts under the hood :
Most of the time the identifier will be identical to the object name, but in case of ambiguity (for instance overloaded methods) a different identifier will have to be specified.
Warning | |
---|---|
Creating a mock object creates a new object and does not magically replace existing ones, for instance creating a mock function will not replace an already existing function with the same name and signature. |
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 { typedef base base_type; // this is required for the shortest form of MOCK_METHOD to work when not using MOCK_BASE_CLASS };
Example :
template< typename T > struct base {}; template< typename T > struct name : base< T >, mock::object { typedef base< T > base_type; };
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 MOCK_METHOD_TPL( [calling convention] name, arity, signature[, identifier] ) // must be used if the signature uses a template parameter of the class, generates both const and non-const methods MOCK_CONST_METHOD_TPL( [calling convention] name, arity, signature[, identifier] ) // must be used if the signature uses a template parameter of the class, generates only the const version of the method MOCK_NON_CONST_METHOD_TPL( [calling convention] name, arity, signature[, identifier] ) // must be used if the signature uses a template parameter of the class, generates only the non-const version of the method
Note | |
---|---|
If the identifier is omitted it will default to the method name. |
Note | |
---|---|
If the method name is not ambiguous both the signature and the identifier can be omitted in the context of a derived MOCK_BASE_CLASS or base_type typedef. |
Note | |
---|---|
The signature cannot be omitted for the _TPL familly of macros, see the related limitation section. |
Note | |
---|---|
Constructors, destructors and conversion operators require special care. |
Note | |
---|---|
In case of a calling convention specified, all four parameters must be provided. |
Warning | |
---|---|
For compilers without support for variadic macros the MOCK_METHOD_EXT familly set of macros must be used. |
Synopsis :
MOCK_METHOD_EXT( [calling convention] name, arity, signature, identifier ) // generates both const and non-const methods MOCK_CONST_METHOD_EXT( [calling convention] name, arity, signature, identifier ) // generates only the const version of the method MOCK_NON_CONST_METHOD_EXT( [calling convention] name, arity, signature, identifier ) // generates only the non-const version of the method MOCK_METHOD_EXT_TPL( [calling convention] name, arity, signature, identifier ) // must be used if the signature uses a template parameter of the class, generates both const and non-const methods MOCK_CONST_METHOD_EXT_TPL( [calling convention] name, arity, signature, identifier ) // must be used if the signature uses a template parameter of the class, generates only the const version of the method MOCK_NON_CONST_METHOD_EXT_TPL( [calling convention] name, arity, signature, identifier ) // must be used if the signature uses a template parameter of the class, generates only the non-const version of the method
Example :
struct base_class { virtual ~base_class() {} 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() {} virtual void method( int, const std::string& ) = 0; virtual void method( float ) = 0; }; MOCK_BASE_CLASS( mock_class, base_class ) { MOCK_METHOD( method, 2, void( int, const std::string& ), identifier_1 ) // both the signature and identifier must be specified because of ambiguity due to overloading MOCK_METHOD( method, 1, void( float ), identifier_2 ) // the identifier must differ from the previous one in order to fully disambiguate methods };
Example :
struct base_class { virtual ~base_class() {} 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() {} virtual void method( float ) = 0; virtual void method( float ) const = 0; }; MOCK_BASE_CLASS( mock_class, base_class ) { MOCK_CONST_METHOD( method, 1, void( float ), identifier_1 ) // this generates only the const version MOCK_NON_CONST_METHOD( method, 1, void( float ), identifier_2 ) // this generates only the non-const version, with a different identifier };
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 ) { MOCK_METHOD_TPL( method, 1, void( const T& ) ) // the _TPL variants must be used if the signature includes a template parameter of the class };
Example :
MOCK_CLASS( mock_class ) { MOCK_METHOD( method, 0, BOOST_IDENTITY_TYPE((std::map< int, int >())) ) // the signature must be wrapped in BOOST_IDENTITY_TYPE if the return type contains a comma };
Example for msvc :
MOCK_CLASS( mock_class ) { MOCK_METHOD( __stdcall method, 0, void(), method ) // all parameters must be provided when specifying a different calling convention };
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' MOCK_STATIC_METHOD_TPL( [calling convention] name, arity, signature[, identifier] ) // must be used if the signature uses a template parameter of the class, if 'identifier' is omitted it will default to 'name'
Note | |
---|---|
A static object is used behind the scene in order to keep track of the expectations of a mock static method, therefore to ensure all tests run in isolation it is strongly suggested to manually verify and reset the static method at the end of each test, see the related pattern section. |
Note | |
---|---|
In case of a calling convention specified, all four parameters must be provided. |
Warning | |
---|---|
For compilers without support for variadic macros the identifier cannot be omitted and must be given explicitly. |
Example :
MOCK_CLASS( mock_class ) { MOCK_STATIC_METHOD( method, 1, float( int ) ) };
Example :
template< typename T > MOCK_CLASS( mock_class ) { MOCK_STATIC_METHOD_TPL( method, 1, void( T ) ) };
Example for msvc :
MOCK_CLASS( mock_class ) { MOCK_STATIC_METHOD( __stdcall method, 0, void(), method ) // all parameters must be provided when specifying a different calling convention };
Example for gcc :
[static_member_function_example_4]
Synopsis :
MOCK_CONSTRUCTOR( [calling convention] name, arity, parameters, identifier ) MOCK_CONSTRUCTOR_TPL( [calling convention] name, arity, parameters, identifier ) // must be used if the signature uses a template parameter of the class
Note | |
---|---|
As constructors do not have a return type, the usual signature gets restricted here to just the parameters. |
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_TPL( mock_class, 2, ( T, const std::string& ), identifier_2 ) };
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 )
Note | |
---|---|
When mocking a destructor it is strongly suggested to manually verify the expectation at the end of the test, because the automatic verification will not be triggered if the mock object is not destroyed. |
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 MOCK_CONVERSION_OPERATOR_TPL( [calling convention] name, type, identifier ) // must be used if the signature uses a template parameter of the class MOCK_CONST_CONVERSION_OPERATOR_TPL( [calling convention] name, type, identifier ) // must be used if the signature uses a template parameter of the class MOCK_NON_CONST_CONVERSION_OPERATOR_TPL( [calling convention] name, type, identifier ) // must be used if the signature uses a template parameter of the class
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_TPL( operator, T, conversion_to_T ) // the _TPL variants must be used if the signature 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'
Note | |
---|---|
A static object is used behind the scene in order to keep track of the expectations of a mock function, therefore to ensure all tests run in isolation it is strongly suggested to manually verify and reset the mock function at the end of each test, see the related pattern section. |
Note | |
---|---|
In case of a calling convention specified, all four parameters must be provided. |
Warning | |
---|---|
For compilers without support for variadic macros the identifier cannot be omitted and must be given explicitly. |
Example :
MOCK_FUNCTION( f, 1, float( int ) ) BOOST_AUTO_TEST_CASE( demonstrates_instantiating_a_mock_function ) { f( 3 ); }
Example for msvc :
MOCK_FUNCTION( __stdcall f, 0, void(), f ) // all parameters must be provided when specifying a different calling convention
Example for gcc :
[function_example_3]
Synopsis :
MOCK_FUNCTOR( [calling convention] name, signature ); MOCK_FUNCTOR_TPL( [calling convention] name, signature ); // must be used if the signature uses a template parameter
Example :
BOOST_AUTO_TEST_CASE( demonstrates_instantiating_a_mock_functor ) { MOCK_FUNCTOR( f, void( int ) ); f( 3 ); }
Example :
template< typename T > struct mock_class { MOCK_FUNCTOR_TPL( f, void( T ) ); }; BOOST_AUTO_TEST_CASE( demonstrates_instantiating_a_mock_functor ) { mock_class< int > c; c.f( 3 ); }
An expectation is a statement of configuration for a mock object.
Synopsis :
MOCK_EXPECT( identifier ).invocation( arguments ).with( constraints ).in( sequences ).action( value );
Note | |
---|---|
The identifier refers to the one specified when creating a mock object. |
Example :
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 !" ) ); }
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& ) ) }; 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.method ); // can be called an unlimited number of times }
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(); }
Example :
MOCK_FUNCTION( f, 1, void( int ) ) BOOST_AUTO_TEST_CASE( demonstrates_setting_up_an_invocation_on_a_mock_function ) { MOCK_EXPECT( f ).once(); }
Example :
MOCK_CLASS( mock_class ) { MOCK_STATIC_METHOD( method, 1, void( int ) ) }; BOOST_AUTO_TEST_CASE( demonstrates_setting_up_an_invocation_on_a_mock_static_method ) { mock_class c; MOCK_EXPECT( c.method ).once(); MOCK_EXPECT( mock_class::method ).once(); // does the same }
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 :
Constraint |
Effect |
Description |
---|---|---|
mock::any |
true |
does not perform any verification |
expected |
expected( actual ) expected( actual_1, actual_2, ... ) actual == expected |
calls expected as a functor returning a bool, throws std::invalid_argument if ! expected calls expected as a functor returning a bool, throws std::invalid_argument if ! expected compares actual to expected using operator == |
mock::equal( expected ) |
actual == expected actual && *actual == expected |
compares actual to expected using operator == compares actual content to expected using operator == |
mock::less( expected ) |
actual < expected |
compares actual to expected using operator < |
mock::greater( expected ) |
actual > expected |
compares actual to expected using operator > |
mock::less_equal( expected ) |
actual <= expected |
compares actual to expected using operator <= |
mock::greater_equal( expected ) |
actual >= expected |
compares actual to expected using operator >= |
mock::near( expected, tolerance ) |
std::abs( actual - expected ) < tolerance |
checks whether actual is near expected within tolerance |
mock::close( expected, tolerance ) |
boost::test_tools::check_is_close( actual, expected, boost::test_tools::percent_tolerance( arg ) ) |
checks whether actual is close to expected, see Floating-point comparison algorithms |
mock::close_fraction( expected, tolerance ) |
boost::test_tools::check_is_close( actual, expected, boost::test_tools::fraction_tolerance( arg ) ) |
checks whether actual is close to expected, see Floating-point comparison algorithms |
mock::small( tolerance ) |
boost::test_tools::check_is_small( actual, expected ) ) |
checks whether actual is small within tolerance, see Floating-point comparison algorithms |
mock::call( expected ) |
expected( actual ) |
calls expected as a functor returning a bool and accepting actual as parameter |
mock::same( expected ) |
&actual == &expected |
compares actual to expected by comparing their pointers |
mock::assign( expected ) |
actual = expected, true *actual = expected, true |
assigns expected to actual using operator = assigns expected to actual content using operator = |
mock::retrieve( expected ) |
expected = actual, true expected = &actual, true |
retrieves actual into expected using operator = retrieves actual address into expected using operator = |
mock::contain( expected ) |
actual.find( expected ) != std::string::npos |
checks whether expected is contained in the std::string actual |
mock::affirm |
actual |
uses actual as a bool |
mock::negate |
! actual |
negates actual using operator ! |
mock::evaluate |
actual() |
evaluates actual as a functor returning a bool and taking no argument |
Important | |
---|---|
When passing expected directly as a shortcut mock::call is implied for a function, a function pointer, an instance of a type with a result_type member typedef (support for standard library, Boost.Bind, Boost.Function functors), an instance of a type with a sig member (support for Boost.Lambda functors), an instance of a type with a result member (support for Boost.Phoenix functors); mock::equal is implied for anything else. |
Warning | |
---|---|
Because mock::assign and mock::retrieve have side effects they may modify expected in unexpected ways. For instance they may be called again after their expectations have already been exhausted because of the way the expectation selection algorithm works. Therefore it is probably a good idea to use an action instead. |
Note | |
---|---|
For mock::assign and mock::retrieve the switch to one form or another is made depending on whichever is the most relevant based on types involved. |
Note | |
---|---|
All constraints accepting a parameter support the use of boost::ref and boost::cref in order to delay initialization. |
Note | |
---|---|
All constraints can be combined using the && and || operators, as well as negated with the ! operator. |
Example :
MOCK_CLASS( mock_class ) { MOCK_METHOD( method, 2, void( int, const std::string& ) ) }; BOOST_AUTO_TEST_CASE( demonstrates_adding_builtin_constraints ) { mock_class c; MOCK_EXPECT( c.method ).with( mock::equal( 3 ), mock::equal( "some string" ) ); MOCK_EXPECT( c.method ).with( 3, "some string" ); // equivalent to the previous one using short-cuts }
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 ); }
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 }
Example using Boost.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_boost_bind ) { mock_class c; MOCK_EXPECT( c.method ).with( boost::bind( &custom_constraint, 42, _1 ) ); }
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 ); }
Example using Boost.Phoenix :
MOCK_CLASS( mock_class ) { MOCK_METHOD( method, 1, void( int ) ) }; BOOST_AUTO_TEST_CASE( demonstrates_adding_a_custom_constraint_with_boost_phoenix ) { mock_class c; MOCK_EXPECT( c.method ).with( boost::phoenix::arg_names::arg1 == 42 ); MOCK_EXPECT( c.method ).with( boost::phoenix::arg_names::_1 == 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; } ); }
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( "" ) ); }
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 ); }
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 MOCK_MAX_SEQUENCES which defaults to 10. If needed the value can be increased before including the library :
#define MOCK_MAX_SEQUENCES 12 #include <turtle/mock.hpp>
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 }
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 MOCK_EXPECT( identifier ).throws( exception ); // stored internally by copy MOCK_EXPECT( identifier ).calls( functor ); // stored internally by copy, throws std::invalid_argument if empty
Note | |
---|---|
The returns and moves actions are not available for mock methods returning void, including constructors and destructors. |
Note | |
---|---|
Actions are captured by copy, boost::ref and boost::cref can however be used to turn the copies into references. |
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 ).returns( 42 ); MOCK_EXPECT( c.method ).moves( 42 ); // returns by moving the value MOCK_EXPECT( c.method ).throws( std::runtime_error( "error !" ) ); MOCK_EXPECT( c.method ).calls( &function ); // forwards 'method' parameter to 'function' MOCK_EXPECT( c.method ).calls( boost::bind( &function, 42 ) ); // drops 'method' parameter and binds 42 as parameter to 'function' MOCK_EXPECT( c.method ).calls( []( int i ) { return i; } ); // uses a C++11 lambda }
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( boost::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 }
Synopsis :
MOCK_VERIFY( identifier ); mock::verify( object ); // verifies all expectations for all methods of 'object' which must be an instance of a class created using MOCK_CLASS or MOCK_BASE_CLASS, or inherit mock::object mock::verify( functor ); // verifies all expectations for 'functor' which must be an instance of a functor created using MOCK_FUNCTOR mock::verify(); // verifies all expectations for all mock objects, functions and functors
Note | |
---|---|
These calls all return a boolean indicating whether the verification was successful or not, however usually simply calling them is enough because a failing verification will be logged to the test framework. |
Note | |
---|---|
Each mock object verifies itself automatically upon destruction, which is usually sufficient for the most common use cases. |
Warning | |
---|---|
Using mock functions or mock static member functions means the associated underlying objects will not be destroyed before exiting the test application, thus it is strongly suggested to verify (and possibly reset) them at the end of each test case (for instance using a fixture) to ensure that each test runs in isolation. |
Example :
MOCK_CLASS( mock_class ) { MOCK_METHOD( method, 0, void() ) }; BOOST_AUTO_TEST_CASE( demonstrates_verifying_a_mock_method ) { mock_class c; MOCK_VERIFY( c.method ); // logs an error and returns false if not all expectations are met mock::verify( c ); // verifies all expectations set for all methods of 'c' mock::verify(); // verifies all existing mock objects, functions and functors }
Example :
BOOST_AUTO_TEST_CASE( demonstrates_verifying_a_mock_functor ) { MOCK_FUNCTOR( f, void( int ) ); MOCK_VERIFY( f ); // logs an error and returns false if not all expectations are met mock::verify( f ); // behaves the same as MOCK_VERIFY mock::verify(); // verifies all existing mock objects, functions and functors }
Example :
MOCK_FUNCTION( f, 1, void( int ) ) BOOST_AUTO_TEST_CASE( demonstrates_verifying_a_mock_function ) { MOCK_VERIFY( f ); // logs an error and returns false if not all expectations are met mock::verify(); // verifies all existing mock objects, functions and functors }
Example :
MOCK_CLASS( mock_class ) { MOCK_STATIC_METHOD( method, 0, void() ) }; BOOST_AUTO_TEST_CASE( demonstrates_verifying_a_static_mock_method ) { mock_class c; MOCK_VERIFY( c.method ); // logs an error and returns false if not all expectations are met MOCK_VERIFY( mock_class::method ); // does the same mock::verify(); // verifies all existing mock objects, functions and functors }
Synopsis :
MOCK_RESET( identifier ); mock::reset( object ); // resets all expectations for all methods of 'object' which must be an instance of a class created using MOCK_CLASS or MOCK_BASE_CLASS, or inherit mock::object mock::reset( functor ); // resets all expectations for 'functor' which must be an instance of a functor created using MOCK_FUNCTOR mock::reset(); // resets all expectations for all mock objects, functions and functors
Example :
MOCK_CLASS( mock_class ) { MOCK_METHOD( method, 0, void() ) }; BOOST_AUTO_TEST_CASE( demonstrates_resetting_a_mock_method ) { mock_class c; MOCK_RESET( c.method ); // resets all expectations set for 'c.method' mock::reset( c ); // resets all expectations set on 'c' mock::reset(); // resets all existing mock objects, functions and functors }
Example :
BOOST_AUTO_TEST_CASE( demonstrates_resetting_a_mock_functor ) { MOCK_FUNCTOR( f, void( int ) ); MOCK_RESET( f ); // resets all expectations set for 'f' mock::reset( f ); // behaves the same as MOCK_RESET mock::reset(); // resets all existing mock objects, functions and functors }
Example :
MOCK_FUNCTION( f, 1, void( int ) ) BOOST_AUTO_TEST_CASE( demonstrates_resetting_a_mock_function ) { MOCK_RESET( f ); // resets all expectations set for 'f' mock::reset(); // resets all existing mock objects, functions and functors }
Example :
MOCK_CLASS( mock_class ) { MOCK_STATIC_METHOD( method, 0, void() ) }; BOOST_AUTO_TEST_CASE( demonstrates_resetting_a_static_mock_method ) { mock_class c; MOCK_RESET( c.method ); // resets all expectations set for 'c::method' MOCK_RESET( mock_class::method ); // resets all expectations set for 'c::method' mock::reset(); // resets all existing mock objects, functions and functors }
This section presents a simple means of creating a new constraint.
Synopsis :
MOCK_CONSTRAINT( name, expected_1, expected_2, ..., expression ) // defines a constraint 'name' based on the given 'expression'
The expression manipulates a received parameter actual in order to implement the constraint, as well as extra optional arguments named expected_1, expected_2, ...
For compilers without support for variadic macros the alternate following macro must be used.
Synopsis :
MOCK_CONSTRAINT_EXT( name, arity, ( expected_1, expected_2, ... ), expression ) // defines a constraint 'name' based on the given 'expression'
Of course this macro is also available for compilers which support variadic macros.
Example without any extra argument :
MOCK_CONSTRAINT( any, true ) // this is how mock::any could be defined MOCK_CONSTRAINT( forty_two, actual == 42 ) // this defines a 'forty_two' constraint BOOST_AUTO_TEST_CASE( mock_constraint_0_arity ) { MOCK_FUNCTOR( f, void( int ) ); MOCK_EXPECT( f ).with( forty_two ); MOCK_EXPECT( f ).with( any ); }
or with the alternate more portable macro :
MOCK_CONSTRAINT_EXT( any, 0,, true ) // this is (almost) how mock::any is defined MOCK_CONSTRAINT_EXT( forty_two, 0,, actual == 42 ) // this defines a 'forty_two' constraint BOOST_AUTO_TEST_CASE( mock_constraint_0_arity ) { MOCK_FUNCTOR( f, void( int ) ); MOCK_EXPECT( f ).with( forty_two ); MOCK_EXPECT( f ).with( any ); }
Example with one extra argument :
MOCK_CONSTRAINT( equal, expected, actual == expected ) // this is how mock::equal could be defined MOCK_CONSTRAINT( near, expected, std::abs( actual - expected ) < 0.01 ) // this defines a 'near' constraint which can be used as 'near( 42 )' BOOST_AUTO_TEST_CASE( mock_constraint_1_arity ) { MOCK_FUNCTOR( f, void( int ) ); MOCK_EXPECT( f ).with( near( 42 ) ); MOCK_EXPECT( f ).with( equal( 42 ) ); }
or with the alternate more portable macro :
MOCK_CONSTRAINT_EXT( equal, 1, ( expected ), actual == expected ) // this is how mock::equal is defined MOCK_CONSTRAINT_EXT( near, 1, ( expected ), std::abs( actual - expected ) < 0.01 ) // this defines a 'near' constraint which can be used as 'near( 42 )' BOOST_AUTO_TEST_CASE( mock_constraint_1_arity ) { MOCK_FUNCTOR( f, void( int ) ); MOCK_EXPECT( f ).with( near( 42 ) ); MOCK_EXPECT( f ).with( equal( 42 ) ); }
Example with two extra arguments :
MOCK_CONSTRAINT( near, expected, tolerance, std::abs( actual - expected ) < tolerance ) // this is how mock::near could be defined BOOST_AUTO_TEST_CASE( mock_constraint_2_arity ) { MOCK_FUNCTOR( f, void( int ) ); MOCK_EXPECT( f ).with( near( 42, 0.001 ) ); }
or with the alternate more portable macro :
MOCK_CONSTRAINT_EXT( near, 2, ( expected, tolerance ), std::abs( actual - expected ) < tolerance ) // this is how mock::near is defined BOOST_AUTO_TEST_CASE( mock_constraint_2_arity ) { MOCK_FUNCTOR( f, void( int ) ); MOCK_EXPECT( f ).with( near( 42, 0.001 ) ); }