[/
 / Copyright (c) 2014 Mathieu Champlon
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]

[section Getting Started]
[import example/getting_started.cpp]

This section introduces most of the library features in a series of use cases built on the example from the [link turtle.motivation motivation] section.

For all the code examples the following is assumed :

[prerequisite]

[section Create, expect, trigger, verify]

A simple unit test with mock objects usually splits into several phases as illustrated by :

[phases]

Triggering the object under test in turn calls methods on the mock objects, and any unexpected call raises an error.

Mock objects are automatically verified during their destruction and an error is signalled if any unfulfilled expectation remains.

More sophisticated tests sometimes require more complex use cases and in particular might need to verify or reset mock objects.

Here is an example highlighting the different possibilities :

[verify_reset]

Note that all verifications upon destruction will be disabled if the mock objects are destroyed in the context of an exception being raised.

[endsect]

[section Expectation selection algorithm]

A method can be configured with several expectations, for instance :

[expectations]

Each method call is then handled by processing the expectations in the order they have been defined :

# looking for a match with valid parameter constraints evaluated from left to right
# checking that the invocation count for this match is not exhausted

An error is raised if none can be found.

By default the relative order of the calls does not matter. It can however be enforced :

[sequence]

Therefore an error will be issued if the second expectation is matched before the first one has been exhausted.

An expectation can be part of several sequences :

[several_sequences]

[endsect]

[section Error diagnostic]

During the execution of a test case, an error can happen for one of the following reasons :

* unexpected call when no match can be found for the given arguments (typically logs an error and throws an exception)
* sequence failure when an enforced call sequence has not been followed (typically logs an error and throws an exception)
* verification failure if a remaining match has not been fulfilled upon manual verification (typically logs an error)
* untriggered expectation if a remaining match has not been fulfilled when destroying the mock object (typically logs an error)
* missing action if a method supposed to return something else than void has not been configured properly (typically logs an error and throws an exception)

The exact type of the exception thrown depends on the [link turtle.customization.test_framework_integration test framework integration] used.

An error log typically looks like :

 unknown location(0): error in "zero_plus_zero_is_zero": unexpected call: v.mock_view::display( 0 )
 v once().with( 1 )
 v once().with( 2 )
 . once().with( 3 )

On the first line is the description of what happened : here the display method of object v of class mock_view has been called with an actual value of 0.

The following lines list the set expectations with the check (the v character) meaning the expectation has been exhausted.
It therefore means that the two first expectations have been fulfilled by two calls, and then instead of 3 in the third call 0 has been erroneously passed on to the mock object.

Another common error looks like :

 src/tests/turtle_test/Tutorial.cpp(73): error in "zero_plus_zero_is_zero": untriggered expectation: v.mock_view::display
 v once().with( 1 )
 v once().with( 2 )
 . once().with( 3 )

The first line tells that a set expectation has not been fulfilled. The file and line number give the location where the corresponding expectation has been configured.

The following lines once again list the set expectations.
It means the two first calls correctly passed the expected values to the mock object, but then no third call happened.

Finally an error looking like :

 src/tests/turtle_test/Tutorial.cpp(73): error in "zero_plus_zero_is_zero": missing action: v.mock_view::display( 0 )
 v once().with( 0 )

indicates that an [link turtle.reference.expectation.actions action] is missing because a mock function must be told what to do when called if it has a return type other than void, for instance given :

[action_view]

the following test case will raise a missing action error :

[action_test]

[endsect]

[endsect]
