Download News Support Project

PrevUpHomeNext

Reference

Creation
Class
Member function
Static member function
Constructor
Destructor
Conversion operator
Function
Functor
Expectation
Invocation
Constraints
Sequence
Actions
Verification
Reset
Constraint

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 :

  • classes
  • functors
  • functions

Creating a mock object involves two parts under the hood :

  • defining an object
  • declaring an identifier for manipulating the object

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] 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 :

  • the object acts as a composite to verify and reset all the expectations for all its methods at once
  • logs involving the object are enhanced because configuring an expectation for a method will set the class name for all the other methods as well

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] Note

If the identifier is omitted it will default to the method name.

[Note] 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] Note

The signature cannot be omitted for the _TPL familly of macros, see the related limitation section.

[Note] Note

Constructors, destructors and conversion operators require special care.

[Note] Note

In case of a calling convention specified, all four parameters must be provided.

[Warning] 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 [@http://www.boost.org/libs/utility/identity_type/doc/html/index.html 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 :

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

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] 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] Note

In case of a calling convention specified, all four parameters must be provided.

[Warning] 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 :

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

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] 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 :

MOCK_CLASS( mock_class )
{
    MOCK_CONSTRUCTOR( __attribute((stdcall)) mock_class, 0, (), constructor )
};

Synopsis :

MOCK_DESTRUCTOR( [calling convention] ~name, identifier )
[Note] 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 :

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

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 :

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

Synopsis :

MOCK_FUNCTION( [calling convention] name, arity, signature[, identifier] ) // if 'identifier' is omitted it will default to 'name'
[Note] 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] Note

In case of a calling convention specified, all four parameters must be provided.

[Warning] 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 :

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

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] 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

compares actual 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 boolean

mock::negate

! actual

negates actual using operator !

mock::evaluate

actual()

evaluates actual as a functor returning a bool and taking no argument

[Important] 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] 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] 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] Note

All constraints accepting a parameter support the use of boost::ref and boost::cref in order to delay initialization.

[Note] 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] Note

The returns and moves actions are not available for mock methods returning void, including constructors and destructors.

[Note] 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] 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] Note

Each mock object verifies itself automatically upon destruction, which is usually sufficient for the most common use cases.

[Warning] 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 ) );
}


PrevUpHomeNext